Sync secrets from Vault to AWS Secrets Manager

The AWS Secrets Manager destination enables Vault to sync and unsync secrets of your choosing into an external AWS account. When configured, Vault will actively maintain the state of each externally-synced secret in near-realtime. This includes sending new secrets, updating existing secret values, and removing secrets when they either get dissociated from the destination or deleted from Vault. This enables the ability to keep control of all your secrets localized while leveraging the benefits of the AWS Secrets Manager.

Prerequisites:

Ability to read or create KVv2 secrets
Ability to create AWS IAM user and access keys with access to the Secrets Manager, or configure workload identity federation (WIF)
Ability to create sync destinations and associations on your Vault server

Setup

Navigate to the AWS Identity and Access Management (IAM) console to configure an IAM user or role with access to the Secrets Manager. The following example policy outlines the required permissions to use secrets syncing.

{
  "Version": "2012-10-17",
  "Statement": [
      {
        "Effect": "Allow",
        "Action": [
          "secretsmanager:Create*",
          "secretsmanager:Update*",
          "secretsmanager:Delete*",
          "secretsmanager:TagResource"
        ],
        "Resource": "arn:aws:secretsmanager:*:*:secret:vault*"
      }
  ]
}

Configure a sync destination with the appropriate authentication credentials.

IAM user credentials: Use IAM user credentials created in the previous step

$ vault write sys/sync/destinations/aws-sm/my-awssm-1 \
      access_key_id="$ACCESS_KEY_ID" \
      secret_access_key="$SECRET_ACCESS_KEY" \
      region='us-east-1'

Output:

Key                   Value
---                   -----
connection_details    map[access_key_id:***** region:us-east-1 secret_access_key:*****]
name                  my-awssm-1
type                  aws-sm

Workload identity federation (WIF) authentication: Configure a trust relationship between Vault and AWS. Use WIF to eliminate the need to manage long-lived access keys.

$ vault write sys/sync/destinations/aws-sm/my-awssm-1 \
      role_arn="arn:aws:iam::123456789123:role/example-web-identity-role" \
      identity_token_audience="$AUDIENCE" \
      region='us-east-1'

Output:

Key                   Value
---                   -----
connection_details    map[identity_token_audience:***** region:us-east-1 role_arn:arn:aws:iam::123456789123:role/example-web-identity-role]
name                  my-awssm-1
type                  aws-sm

Usage

If you do not already have a KVv2 secret to sync, mount a new KVv2 secrets engine.

$ vault secrets enable -path=my-kv kv-v2

Output:

Success! Enabled the kv-v2 secrets engine at: my-kv/

Create secrets you wish to sync with a target AWS Secrets Manager.

$ vault kv put -mount=my-kv my-secret foo='bar'

Output:

==== Secret Path ====
my-kv/data/my-secret

======= Metadata =======
Key                Value
---                -----
created_time       2023-09-19T13:17:23.395109Z
custom_metadata    <nil>
deletion_time      n/a
destroyed          false
version            1

Create an association between the destination and a secret to synchronize.

$ vault write sys/sync/destinations/aws-sm/my-awssm-1/associations/set \
    mount='my-kv' \
    secret_name='my-secret'

Output:

Key                   Value
---                   -----
associated_secrets    map[kv_37993f8a/my-secret:map[accessor:kv_37993f8a secret_name:my-secret sync_status:SYNCED updated_at:2023-09-19T13:17:35.085581-05:00]]
store_name            aws1
store_type            aws-sm

Navigate to the Secrets Manager in the AWS console to confirm your secret was successfully synced.

Moving forward, any modification on the Vault secret will be propagated to its AWS Secrets Manager counterpart. Creating a new secret version in Vault will update the one in AWS to the new version. Deleting either the secret or the association in Vault will delete the secret in your AWS account as well.

Workload identity federation (WIF)

The AWS Secrets Manager sync destination supports the WIF workflow, and has a source of identity called an identity token. The identity token is a JWT that Vault signs internally using the secrets sync identity token issuer.

The sync destination can exchange identity tokens for short-lived STS credentials needed to perform the requested actions as long as you have configured a trust relationship between Vault and AWS using workload identity federation

Exchanging identity tokens for STS credentials lets the AWS Secrets Manager sync destination operate without configuring explicit access to sensitive IAM security credentials.

To configure the sync destination to use WIF:

Ensure that Vault openid-configuration and public JWKS APIs are network-reachable by AWS. We recommend using an API proxy or gateway if you need to limit Vault API exposure.
Create an IAM OIDC identity provider in AWS.
- The provider URL must point at your Vault identity token issuer with the /.well-known/openid-configuration suffix removed. For example: https://host:port/v1/identity/oidc/secrets-sync.
- The audience should uniquely identify the recipient of the identity token. In AWS, the recipient is the identity provider. We recommend using the host:port/v1/identity/oidc/secrets-sync portion of the provider URL as your recipient since it is unique for each configured identity provider.
Create a web identity role in AWS with the same audience used for your IAM OIDC identity provider.
- The subject identifier must match the unique sub claim issued by identity tokens and have the form secrets-sync:<namespace_path>:<store_type>:<store_name>.
- Attach the IAM policy granting the required Secrets Manager permissions to the web identity role, as shown in the Setup section.
Configure the AWS Secrets Manager sync destination with the IAM OIDC audience value and web identity role ARN.

$ vault write sys/sync/destinations/aws-sm/my-awssm-1 \
    identity_token_audience="vault.example/v1/identity/oidc/secrets-sync" \
    role_arn="arn:aws:iam::123456789123:role/example-web-identity-role" \
    region="us-east-1"

Your sync destination can now use WIF for its configuration credentials. By default, WIF credentials have a time-to-live of 1 hour and automatically refresh when they expire.

For more information about the WIF-related configuration parameters, refer to the API documentation.

Access management

You can allow or restrict access to secrets by attaching AWS Resource Tags to secrets. For example, the following AWS IAM policy prevents Vault from modifying secrets that were not created by a sync operation:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:*",
      ],
      "Resource": "*",
      "Condition": {
        "StringEquals": {
          "secretsmanager:ResourceTag/hashicorp:vault": "" # This tag is automatically added by Vault on every synced secrets
        }
      }
    }
  ]
}

To prevent out-of-band overwrites, we recommend adding a negative condition on all write-access policies not used by Vault:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Deny",
      "Action": [
        "secretsmanager:*"
      ],
      "Resource": "*",
      "Condition": {
        "StringNotEquals": {
          "secretsmanager:ResourceTag/hashicorp:vault": "" # This tag is automatically added by Vault on every synced secrets
        }
      }
    }
  ]
}

Use wildcards with extreme caution

The previous examples use wildcards for the sake of brevity. We strongly recommend you use the principle of least privilege to restrict actions and resources for each use case to the minimum necessary requirements.

Tutorial

Refer to the Vault Enterprise Secrets Sync tutorial to learn how to configure the secrets sync between Vault and AWS Secrets Manager.

API

Please see the secrets sync API for more details.