Visual overview
The workload is authorized to one secret, Secrets Manager manages versions and rotation, and KMS protects the stored secret value.
Technical reference
The secret value, its version state, the caller authorization, and the KMS encryption boundary are independent controls that must line up.
GetSecretValue returns the current version when no version ID or stage is explicitly selected.
The former current value can be identified explicitly, which is useful for rollback and troubleshooting.
Rotation workflows place the candidate version in a pending stage before promotion.
The four rotation steps create a candidate, update the target, verify the credential, and finalize staging labels.
PutResourcePolicy can validate and reject resource policies that would grant broad access when this protection is requested.
Secret values are encrypted with KMS; a customer managed key adds key-policy authorization that must be considered with IAM and resource policies.
A secret should be retrieved, not baked into an application
AWS Secrets Manager stores sensitive values such as database credentials, API keys, tokens, and other application secrets so applications can retrieve them at runtime through authenticated API calls. The access decision is governed by IAM and, when used, a resource-based policy on the secret. Secret values are encrypted using AWS KMS. This replaces the insecure pattern of embedding credentials in source code, AMIs, container images, or long-lived configuration files.
A workload still needs an identity to call GetSecretValue. In AWS, that normally means an IAM role with only the permissions required for the specific secret and, when a customer managed KMS key is involved, the necessary permission to use that key. Central storage does not make a secret public to every workload; it creates an addressable resource whose retrieval and lifecycle can be audited and controlled.
Versions and staging labels make rotation atomic
Secrets Manager stores secret values as versions and uses staging labels to identify which version has a particular role in the lifecycle. AWSCURRENT represents the version applications normally retrieve, AWSPREVIOUS identifies the former current version, and AWSPENDING is used during rotation. Applications can therefore request the current secret without hard-coding a version identifier, while the rotation workflow can create and test a replacement before promoting it.
Automatic rotation can be provided through managed rotation for supported integrations or through a Lambda rotation function for other secret types. The standard Lambda rotation contract is divided into create_secret, set_secret, test_secret, and finish_secret steps. A robust rotation updates both the stored secret and the target service credential, tests that the pending value actually works, and only then moves the staging labels so consumers see the new current version.
Secret access has both identity and resource boundaries
Secrets Manager supports resource-based policies, which are important for controlled cross-account access but can also become an exposure path if written too broadly. AWS provides policy validation and the BlockPublicPolicy parameter to help prevent a resource policy that grants broad public access. Cross-account designs can also require permission to use the customer managed KMS key encrypting the secret, so resource policy, caller IAM policy, and KMS key policy must agree.
Retrieval is an API call and should not be performed more often than necessary. AWS provides client-side caching approaches so workloads can reduce repeated network calls and cost while still refreshing secrets. Cache lifetime must be compatible with rotation: an application that caches indefinitely defeats the operational benefit of changing the credential in Secrets Manager. CloudTrail records Secrets Manager operations and should be part of the audit trail for sensitive credential management.
Key takeaways
- 01
Secrets Manager removes secrets from application artifacts and makes retrieval an authenticated, auditable API operation.
- 02
AWSCURRENT, AWSPREVIOUS, and AWSPENDING staging labels describe version roles during normal use and rotation.
- 03
Rotation must update the target credential as well as the stored secret and validate the new value before promotion.
- 04
Resource policies and KMS key policies are additional authorization boundaries, especially for cross-account access.
- 05
BlockPublicPolicy helps prevent broadly accessible secret resource policies.
Official AWS sources
Use these primary AWS resources for the source material behind this article and for deeper reference.