AWS Secrets Manager: Secure Storage, Retrieval, and Rotation

Database passwords, API keys, OAuth client secrets, and third-party credentials should not be hardcoded in application source code or committed to a repository. AWS Secrets Manager provides managed storage, retrieval, encryption, versioning, and rotation for these sensitive values.

This is Part 58 of the AWS Cloud Practitioner Study Notes. The most important distinction is:

AWS Secrets Manager → Stores and manages secrets
AWS KMS             → Manages encryption keys
Parameter Store     → Stores configuration and SecureString parameters

Secrets Manager uses AWS KMS to encrypt secret values at rest, but KMS is not the place to store a database password. KMS manages the cryptographic key; Secrets Manager manages the secret lifecycle.

Why use Secrets Manager?

Hardcoding credentials creates several problems:

const databasePassword = "MyPassword123";

The value can leak through source control, build logs, container images, error messages, or developer machines. Rotation is also difficult: changing the password requires updating every consumer that copied the old value.

With Secrets Manager, an application retrieves the value at runtime:

Application
      ↓ GetSecretValue
Secrets Manager
      ↓ decrypts with KMS when authorised
Secret value returned

The application still needs to handle the value safely in memory and avoid logging it. Secrets Manager reduces hardcoding and centralises access control; it does not make it safe to print a secret after retrieving it.

What is a secret?

A secret is confidential data that should be protected from unauthorised access. Common examples include:

• Database usernames and passwords
• API keys
• OAuth client secrets
• JWT signing secrets
• Payment provider credentials
• Redis or third-party service passwords
• Private keys and certificates, where Secrets Manager is appropriate

A secret value can be plain text or structured JSON. Database credentials are often stored in JSON so that an application can retrieve the host, port, username, password, and database name together:

{
  "engine": "mysql",
  "host": "db.internal.example",
  "port": 3306,
  "username": "app_user",
  "password": "replace-with-a-secret"
}

The JSON structure is application data. Secrets Manager encrypts the secret value and controls which principals may retrieve or update it.

Encryption with AWS KMS

Secrets Manager encrypts secret values at rest. You can use the AWS managed key for Secrets Manager or choose a customer managed KMS key when you need more control over key policy, cross-account access, audit, or key lifecycle.

Secret value
      ↓ encrypted at rest with
KMS key
      ↓ stored and managed by
Secrets Manager

When an authorised workload calls GetSecretValue, Secrets Manager retrieves the encrypted value and returns it after the relevant permissions and decryption checks succeed. The service stores the secret; KMS supplies the cryptographic protection.

This is the same service boundary described in AWS KMS: encryption keys and envelope encryption: KMS is a key-management service, while Secrets Manager is a secret-management service.

IAM access control

Give an application only the permission it needs to read the specific secret. A Lambda execution role might contain a statement like:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "secretsmanager:GetSecretValue",
      "Resource": "arn:aws:secretsmanager:ap-southeast-1:123456789012:secret:prod/database-*"
    }
  ]
}

If the secret uses a customer managed KMS key, the workload may also need the corresponding KMS decrypt permission, and the KMS key policy must allow the access path. Keep the secret resource, IAM policy, and KMS policy aligned.

Avoid granting secretsmanager:* on Resource: "*" to every application. Separate read access from administrative actions such as updating, deleting, or changing rotation configuration. Review access with CloudTrail and IAM tools, and avoid placing secret values in logs.

Secret versions and staging labels

Secrets Manager creates a new version when you change or rotate a secret. Version staging labels identify which version an application should use:

AWSCURRENT  → version applications normally retrieve
AWSPENDING  → candidate version during rotation
AWSPREVIOUS → previous known-good version

Applications normally call GetSecretValue without specifying a version and receive the AWSCURRENT version. During troubleshooting or controlled rollback, a specific version or staging label can be requested according to the application’s needs.

Versioning helps a rotation workflow test a new credential before making it current. It is not a substitute for backups or an unlimited linear history of every old secret value; design retention and recovery deliberately.

Automatic rotation

Rotation means changing the credential both in Secrets Manager and in the database or external service that accepts it. A secret that changes only in Secrets Manager will cause the application’s old credential and the stored value to disagree.

The general flow is:

Create a new secret version
          ↓
Update the database or external service
          ↓
Test the new credential
          ↓
Move AWSCURRENT to the new version
          ↓
Keep the previous version as AWSPREVIOUS

Secrets Manager supports managed rotation for supported secret types and Lambda-based rotation for other types. A Lambda rotation function commonly performs four stages:

1. createSecret creates a new pending value.
2. setSecret updates the database or service.
3. testSecret verifies the pending credential.
4. finishSecret moves AWSCURRENT to the successful version.

For RDS and compatible database credentials, Secrets Manager provides supported rotation workflows. For a custom API key or external system, you may need to implement and secure the rotation function yourself.

Rotation is not magic. The rotation function needs permission to update the secret, network access to the database or service, and credentials with enough authority to change the target account. Do not log the pending or current secret during debugging.

Application retrieval patterns

An application can retrieve a secret through the AWS SDK or CLI using GetSecretValue. A typical server-side flow is:

Lambda, ECS task, EC2 role, or application role
          ↓ assumes IAM role
Temporary AWS credentials
          ↓ calls
Secrets Manager GetSecretValue
          ↓
Database password or API credential

Prefer IAM roles and temporary credentials for workloads on AWS. Do not replace a hardcoded database password with a hardcoded AWS access key that can read the secret.

Applications should also consider caching retrieved values for a short, appropriate period. Fetching the secret on every request can increase latency, API calls, and cost. Caching creates a trade-off: after rotation, the application may use the old value until the cache expires, so connection retry and refresh behaviour should be designed explicitly.

Integrations with AWS services

Secrets Manager is commonly used by:

Service or workload	Example use
AWS Lambda	Retrieve a database password or third-party API key at runtime
Amazon ECS and Fargate	Inject a secret into a task definition or retrieve it in application code
Amazon EKS	Integrate workloads with Secrets Manager through supported secret-provider patterns
Amazon EC2	Use an instance role and SDK to retrieve credentials
Amazon RDS	Store and rotate database credentials
API Gateway integrations	Let a backend retrieve an external service credential
Systems Manager	Coordinate operational workflows that need secret access

When a secret is injected into a container as an environment variable, the process receives a copy at startup. Rotating the secret does not automatically update an already-running process in every integration. Plan task restarts, dynamic retrieval, connection refresh, or another update mechanism when rotation matters.

Secrets Manager versus Parameter Store

Both services can store values securely, but their centre of gravity is different:

Need	Recommended fit
Environment name, endpoint URL, feature setting, or tuning value	Systems Manager Parameter Store
Encrypted configuration value	Parameter Store SecureString
Database credential, API key, OAuth token, or private credential	Secrets Manager
Automatic credential rotation	Secrets Manager
Secret version stages and purpose-built secret lifecycle	Secrets Manager
Simple central configuration with lower operational overhead	Parameter Store

Parameter Store SecureString values use KMS encryption, but AWS recommends Secrets Manager for credentials and other secrets that need automatic rotation, cross-Region replication, or fine-grained secret-management controls. Do not put sensitive data in ordinary String or StringList parameters.

Secrets Manager versus KMS

Capability	AWS Secrets Manager	AWS KMS
Stores database passwords	Yes	No
Stores API keys and tokens	Yes	No
Manages encryption keys	Uses KMS	Yes
Encrypts data directly	Secret values at rest	Cryptographic operations and data keys
Automatic database credential rotation	Yes, for supported workflows or configured rotation	No
Key policy and key lifecycle	Uses the selected KMS key	Yes

The exam shortcut is:

Need a password or API key?       → Secrets Manager
Need an encryption key?            → KMS
Need ordinary application config? → Parameter Store

Practical security checklist

• Give each workload access only to the secrets it needs.
• Use IAM roles instead of long-term AWS access keys on AWS compute.
• Use a customer managed KMS key when key-level control or cross-account access requires it.
• Enable rotation for supported credentials where the application can tolerate and handle it.
• Make rotation idempotent and test the pending credential before promotion.
• Avoid logging secret values, environment dumps, or full SDK responses.
• Consider VPC endpoints when private network access to Secrets Manager is required.
• Cache carefully and implement connection refresh after rotation.
• Monitor access and changes with CloudTrail and operational alerts.

Common exam questions

Where should a database password or API key be stored?

AWS Secrets Manager.

Which service encrypts the secret value?

Secrets Manager uses AWS KMS for encryption at rest.

Which service manages the encryption key itself?

AWS KMS.

Which service can automatically rotate supported database credentials?

AWS Secrets Manager.

What should store a non-sensitive endpoint URL or environment setting?

Systems Manager Parameter Store is usually the simpler fit.

Why does an application still fail after a secret rotates?

The running process may have cached or injected the old value, existing database connections may need refreshing, or the rotation workflow may not have updated and tested the target database successfully.

Final memory map

Application
    ↓ GetSecretValue
Secrets Manager
    ├── stores secret versions
    ├── controls access with IAM and resource policies
    ├── rotates supported credentials
    └── encrypts values with KMS

KMS       → encryption keys
Parameter Store → configuration and SecureString parameters

The one-sentence takeaway is: AWS Secrets Manager stores and manages sensitive values, retrieves them for authorised workloads, and can rotate supported credentials, while AWS KMS supplies the encryption-key protection underneath.

Sources

• What is AWS Secrets Manager?
• What is in a Secrets Manager secret?
• Rotate AWS Secrets Manager secrets
• Lambda rotation functions
• Secrets Manager rotation schedules
• Systems Manager Parameter Store reference
• Move hardcoded database credentials to Secrets Manager