This feature is available as a product update from 27/10/2020 onwards. If you don't already have this update, you can get the latest updates now.
The ESB profile of WSO2 EI is, by default, configured to use WSO2 secure vault for encrypting secrets. However, you may encounter certain limitations if you use secrets with a large number of characters. You can overcome this issue by using HashiCorp secrets.
Note that HashiCorp secrets are only applicable to synapse configurations. For server configurations, you can continue using WSO2 secure vault.
Before you begin
- Generate the required secrets in your HashiCorp vault.
- Select the server authentication method that you want to use when connecting the ESB with HashiCorp. There are two authentication methods available for HashiCorp:
If you select Static Token authentication, you need to generate a tokenID from HashiCorp. If you select AppRole Pull authentication, you need to generate a secret ID and role ID. See the HashiCorp documentation for details and instructions.
Copy the vault-java-driver to the
\libfolder of your ESB (
Vault driver version 5.1.0 is tested with the ESB profile of WSO2 EI.
Connecting the ESB to the HashiCorp server
Once you have set up the secrets in the HashiCorp server, you can configure the ESB profile to connect with HashiCorp.
Add the following configurations to the
external-vaults.xml file (stored in the
Be sure to apply the security tokens relevant to the authentication method you are using.
Accessing HashiCorp secrets in synapse configurations
Once your ESB is connected to HashiCorp, you can point to the secrets stored in the HashiCorp vault from your synapse configurations.
Given below is a sample synapse property that uses a HashiCorp secret:
Renewing security token (AppRole-pull method)
When you generate the secret ID from HashiCorp (for enabling AppRoll-pull authentication), you have the option of limiting the number of times the secret ID token can be used. This is done using the
secret_id_num_uses parameter in HashiCorp. In this case, the secret ID will expire after it is used for the specified number of times.
In such situations, you need to regenerate a secret ID from HashiCorp and apply it to the
external-vaults.xml file in the ESB. However, you need to restart the ESB before
using the new secret token, which means, there will be a server downtime.
If you want to update the secret token dynamically without restarting the server, you can use the following admin service in the ESB. As shown below, you can send a request to the given URL with the new secret ID (specified in the sample payload).
- Service URL: https://HOST:9443/services/MediationSecurityAdminService?wsdl
- Operation: setSecretIdForHashiCorpVault
Using Namespaces for the HashiCorp connection
Namespace support is available only in the Enterprise edition of HashiCorp.
You can add a global namespace value in the
external-vaults.xml file. See the instructions on connecting the ESB with HashiCorp. You can also use namespace values per request in synapse configurations as shown below.