AWS Secrets Manager

AWS Secrets Manager stores credentials and other sensitive values, encrypts them, controls who may retrieve them, and rotates them on a schedule. Its purpose is to remove secrets from application code, configuration files and environment variables, and to make rotating one a routine event rather than a release.

What it does

1. Encryption. Secrets are encrypted at rest with AWS KMS and in transit with TLS.
2. Access control. Retrieval is authorised through IAM, and every retrieval is recorded in AWS CloudTrail.
3. Rotation. Secrets are replaced on a schedule, either by the owning AWS service or by a Lambda rotation function.

Encryption

Secrets Manager encrypts each secret with a KMS key — the AWS managed key aws/secretsmanager by default, or a customer managed key where key-level audit and control are required. A customer managed key is also what makes cross-account access to a secret work, because the other account needs permission on the key as well as on the secret.

Secret values are limited to 65,536 bytes, which is generous enough for a certificate or a small JSON document as well as a password.

Rotation

Managed rotation

Several AWS services rotate their own credentials in Secrets Manager, with no Lambda function to write or maintain:

• Amazon RDS — master user credentials
• Amazon Aurora — master user credentials
• Amazon DocumentDB — master user credentials
• Amazon Redshift — admin passwords
• Amazon ECS Service Connect — AWS Private CA TLS certificates
• Managed external secrets — secrets held by Secrets Manager partners

Managed rotation typically completes in under a minute. During the window, a connection that retrieves the secret may briefly receive the previous version, which is one reason applications should use a least-privilege database user rather than the master user.

Rotation by Lambda function

Everything else — a third-party API key, a self-managed database, an internal service credential — rotates through a Lambda function that you provide. Secrets Manager invokes it in four steps: create a new secret version, set it on the service, test it, and then mark it current.

The alternating users strategy is the one to choose where availability matters: two users exist, and rotation updates the one not currently in use, so there is never a moment when the live credential is invalid.

Scheduling

A rotation schedule is expressed as a rate() or cron() expression in UTC, with an optional window duration. A secret can rotate as often as every four hours.

Enabling rotation triggers an immediate one-time rotation to validate the configuration. Applications must be able to survive that first rotation — which is exactly the point of testing it — so enable rotation deliberately rather than as an afterthought during a release.

Access control

Two policy types apply, and both are evaluated.

Resource-based policies attach to an individual secret and state explicitly which principals may access it. They are the mechanism for cross-account access and for tight, per-secret control.

Identity-based policies attach to IAM roles and users and can cover many secrets at once — for example, allowing a service role to read every secret under a path prefix. This is the usual arrangement for a service that owns several secrets.

Application integration

1. Grant the application’s IAM role permission to call secretsmanager:GetSecretValue on the specific secret, and kms:Decrypt on the key if a customer managed key is used.
2. Retrieve the secret at runtime through the AWS SDK, or through the Secrets Manager Agent or the AWS Parameters and Secrets Lambda extension, both of which add a local cache.
3. Handle failure explicitly: retrieval can throttle, and a cached credential can be revoked mid-rotation. Reconnecting on an authentication error and re-reading the secret is the pattern that survives rotation.

The application code does not change when a secret rotates. It asks for the current value each time it needs one, and caches it for a bounded period; the rotation happens underneath.

Practice

• Never hold a secret in source control, a container image, an environment variable or a configuration file. Those are the four places credentials actually leak from.
• Grant the narrowest IAM permission that works — a specific secret ARN, not *.
• Cache retrieved secrets in memory for a short interval. Uncached retrieval in a hot path costs latency and money; caching for hours defeats rotation.
• Monitor retrieval and rotation through CloudTrail, and alarm on rotation failures — a rotation that has been failing silently for six months is the same as no rotation.
• Use a customer managed KMS key where the audit trail of key use, or cross-account sharing, matters.

For the choice between Secrets Manager and Systems Manager Parameter Store, see Secrets Manager vs Parameter Store.