WSO2 ESB Tutorial: How to programmatically manage Secure Vault passwords

When we need to store encrypted passwords for our integrations we use the Secure Vault implementation shipped with the WSO2 products.

The WSO2 Documentation shows us how to add our passwords using the Carbon Management Console.

In a Continuous Integration/Continuous Delivery infrastructure we need a mechanism for add these vault entries automatically. Let’s see how this can be done using the Admin Services.

Prerequisites

1. Download and unzip the WSO2 Enterprise Integrator 6.4.0 from official site. We’ll call <EI_HOME> to this folder in this post.
2. Enable the WSDLs of the Admin Services. For that set the <HideAdminServiceWSDLs> element to false in the <EI_HOME>/conf/carbon.xml.
3. We need to configure the Cipher Tool in the WSO2 EI server before use the security vault:
   1. Open a terminal and navigate to the <EI_HOME> directory
   2. Execute bin/ciphertool.sh -Dconfigure
   3. You’ll need to enter the primary keystore password of Carbon server (wso2carbon by default)
4. Finally, start the ESB profile of the WSO2 EI server executing bin/integrator.sh
   1. Again, you will be asked to enter the primary keystore password of Carbon server (You can avoid entering the password manually following this procedure in WSO2 Documentation)

Note: For this tutorial we have used the following product versions:

• macOS Mojave v 10.14.1
• WSO2 Enterprise Integrator 6.4.0
• SoapUI 5.4.0

Configuration to manage Secure Vault passwords programmatically

A bit of theory

First, we need to understand how passwords are stored so we can know which Admin Services we need to use.

Secure Vault passwords are stored in the Configuration repository of the Registry. They are stored as properties in the entry: 

/_system/config/repository/components/secure-vault

The name is the alias of the password and the value is the encrypted password:

So, we will use Admin Services:

1. MediationSecurityAdminService: For encrypt the passwords.

                 WSDL: https://localhost:9443/services/MediationSecurityAdminService?wsdl

2. PropertiesAdminService: With this service, we will add, remove or modify properties of the registry entry to manage our passwords.

                 WSDL: https://localhost:9443/services/PropertiesAdminService?wsdl

These SOAP services need Basic Authentication of a user belonging to the admin role (default admin user and password are admin/admin). We will use SoapUI for our sample calls.

Add a password

We are going to create the password “my.password” with the alias my-key.

First we are going to encrypt the password using the doEncrypt operation of the service MediationSecurityAdminService.

This operation only needs as the password to encrypt as parameter:

With the password encrypted, we will call the setProperty oneWay operation of the PropertiesAdminService to set our key. The fields are:

• Path: The secure-vault entry path in the registry
• Name: Alias for the password
• Value: Encrypted password

The service will respond with a 202 Accepted response and we should see our key in the registry. For that, go to Registry > Browse in the main menu:

We can deploy the following custom Proxy Service to check the password:

<proxy xmlns="http://ws.apache.org/ns/synapse"

      name="VaultTest"

      transports="http https"

      startOnLoad="true">

  <description/>

  <target>

     <inSequence>

        <payloadFactory media-type="xml">

           <format>

              <info>

                 <my-key>$1</my-key>

              </info>

           </format>

           <args>

              <arg evaluator="xml" expression="wso2:vault-lookup('my-key')"/>

           </args>

        </payloadFactory>

        <respond/>

     </inSequence>

  </target>

</proxy>

If we try the service we can see how the password have been correctly set:

Modify a password

We could try now to modify our password, the new value will be “my.new.password”.

So first we encrypt this new password with the MediationSecurityAdminService:

With the password encrypted, we will call the updateProperty oneWay operation of the PropertiesAdminService to set our key. The fields are:

• Path: The secure-vault entry path in the registry
• Value: Encrypted password
• Name and Old Name: The service will delete the Old Name property and create the Name property. So we will set both to my-key to update the value.

The service will respond with a 202 Accepted response and we should see our key updated in the registry:

If we try the service our VaultTest proxy service we should see how the password have been updated:

Delete a password

Finally we will remove the password from the Vault. For that we just need to use the removeProperty oneWay operation of the PropertiesAdminService. The input params are:

• Path: The secure-vault entry path in the registry
• Name: Alias to delete

The service will respond with a 202 Accepted response and we should not see our key in the registry anymore:

If we try the service our VaultTest proxy service we should see how we do not get any value for the my-key alias:

Conclusion

With these two Admin Services you have the tools to programmatically manage your Secure Vault passwords and to integrate it in any process you need.

As an example in the real world, you could use these services in continuous integration and continuous deployment (CI/CD) processes to populate the WSO2 Secure Vault with secrets from your corporate Vault.