AWS Secrets Manager is a secrets management service that helps you protect access to your applications, services, and IT resources. AWS Secrets Manager helps you manage, retrieve, and rotate database credentials, application credentials, OAuth tokens, API keys, and other secrets throughout their lifecycles. With Secrets Manager, you can configure an automatic rotation schedule for your secrets. You can use Secrets Manager without any deposit amount (upfront investment) or maintenance cost.

1. Concepts in AWS Secrets Manager

Secret is secret information that may be a password, a set of credentials such as a user name and password, an OAuth token, or other secret information that you store in an encrypted form in Secrets Manager. the secret value, plus metadata about the secret that can be a string or binary. To store multiple string values in one secret, we recommend that you use a JSON text string with key/value pairs.

A secret has versions that hold copies of the encrypted secret value. When you change the secret value or the secret is rotated, Secrets Manager creates a new version. It does not store the history of secrets with versions. Instead of storing, it tracks the versions as labels. There are 3 types of labels in versions they are AWSCURRENT for the current version, AWSPREVIOUS for the previous version, and AWSPENDING as pending during rotation. Secrets Manager never removes labeled versions but removes unlabeled (deprecated) versions when there are more than 100. Secrets Manager doesn’t remove versions created less than 24 hours ago.

version

Rotation is the process of periodically updating a secret. Here secret means the credentials and the database or service. In Secrets Manager, you can set up automatic rotation for your secrets. It offers two rotation strategies. They are single-user and alternating user.

Amazon CodeGuru Reviewer is a service that is used for developers to detect potential defects by using program analysis and machine learning. CodeGuru Reviewer integrates with Secrets Manager to find unprotected secrets in your code.

2. Authentication and access control for AWS Secrets Manager

Secrets Manager uses AWS Identity and Access Management (IAM) to secure access to secrets. IAM provides authentication and access control. Authentication verifies the identity of individuals’ requests. Secrets Manager uses a sign-in process with passwords, access keys, and multi-factor authentication (MFA) tokens to verify the identity of the users. Access control ensures that only approved individuals can perform operations on AWS resources such as secrets. Secrets Manager uses policies to define who has access to which resources, and which actions the identity can take on those resources.

By using IAM Roles Anywhere you can obtain temporary security credentials for your workloads & store and manage the credentials that can be accessed by AWS resources.

By using IAM permission policies, you control which users or services have access to your secrets. A permissions policy describes who can perform which actions on which resources. Identity-based policy means you can specify who ( user, role, groups) can access which secrets and act on those secrets. Resource-based policy means you specify who can access the secret and the actions they can perform on the secret.

An AWS-managed policy is a standalone policy that is created and administered by AWS. AWS managed policies are designed to provide permissions for many common use cases so that you can start assigning permissions to users, groups, and roles.

Cross account Access means allowing users to access the secrets from one account to another account. For this, you must allow access both in a resource policy and in an identity policy. Instead of using AWS-managed keys, you can use your own KMS key and attach the key policy to it.

3. Working with secrets

After you create a user for the database (Amazon RDS, Amazon Aurora, Amazon Redshift, or Amazon Document DB), you can store their credentials in Secrets Manager. To create a secret, you need the permissions granted by the SecretsManagerReadWrite. Secrets Manager generates a CloudTrail log entry when you create a secret.

Optionally you can replicate (copy) your secret for your source data to different regions in read-only mode. The secret contains the connection information of your source database. Before you can replicate a secret to another Region, you must enable that Region. You can add additional key/value pairs to the secret for regional connection information. If you turn on rotation for your primary secret, the Secrets Manager rotates the secret in the primary Region, and the new secret value propagates to all of the associated replica secrets.

You can update the secret value. The current secret value is kept as AWSCURRENT and the old secret value as AWSPREVIOUS.

Secrets Manager uses envelope encryption with AWS KMS keys and data keys to protect each secret value. For each secret, you can use the AWS-managed key or customer-managed key. For most cases, we recommend using the AWS managed key, and there is no cost for using it. If you need to access the secret from another AWS account, or if you want to use your own KMS key so that you can rotate it or apply a key policy to it, use a customer managed key. You can change the encryption key (AWS managed key to customer managed key (or) vice versa) for your secret. So that, your existing versions of the secrets do not affect. Only the newer versions of the secret will change under the new encryption key. If you deactivate the previous encryption key, you will be able to decrypt the following secret versions AWSCURRENT, AWSPREVIOUS, and AWSPENDING only. If you want to access to other labelled secret versions, you need to recreate those versions with the new encryption key using the AWS CLI.

Secrets Manager does not immediately delete secrets. Instead, Secrets Manager makes the secrets inaccessible and scheduled for deletion after a recovery window of a minimum of seven days. Until the recovery window ends, you can recover a secret you previously deleted. Incase of replica, first delete the replicas in other regions, then delete the primary secret in primary region. If you want to delete a version of a secret, first you remove all staging labels from the version using the AWS CLI or AWS SDK then Secrets Manager can automatically delete the version in the background. If you don’t know whether an application still uses a secret, you can create an Amazon CloudWatch alarm to alert you to any attempts to access a secret during the recovery window.

Secrets Manager considers a secret scheduled for deletion you can’t directly access it. You can’t recover the secret after the Secrets Manager deletes the secret permanently. Before the end of the recovery window, you can recover the secret and make it accessible again.

4. Working with Rotation

Secrets Manager rotation uses an AWS Lambda function to update the secret and the database. Secrets Manager only permits a Lambda rotation function to rotate the secret directly. The Lambda rotation function needs permission to access the secret in Secrets Manager, database or service to rotate the secret. The rotation function can’t call a second Lambda function to rotate the secret. You can automate the rotation in both consoles, CLI.

rotation function

When rotation is successful, the AWSPENDING label is attached with AWSCURRENT. When rotation is unsuccessful, the AWSPENDING label is attached with an empty version. If any rotation step fails, the Secrets Manager retries the entire rotation process multiple times. To turn on automatic rotation, you need both iam:CreateRole and iam:AttachRolePolicy permissions.

rotation schedule

See the above diagram for scheduled rotation which is in cron() and rate() expressions. rate() expression is used to schedule the rotation in hours or days. cron() expression is used to schedule the rotation in hours or days or week or month. To rotate the secret immediately, you can do this using the console (or) CLI. In the console under your secrets-> Rotation Configuration-> enable the Rotation Status -> select Rotate the Secret immediately. In AWS CLI call the “describe-secret” and get the response of Rotation Lambda ARN and Rotation Rules.