On Mar 03, 2022

Cheat Sheet: AWS Secrets Manager

Kyler Middleton
Kyler MiddletonCloud IAM Advocate at IAM Pulse

AWS documentation is comprehensive, but it sometimes feels like you're reading the encyclopedia - there's just so much data! That's why we read the encyclopedia for you, and distilled down what we think are the most important flags for resources and services, and provide example IAM resource policies to give you a running start. Keep an eye out for this series as we build it out to include the most commonly (and most commonly misconfigured) services.

Link to PDF copy

Basics

Secrets Manager is a vault for private text information. It can store both simple strings, which can include JSON structures, or key/value pairs. It can’t store blob/binary data. This data can be encrypted with an AWS provided key, or with a key provided by your org, which prevents AWS from accessing the secret even if they attempt to. Most AWS services that need to retrieve passwords are able to integrate with secrets manager, and can retrieve secrets values from this resource, rather than storing plain-text secrets in their configuration, CloudFormation, or Terraform settings, a big boon for security.

How Does IAM Fit?

Access to Secret contents are controlled by IAM resource policies. These secrets can be encrypted with many different keys if needed, which means keys can be used as a way to funnel access, e.g. - all front-end services use the “front end” KMS key, which only unlocks the secrets they should require.

Overview

Facts


  • Secrets are ASCII text, and can’t be binary or blob data. If you need to store binary data, look at S3 or EFS
  • Secrets can be encrypted with an AWS-provided secret key, or with a CMK, a customer-provided key. CMKs should prevent AWS from accessing the secret contents.
  • Secrets exist in a single region, but can be replicated to other regions. When replicated, they retain their link to the master secret
  • When replicated to other regions, they use an encryption key local to that region, so make sure to replicate KMS keys first if you want to have a common encryption key for the secret
  • Can store secrets as:
    • Simple strings, e.g. “P@ssword!
    • Structured data, like a JSON document
    • Key/value pairs
  • The secret value is often either:
    • Rotated automatically - if it doesn’t have to sync up to external systems (e.g., auth to separate application), and only has to be internally consistent. Secrets Manager can do a “Rotation” policy to automate this process
    • Set by hand outside of IaC - Common pattern is to build the secrets and any policies using CloudFormation/Terraform/Other IaC tool and then populate the secret value by hand. This avoid the IaC tooling ever knowing the secret value, and potentially storing it somewhere

Secrets Manager IAM Policy Examples

Several examples are listed below. For an up to date list of all stored policies, visit this page: https://www.iampulse.com/policies

Permit multi-account access to a secret in an account.

1{
2  "Version" : "2012-10-17",
3  "Statement" : [
4    {
5      "Sid" : "Secrets Manager Cross Account Policy",
6      "Effect" : "Allow",
7      "Action" : "secretsmanager:GetSecretValue",
8      "Resource" : "*",
9      "Principal" : {
10        "AWS" : [
11          "arn:aws:iam::1111111111:role/RoleName1",
12          "arn:aws:iam::2222222222:role/RoleName2"
13         ]
14      }
15    }
16  ]
17}

Principal policy to permit access to a secret called “SuperSecret”. Note the “*” at the end of the name, to include versioning as this secret is updated. Also see the KMS permit policy below. Principals will need to both get to the secret contents as well as the key that is used to encrypt that secret in order to decrypt it and get to the plaintext.

1{
2  "Version" : "2012-10-17",
3  "Statement" : [
4    {
5      "Effect" : "Allow",
6      "Action" : [
7        "secretsmanager:GetSecretValue"
8      ],
9      "Resource" : [
10        "arn:aws:secretsmanager:us-east-1:1234567890:secret:SuperSecret*"
11      ]
12    },
13    {
14      "Effect" : "Allow",
15      "Action" : [
16        "kms:Decrypt"
17      ],
18      "Resource" : [
19        "arn:aws:kms:us-east-1:1234567890:key/aaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee"
20      ]
21    }
22  ]
23}

Secrets Manager Configuration Options

IAM-Related Options

  • KMS Key ID (aws/secrets-manager AMK) - The KMS key used to encrypt this secret. If not specified, uses the aws/secrets-manager default Amazon Managed Key (AMK), which is created on first use if doesn’t exist yet.
    • Note: this can be changed later, but will regenerate the secret, and any consumers of this secret will need to specify the updated encryption key at the same time.
    • Recommendation: If security is a priority (is it ever not?), use a CMK that you specify by ARN here
  • Policy (blank) - A JSON-formatted IAM policy to control who can access this key.
    • Access to secrets can be gated with this policy or with a CMK key policy. Lack of access to either will make the key’s contents unreachable.
    • Recommendation: For max security, set this policy to permit access to only the specific principals and roles that require access

Other Options

  • Name (none) - A human-readable name for your key. By default none is assigned.
    • The name field also permits folder-like structures using the character “/”. For instance, you can use name “Prod/FrontEnd/Secret1” and write permissions policies against “Prod/FrontEnd/*”. This is an excellent scale-out technique
    • Recommendation: Assigned a memorable and human readable name, and utilize folders if scaling out is required
  • Replica (none) - Keys be default exist in one region in one account. Replication copies the key contents to other regions. Updates to the primary are automatically and immediately replicated to replica regions.
    • Each replica region needs to be assigned an encryption key local to that region. If you want to use the same CMK key for your secret replicas, make sure to first replicate your CMKs to those other regions
    • Force Overwrite Replica can be used to delete any existing keys in that region which use the same name in the target replica region.
  • Tags (none) - As with most resources, secrets support tags.

Additions

Did we miss something? Do you have a policy or addendum for these docs? Please reach out to our team on twitter @checkiampulse

    Get the IAM Pulse Check Newsletter

    We send out a periodic newsletter full of tips & tricks, contributions from the community, commentary on the industry, relevant social posts, and more.

    Checkout past issues for a sampling of the goods.