Integrate with HashiCorp Vault¶

Using HashiCorp Vault extension, you can set up HashiCorp Vault to store passwords that are mapped to aliases instead of the actual passwords. When setting up HashiCorp Vault with APIM you can use either of the following authentication methods, based on your requirement.

Using Root Token authentication
Using App-Role authentication

Setting up using Root Token authentication¶

This method uses a static root token to authenticate with HashiCorp Vault, providing direct and full access to Vault's secrets.

Step 1 - Setup HashiCorp Vault¶

Start the HashiCorp Vault server and create a new KV engine. Enter a path name when creating the kv engine (e.g., wso2apim). The following commands can be used to add secrets with the HashiCorp Vault.

# Create a new kv engine
vault secrets enable -path=wso2apim -version=2 kv

# Add new secret
vault kv put wso2apim/admin_password value=admin

# Get a secret (To check)
vault kv get -field=value wso2apim/admin_password

Step 2 - Configure HashiCorp Vault extension¶

Clone HashiCorp Vault extension repo.
Build the HashiCorp Vault Integration OSGI bundle using mvn clean install command and copy the target/org.wso2.carbon.securevault.hashicorp-1.0.jar file to the <API-M_HOME>/repository/components/dropins/ directory.
Add HashiCorp Vault Java Driver (e.g., vault-java-driver-5.1.0.jar) to the <API-M_HOME>/repository/components/lib/ directory.

Create the <API-M_HOME>/repository/conf/security/secret-conf.properties file and set the following configurations.

keystore.identity.location=repository/resources/security/wso2carbon.jks
keystore.identity.type=JKS
keystore.identity.store.password=identity.store.password
keystore.identity.store.secretProvider=org.wso2.carbon.securevault.DefaultSecretCallbackHandler
keystore.identity.key.password=identity.key.password
keystore.identity.key.secretProvider=org.wso2.carbon.securevault.DefaultSecretCallbackHandler
carbon.secretProvider=org.wso2.securevault.secret.handler.SecretManagerSecretCallbackHandler

secVault.enabled=true
secretRepositories=vault
secretRepositories.vault.provider=org.wso2.carbon.securevault.hashicorp.repository.HashiCorpSecretRepositoryProvider
secretRepositories.vault.properties.address=http://127.0.0.1:8200
secretRepositories.vault.properties.namespace=ns1
secretRepositories.vault.properties.enginePath=wso2apim
secretRepositories.vault.properties.engineVersion=2
secretRepositories.vault.properties.authType=ROOT_TOKEN

Note

In production, you should always use the vault address with TLS enabled.

Add the following lines to the <API-M_HOME>/repository/conf/log4j2.properties file.

logger.org-wso2-carbon-securevault-hashicorp.name=org.wso2.carbon.securevault.hashicorp
logger.org-wso2-carbon-securevault-hashicorp.level=INFO
logger.org-wso2-carbon-securevault-hashicorp.additivity=false
logger.org-wso2-carbon-securevault-hashicorp.appenderRef.CARBON_CONSOLE.ref = CARBON_CONSOLE

Then append org-wso2-carbon-securevault-hashicorp to the loggers list in the same file as follows.
```
loggers = AUDIT_LOG, trace-messages, ..., org-wso2-carbon-securevault-hashicorp
```

Step 3 - Update passwords with their aliases¶

Open the deployment.toml file in the <API-M_HOME>/repository/conf/ directory and add the [secrets] configuration section at the bottom of the file as shown below. Give an alias for the passwords and put the value as blank ("").
```
[secrets]
admin_password = ""
```
Add the encrypted password alias to the relevant sections in the deployment.toml file by using a placeholder: $secret{alias}. For example:
```
[super_admin]
username="admin"
password="$secret{admin_password}"
```

Step 4 - Start the server¶

Provide the VAULT_TOKEN to the prompted message in the console or by creating a new file in the <API-M_HOME> directory. The file should be named according to your Operating System.

LinuxWindows

The file name should be hashicorpRootToken-tmp.

The file name should be hashicorpRootToken-tmp.txt.

Note

When you add tmp to the file name, note that this will automatically get deleted from the file system after the server starts. Alternatively, if you want to retain the password file after the server starts, the file should be named as follows:

LinuxWindows

The file name should be hashicorpRootToken-persist.

The file name should be hashicorpRootToken-persist.txt.
Start the WSO2 API Manager Server and enter the keystore password at startup when prompted:
```
[Enter KeyStore and Private Key Password :] wso2carbon
```

Setting up using App-Role authentication¶

This method uses dynamic authentication based on role IDs and secret IDs, allowing for secure, scoped access to Vault without the need for storing static tokens.

Step 1 - Setup HashiCorp Vault¶

Start the HashiCorp Vault server and set the environment variables.

export VAULT_ADDR='https://127.0.0.1:8200'
export VAULT_TOKEN='xxxxxxxxxxxxxx'

Include the policy in the kv-read-write.hcl file as below.

path "wso2apim/data/*" {
    capabilities = ["create", "read", "update", "delete", "list"]
}

Upload the kv policy using the command below.

vault policy write kv-read-write kv-read-write.hcl

The following commands can be used to create the AppRole using the created policy.

vault auth enable approle

vault write auth/approle/role/my-role \
    token_policies="kv-read-write" \
    token_type="service" \
    token_ttl="24h" \
    token_max_ttl="72h"

Get the role-id as below.

vault read auth/approle/role/my-role/role-id

Get the secret-id as below.

vault write -f auth/approle/role/my-role/secret-id

Create the kv engine with a path name (e.g., wso2apim).

The following commands can be used to add secrets with the HashiCorp Vault.

# Create a new kv engine
vault secrets enable -path=wso2apim -version=2 kv

# Add new secret
vault kv put wso2apim/admin_password value=admin

# Get a secret (To check)
vault kv get -field=value wso2apim/admin_password

Step 2 - Configure HashiCorp Vault extension¶

Clone HashiCorp Vault extension repo.
Build the HashiCorp Vault Integration OSGI bundle using mvn clean install command and copy the target/org.wso2.carbon.securevault.hashicorp-1.0.jar file to the <API-M_HOME>/repository/components/dropin/ directory.
Add HashiCorp Vault Java Driver (e.g., vault-java-driver-5.1.0.jar) to the <API-M_HOME>/repository/components/lib/ directory.
Create the <API-M_HOME>/repository/conf/security/secret-conf.properties file and set the following configurations.

Note

In production, you should always use the vault address with TLS enabled.

Add the following lines to the <API-M_HOME>/repository/conf/log4j2.properties file.

logger.org-wso2-carbon-securevault-hashicorp.name=org.wso2.carbon.securevault.hashicorp
logger.org-wso2-carbon-securevault-hashicorp.level=INFO
logger.org-wso2-carbon-securevault-hashicorp.additivity=false
logger.org-wso2-carbon-securevault-hashicorp.appenderRef.CARBON_CONSOLE.ref = CARBON_CONSOLE

Then append org-wso2-carbon-securevault-hashicorp to the loggers list in the same file as follows.

loggers = AUDIT_LOG, trace-messages, ..., org-wso2-carbon-securevault-hashicorp

Step 3 - Update passwords with their aliases¶

Open the deployment.toml file in the <API-M_HOME>/repository/conf/ directory and add the [secrets] configuration section at the bottom of the file as shown below. Give an alias for the passwords and put the value as blank ("").
```
[secrets]
admin_password = ""
```
Add the encrypted password alias to the relevant sections in the deployment.toml file by using a placeholder: $secret{alias}. For example:
```
[super_admin]
username="admin"
password="$secret{admin_password}"
```

Step 4 - Start the server¶

Provide the Secret ID to the prompted message in the console or by creating a new file in the <API-M_HOME> directory. The file should be named according to your Operating System.

LinuxWindows

The file name should be hashicorpSecretId-tmp.

The file name should be hashicorpSecretId-tmp.txt.

Note

When you add tmp to the file name, note that this will automatically get deleted from the file system after the server starts. Alternatively, if you want to retain the password file after the server starts, the file should be named as follows.

LinuxWindows

The file name should be hashicorpSecretId-persist.

The file name should be hashicorpSecretId-persist.txt.

Start the WSO2 API Manager Server and enter the keystore password at startup when prompted.
```
[Enter KeyStore and Private Key Password :] wso2carbon  
```