In this blog, I will discuss the concept of a simple REST API for manipulating the contents of the secure vault of the WSO2 Enterprise Integrator through the SOAP admin services and how to set it up. This can for example be used in a situation where values need to be set dynamically during automatic deployment of a new environment. In this case, it is great to have a REST API securely available to expose the AdminServices. This blog is based on WSO2 Enterprise Integrator 6.2.0.
Secure vault
To be able to change values inside the secure vault remotely, you need to have access to the AdminServices WSDLS inside the WSO2 Enterprise Integrator. These WSDLs describe a set of SOAP webservices that can be used to manipulate various configurations of the product as well as in our case, adding and removing secure vault entries for encrypted entries. The WSDLs are hidden by default so we first need to unhide them through a configuration change.
To do this, you have to open the carbon.xml file located inside the conf folder of the product and search for an XML element called “HideAdminServiceWSDLs” and set the value to “false”. Now (re)start the product.
You can now access the AdminServices WSDLs through their respective URLs (All URL’s listed on the page linked earlier). For example to use the PropertiesAdminService that we need for our API, we can access the https://<hostname>:8243/services/PropertiesAdminService?wsdl to retrieve the necessary WSDL.
If you want, you can load the WSDL into a program like SOAPUI to see all the available messages and operations in a more readable way.
As you can see, this AdminService has various operations attached so it can be used for manipulating properties inside the product.
For the API, we will only use the setProperty and removeProperty function. If you’re looking for a training example, you could try to add an API resource for updating a property as well using the updateProperty operation.
The API
Write an API consisting of a PUT and DELETE resource for their respective functionalities.
The way you protect this API is your choice, you can for example use some degree of basic authentication to verify the user can access the API. (I.e. username/password).
We will call the API SecureVaultAdmin while using the context “/secrets” with two resources, one PUT resource and one DELETE resource.
The PUT resource will expect the identifier of the secret at the end of the URL like in a GET request and the secret value to be inside the message body as the “<secret>secretValue</secret>” element.
<resource methods=”PUT” uri-template=”/{secretID}”>
It will look like this:
For the DELETE resource there only needs to be the identifier inside the URL, no message body.
<resource methods="DELETE" uri-template="/{secretID}">
The API PUT flow
The PUT will be built up in two stages; first the message body must be encrypted and afterwards it can be sent to the secure vault.
First, we create a message with the doEncrypt element so we can encrypt the password we received in plaintext.
<xsd:doEncrypt xmlns_xsd="http://org.apache.synapse/xsd">
<xsd:plainTextPass>plaintextpassword</xsd:plainTextPass>
</xsd:doEncrypt>Second, this message must be sent to the following endpoint.
<http method="POST" uri-template="https://<hostname>:9443/services/MediationSecurityAdminService.MediationSecurityAdminServiceHttpsSoap11Endpoint"/>This MediationSecurity AdminService will return the password in encrypted form and we’ll put it inside a new message to look like this:
<ser:setProperty>
<ser:path>/_system/config/repository/components/secure-vault</ser:path> <ser:name>firstSecret</ser:name> <ser:value>CED3+3U73DO8/CJ9s/oWaiFzfKioRcWkbyHKT1ZDtik1mPntz79ZbRKqB6MTP7AsKcPAcz241cEcbRg89H8IjAa3PHISaJTU+sxC2PyXI8TfAH9GTuxenE2zxXvf+zJ+RUvjH8+U9uQyjCN6qs0bmahf
2cuBU1WK8rqd+NHF0juCbUJbft/mi2UJY0arKClJ+0dwKwEeMrj3Z9AokNbsNL/DZbNEM1riSt8jdJdnvIuw1qcJtokYuSXmBCgq1vABOTw4jWvAEUsjcMddrzxsdTpDmBh1KBWclPqkiF1G5N7I1zPDau/+KAX+QeGWmrcoKgoBwoH50J0uoN7zWx/zeg==</ser:value>< /ser:setProperty>And send it to the property adminservice endpoint.
<http method="POST" uri-template="https://localhost:9443/services/PropertiesAdminService.PropertiesAdminServiceHttpsSoap11Endpoint"/>Now you can check out the secure vault screen and the value should have shown up there like this:
DELETE API resource source code
The DELETE resource is very simple, it will have to create a DELETE message with the secretID specified in the request and send it to the below endpoint. The formatting for the message can be found in the WSDL we retrieved earlier.
<http method="POST" uri-template="https://localhost:9443/services/PropertiesAdminService.PropertiesAdminServiceHttpsSoap11Endpoint"/> This call will cause the related secret to be deleted from the secure vault.
So, that’s how you can manipulate the secure vault inside the WSO2 Enterprise Integrator / Enterprise Server Bus. Of course there are many more options so try to play around with it a little if you have time. I hope this helps you with your WSO2 Enterprise Integrator / Enterprise Server Bus project. If you have any questions, don’t hesitate to ask them in the comments below!
