How do I share AWS Secrets Manager secrets between AWS accounts?

Last updated: 2020-10-14

I want to share my AWS Secrets Manager secret with another AWS account. How can I do this?

Short description

In this example, the Security_Account user manages your credentials, and the Dev_Account user is used by your developers. An AWS Identity and Access Management (IAM) user or an application running in the Amazon Elastic Compute Cloud (Amazon EC2) instance of your Dev_Account retrieves secrets in the Security_Account user account. You can use a resource-based policy for a secret, which allows you to attach a permissions policy to the secret. You can use this policy to allow an IAM entity from your Dev_Account to access the secret in your Security_Account.

A secret named DevSecret in your Security_Account is encrypted using a AWS KMS key DevSecretKMS. Then the secret is shared with your Dev_Account.

Note: You can't use the KMS default key for the account. The KMS default key is created, managed, and used on your behalf by an AWS service that runs on AWS Key Management Service (KMS). The KMS default key is unique to your AWS account and Region. Only the service that created the AWS managed key can use it. For more information, see AWS KMS keys.

Resolution

1.    If you don't have a secret, follow the instructions for Creating a basic secret. Be sure to specify the Amazon Resource Name (ARN) in the KMS key ID parameter for the secret.

2.    If you have an existing secret using an alias, follow the instructions for Modifying a secret. Be sure to specify the KMS key ARN in the KMS key ID parameter for the secret.

Note: You must use the full KMS key ARN to access a secret from another AWS account.

3.    Attach permissions to the IAM identity similar to the following:

Note: Replace your-region with your AWS Region.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowGetSecretValue",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": [
                "arn:aws:secretsmanager:your-region:Security_Account:secret:DevSecret-??????"
            ]
        },
        {
            "Sid": "AllowKMSDecrypt",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": [
                "arn:aws:kms:your-region:Security_Account:key/DevSecretKMS_id"
            ]
        }
    ]
}

The IAM user SecretsUser in Dev_Account retrieves the secret. SecretsUser must have permission to secretsmanager:GetSecretValue. The AWS decrypt permissions are required for SecretsUser, because DevSecret is encrypted using the DevSecretKey.

4.    Grant permissions in the key policy of the KMS key. Secrets Manager encrypts secrets by default. Identities that retrieve these secrets require access to decrypt. Because DevSecret is encrypted using DevSecretKMS, you must change the key policy by adding the following permissions:

Note: Replace your-region with your AWS Region.

{
    "Sid": "AllowUseOfTheKey",
    "Effect": "Allow",
    "Principal": {
        "AWS": "arn:aws:iam::Dev_Account:user/SecretsUser"
    },
    "Action": [
        "kms:Decrypt"
    ],
    "Resource": "*",
    "Condition": {
        "StringEquals": {
            "kms:ViaService": "secretsmanager.your-region.amazonaws.com"
        },
        "StringLike": {
            "kms:EncryptionContext:SecretARN": "arn:aws:secretsmanager:your-region:Security_Account:secret:DevSecret-??????"
        }
    }
}

This policy grants SecretsUser the permission to use DevSecretKMS. This policy also grants the SecretsUser the ability to use the decrypt and describe-key commands with DevSecretKMS.

5.    Allow the IAM entity permission to access the secret. From the Security_Account, attach a resource-based policy that grants permission for the SecretsUser to retrieve DevSecret.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowUseOfTheKey",
            "Effect": "Allow",
            "Action": "secretsmanager:GetSecretValue",
            "Principal" : {
              "AWS" : "arn:aws:iam::Dev_Account:user/SecretsUser"
            },
            "Resource": "*",
            "Condition": {
                "ForAnyValue:StringEquals": {
                    "secretsmanager:VersionStage": "AWSCURRENT"
                }
            }
        }
    ]
}

6.    Retrieve the secret as SecretsUser.

Note: The policy in step 5 explicitly requires reference to the AWSCURRENT version stage. This must be explicitly required wherever the secret is retrieved by SecretsUser similar to the following:

$ aws secretsmanager get-secret-value --secret-id arn:aws:secretsmanager:your-region:Security_Account:secret:DevSecret --version-stage AWSCURRENT

You can use these instructions for all IAM entities. For example, for an Amazon EC2 instance profile or a role, replace or add the ARN in the resource policy and edit the permissions attached to the IAM entity.