Using HashiCorp Secrets

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:
  
  • Static Token authentication
  • AppRole Pull authentication 

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 \lib folder of your ESB (<EI_HOME>/lib).
  

  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 <EI_HOME>/conf/security folder).

<secureVaults>
    <!-- Uncomment this and configure as appropriate for HashiCorp secure vault support -->
    <vault name="hashicorp">
        <!-- Server address to be used in the http communication -->
        <parameter name="address">http://127.0.0.1:8200</parameter>
        <!-- Server address to be used in the https communication -->
        <parameter name="address">https://127.0.0.1:8200</parameter>
        <!-- Root token parameter for authenticate with the HashiCorp vault server-->
        <parameter name="rootToken">root_token</parameter>
        <!-- roleId and secretId parameter used to AppRole Pull authenticatation with the HashiCorp vault server -->
        <parameter name="roleId">ROLE_ID</parameter>
        <parameter name="secretId">SECRET_ID</parameter>
        <!-- All resources fetched from the HashiCorp vault would be cached for this number of milliseconds -->
        <parameter name="cacheableDuration">15000</parameter> 
        <!-- Version of the HashiCorp secret engine -->
        <parameter name="engineVersion">2</parameter>
        <!-- HashiCorp namespace across the runtime -->
        <parameter name="namespace">namespace</parameter> 
        <!-- SSL configuration. By defaults truststore and keystore files are pointed to the default WSO2 JKS files. 
             Can define paths as both absolute or relative to the ${carbon.home} -->
        <parameter name="trustStoreFile">${carbon.home}/repository/resources/security/client-truststore.jks</parameter> 
        <parameter name="keyStoreFile">${carbon.home}/repository/resources/security/wso2carbon.jks</parameter>
        <parameter name="keyStorePassword">key_store_password</parameter>
    </vault> 
</secureVaults>

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:

<property name="HashiCorpSecret" expression="hashicorp:vault-lookup('path-name', 'field-name') />

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

• Payload:

  <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://org.apache.synapse/xsd">
     <soapenv:Header/>
     <soapenv:Body>
        <xsd:setSecretIdForHashiCorpVault>
           <xsd:secretId>new_secret_id</xsd:secretId>
        </xsd:setSecretIdForHashiCorpVault>
     </soapenv:Body>
  </soapenv:Envelope>

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.

<property name="HashiCorpSecret" expression="hashicorp:vault-lookup('namespace', 'path-name', 'field-name') />