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
• Ability to create sync destinations and associations on your Vault server

Setup

1. Navigate to the AWS Identity and Access Management (IAM) console to configure a IAM user with access to the Secrets Manager. The following is an example policy outlining 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*"
         }
     ]
   }
   

   Copy

2. Configure a sync destination with the 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'
   

   Copy

   Output:

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

Usage

1. 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
   

   Copy

   Output:

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

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

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

   Copy

   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
   

3. 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'
   

   Copy

   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
   

4. 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.

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
        }
      }
    }
  ]
}

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.