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. Novel (multiple repositories)Legacy (single repository) 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. 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" Replace the plain-text values with secret references. Novel (multiple repositories)Legacy (single repository) [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. Novel (multiple repositories)Legacy (single repository) <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: Novel (multiple repositories)Legacy (single repository) <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: Novel (multiple repositories)Legacy (single repository) <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. 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. 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. 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 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.