Skip to content

Using AWS Secrets Manager Secrets

By default, the WSO2 Integrator: MI is configured to use WSO2 secure vault for encrypting secrets, which stores the encrypted secrets inside the MI distribution. If your secrets are already managed centrally in AWS Secrets Manager, you can plug AWS Secrets Manager into the WSO2 Integrator: MI as a secret repository instead, using the carbon-securevault-aws extension.

AWS Secrets Manager secrets can be used in both server configurations (the deployment.toml file) and synapse configurations.

The extension can be configured in two ways:

Mode Description
Novel (multiple repositories) AWS Secrets Manager is registered alongside the built-in WSO2 secure vault. Each secret reference names the repository it comes from (for example, vault:aws:my-secret), so you can use both vaults in the same server.

Recommended for most deployments.
Legacy (single repository) AWS Secrets Manager completely replaces the built-in WSO2 secure vault implementation. Secret references stay as plain aliases (for example, my-secret), but every secret must then come from AWS Secrets Manager.

Use this if you are migrating existing configurations and do not want to change every secret reference.

Before you begin

  • Create the required secrets in AWS Secrets Manager. The secret name you use in AWS is the alias you will refer to from the WSO2 Integrator: MI.

    Note

    The extension retrieves the secret string as it is stored. Store the value as a plaintext secret (not a key/value JSON secret) so that the retrieved value is the secret itself.

  • Make sure the identity that the WSO2 Integrator: MI authenticates with has permission to call secretsmanager:GetSecretValue on those secrets.

  • Decide which AWS credential provider the WSO2 Integrator: MI should use to authenticate into AWS.

Step 1: Install the extension

Download the org.wso2.carbon.securevault.aws-1.1.1.jar file and copy it to the dropins folder of your WSO2 Integrator: MI distribution (<MI_HOME>/dropins).

Note

Use version 1.1.1 or later with the WSO2 Integrator: MI. Earlier versions depend on Carbon Kernel classes that are not shipped with the MI runtime.

The AWS SDK classes required by the extension are bundled inside this JAR, so no additional libraries are needed.

Step 2: Configure the secret repository

Open the secret-conf.properties file (stored in the <MI_HOME>/conf/security folder) and add the configurations given below for the mode you selected.

Note

All the properties in this file are commented out by default. Add the following configurations as new (uncommented) lines.

keystore.identity.location=repository/resources/security/wso2carbon.jks
keystore.identity.type=JKS
keystore.identity.alias=wso2carbon
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
secretProviders=vault
secretProviders.vault.provider=org.wso2.securevault.secret.repository.VaultSecretRepositoryProvider
secretProviders.vault.repositories=aws,<OTHER_REPOSITORIES_IF_ANY>
secretProviders.vault.repositories.aws=org.wso2.carbon.securevault.aws.secret.repository.AWSSecretRepository
secretProviders.vault.repositories.aws.properties.awsregion=<AWS_REGION>
secretProviders.vault.repositories.aws.properties.credentialProviders=<CREDENTIAL_PROVIDER_TYPE>
secretProviders.vault.repositories.aws.properties.encryptionEnabled=false

Note

encryptionEnabled must be set to false in the novel mode. Encryption of stored secrets is only supported in the legacy mode.

Tip

List any other secret repositories you use alongside aws in the secretProviders.vault.repositories property, or remove the placeholder if AWS Secrets Manager is the only one.

keystore.identity.location=repository/resources/security/wso2carbon.jks
keystore.identity.type=JKS
keystore.identity.alias=wso2carbon
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.aws.secret.repository.AWSSecretRepositoryProvider
secretRepositories.vault.properties.awsregion=<AWS_REGION>
secretRepositories.vault.properties.credentialProviders=<CREDENTIAL_PROVIDER_TYPE>
secretRepositories.vault.properties.encryptionEnabled=<ENCRYPTION_ENABLED>
Parameter Description
awsregion The AWS region in which the AWS Secrets Manager holding your secrets is deployed. For example, us-east-2.
credentialProviders The credential provider type used to authenticate the WSO2 Integrator: MI into AWS. Possible values are env, ecs, ec2, cli, and k8sServiceAccount. You can specify multiple values as a comma-separated list to build an authentication chain that is evaluated in the given order. If the value is left empty or is invalid, the AWS default credential provider chain is used. See Step 3 for details.
encryptionEnabled Specify true or false. If set to true, the secrets stored in AWS Secrets Manager (except the root passwords) must be encrypted beforehand using the Cipher Tool, and the encrypted value is what you store in AWS. This must be false when the novel mode is used.

Step 3: Set up AWS credentials

The credentialProviders property selects how the WSO2 Integrator: MI authenticates into AWS.

Value Description
env Uses the EnvironmentVariableCredentialsProvider to load credentials from the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables.
ecs Uses the ContainerCredentialsProvider to load credentials from a local metadata service using the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable.
ec2 Uses the InstanceProfileCredentialsProvider to load credentials from the Amazon EC2 metadata service.
cli Uses the ProfileCredentialsProvider to load credentials from the credential profile file in the default location (~/.aws/credentials) with the default profile name. Use this if you are logged in to AWS using the AWS CLI.
k8sServiceAccount Uses the WebIdentityTokenFileCredentialsProvider to load credentials from a web identity token file. Use this when the WSO2 Integrator: MI is deployed on an AWS EKS cluster and authenticates using a Kubernetes service account. For more information, see IAM roles for service accounts on EKS.
(empty) Uses the DefaultCredentialsProvider chain.

Examples:

# Single credential provider type
secretProviders.vault.repositories.aws.properties.credentialProviders=env

# Multiple credential provider types, evaluated in order
secretProviders.vault.repositories.aws.properties.credentialProviders=env,ecs,ec2

Be sure to set the environment variables required by the credential provider you selected. For example, if you select env, the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables must be set before starting the server.

Accessing AWS secrets in server configurations

Once the WSO2 Integrator: MI is connected to AWS Secrets Manager, you can refer to the secrets from the deployment.toml file (stored in the <MI_HOME>/conf folder) using the $secret{alias} placeholder.

  1. Enable runtime secrets by adding the following section to the deployment.toml file. This tells the configuration parser to leave the $secret{...} placeholders unresolved at startup so that they are resolved from the vault at runtime.

    [runtime_secrets]
    enable = "true"
    
  2. Replace the plain-text values with secret references.

    [super_admin]
    username = "admin"
    password = "$secret{vault:aws:admin-password}"
    
    [keystore.primary]
    file_name = "wso2carbon.jks"
    password = "$secret{vault:aws:keystore-password}"
    
    [truststore]
    file_name = "client-truststore.jks"
    password = "$secret{vault:aws:truststore-password}"
    type = "JKS"
    

    The reference takes the form $secret{<provider>:<repository>:<secret-name>}, where vault is the provider name and aws is the repository name configured in the secret-conf.properties file.

    [super_admin]
    username = "admin"
    password = "$secret{admin-password}"
    
    [keystore.primary]
    file_name = "wso2carbon.jks"
    password = "$secret{keystore-password}"
    
    [truststore]
    file_name = "client-truststore.jks"
    password = "$secret{truststore-password}"
    type = "JKS"
    

The alias (for example, admin-password) is the name of the secret stored in AWS Secrets Manager.

Accessing AWS secrets in synapse configurations

You can refer to AWS secrets from your integration artifacts using the vault lookup function, in the same way you would refer to a WSO2 secure vault secret.

<variable name="password" expression="${wso2-vault('vault:aws:mysql-password')}"/>
<variable name="password" expression="${wso2-vault('mysql-password')}"/>

If you are using the older XPath-based expression syntax, the alias is the same as above for the mode you configured:

<property name="password" expression="wso2:vault-lookup('vault:aws:mysql-password')"/>
<property name="password" expression="wso2:vault-lookup('mysql-password')"/>

In a data service, the datasource password uses the vault lookup function enclosed in curly braces:

<password>{wso2:vault-lookup('vault:aws:dbpassword')}</password>
<password>{wso2:vault-lookup('dbpassword')}</password>

Note

The whole element value must be the lookup expression. The password is resolved when the data service is deployed, not per request. See Limitations.

Retrieving a specific version of a secret

Referring to a secret by its name alone retrieves the latest version of the secret. To retrieve a specific version, append the version ID to the alias using a # delimiter.

[keystore.primary]
file_name = "wso2carbon.jks"
password = "$secret{vault:aws:keystore-password#9d21179b-cd37-4174-a65a-7d1cea075dcd}"

The same delimiter applies in synapse configurations:

<variable name="password" expression="${wso2-vault('vault:aws:mysql-password#9d21179b-cd37-4174-a65a-7d1cea075dcd')}"/>

Note

Only a version ID can be used after the # delimiter. Staging labels such as AWSPREVIOUS are not supported.

Retrieving the keystore passwords from AWS Secrets Manager

By default, the keystore and private key passwords (the secure vault root passwords) are read from the password-tmp/password-persist file in the <MI_HOME> directory, or prompted for on the command line. You can configure the WSO2 Integrator: MI to retrieve these passwords from AWS Secrets Manager instead.

  1. In the secret-conf.properties file, change the secret provider of the keystore passwords to the AWS callback handler and add the aliases of the secrets that hold them.

    keystore.identity.store.secretProvider=org.wso2.carbon.securevault.aws.secret.handler.AWSSecretCallbackHandler
    keystore.identity.key.secretProvider=org.wso2.carbon.securevault.aws.secret.handler.AWSSecretCallbackHandler
    keystore.identity.store.alias=<IDENTITY_KEYSTORE_PASSWORD_ALIAS>
    keystore.identity.key.alias=<PRIVATE_KEY_ALIAS>
    

    Keep the rest of the configuration from Step 2 unchanged.

  2. Create the secrets in AWS Secrets Manager with the names used for <IDENTITY_KEYSTORE_PASSWORD_ALIAS> and <PRIVATE_KEY_ALIAS>.

Note

Root passwords are never encrypted with the Cipher Tool, even when encryptionEnabled is set to true. Store them in AWS Secrets Manager as plain values.

Enabling debug logs

To troubleshoot the connection between the WSO2 Integrator: MI and AWS Secrets Manager, enable debug logs for the extension.

  1. Add the following lines to the log4j2.properties file (stored in the <MI_HOME>/conf folder).

    logger.org-wso2-carbon-securevault-aws.name=org.wso2.carbon.securevault.aws
    logger.org-wso2-carbon-securevault-aws.level=DEBUG
    logger.org-wso2-carbon-securevault-aws.additivity=false
    logger.org-wso2-carbon-securevault-aws.appenderRef.CARBON_CONSOLE.ref=CARBON_CONSOLE
    
  2. Append org-wso2-carbon-securevault-aws to the loggers list in the same file.

    loggers = AUDIT_LOG, SERVICE_LOGGER, API_LOGGER, ... , org-wso2-carbon-securevault-aws
    

Limitations

  • AWS Secrets Manager does not provide a caching mechanism, and secrets are fetched on demand when they are requested. Secrets referenced from mediation logic (such as the vault lookup function) therefore pick up updated values at runtime, subject to the mediation-level cache duration.
  • Secrets referenced from artifacts that are resolved at deployment time — such as data sources, message stores, message processors, and inbound endpoints — are resolved once when the artifact is deployed. Updating the secret in AWS Secrets Manager is not reflected until the artifact is redeployed or the server is restarted. This is the same behaviour as with the built-in WSO2 secure vault.
  • Encryption of stored secrets (encryptionEnabled=true) is supported only in the legacy mode.