SEC02-BP03 Store and use secrets securely
Workloads prove their identity to databases, APIs, and third-party services with secrets such as passwords, API keys, and tokens. A secret in source code, a configuration file, or an environment variable is easy to disclose and hard to rotate. A secrets service encrypts these credentials, controls access, and rotates them automatically.
Desired outcome:
-
You know which secrets your workload requires and why each one exists.
-
You have replaced long-term credentials with short-term credentials wherever the workload supports it.
-
Your remaining long-term secrets are stored encrypted and rotated automatically.
-
You scope, audit, and log access to every secret.
-
Your development process continuously checks that no secrets are committed to source code.
Common anti-patterns:
-
Teams store long-term credentials in source code or configuration files.
-
Teams store credentials at rest without encryption.
-
Teams never rotate credentials, so a single instance of unauthorized access remains there indefinitely.
-
Teams grant broad human access to production secrets instead of restricting it to a dedicated role.
Benefits of establishing this best practice:
-
Secrets are encrypted at rest and in transit.
-
Access to each secret is gated through an API and recorded for audit.
-
Rotation runs in a central location, separate from application logic.
-
Fine-grained access control limits which principals can read or change a secret.
-
Automated scanning catches secrets before they reach a shared repository.
Level of risk exposed if this best practice is not established: High
Implementation guidance
Manage secrets in three ordered steps to reduce what needs long-term protection: remove, replace, and rotate. 1. Remove credentials the workload no longer needs. 2. Replace long-term credentials with short-term ones where possible — for example, swap a stored access key for a role that supplies temporary credentials. 3. Store and rotate what remains.
An audit of source code and configuration usually surfaces several kinds of credentials. The following table maps each to a handling strategy:
| Credential type | Description | Suggested strategy |
|---|---|---|
| IAM access keys | Access and secret keys used to call AWS from within a workload | Replace with IAM roles on the compute runtime, such as Amazon EC2 or AWS Lambda. For third-party access, ask whether they support cross-account access. For mobile apps, use Amazon Cognito identity pools. For workloads outside AWS, use IAM Roles Anywhere or AWS Systems Manager hybrid activations. For containers, use the Amazon ECS task role or Kubernetes service account for EKS. |
| SSH keys | Private keys used to log in to Linux instances | Replace with AWS Systems Manager Session Manager or EC2 Instance Connect, using IAM roles. |
| Application and database passwords | Plaintext password strings | Rotate by storing them in AWS Secrets Manager with automated rotation. |
| Amazon RDS and Aurora admin credentials | Plaintext password strings | Replace with the Secrets Manager integration for Amazon RDS or Amazon Aurora, or use IAM database authentication where supported. |
| OAuth and API tokens | Secret token strings | Rotate by storing them in AWS Secrets Manager with automated rotation. |
Access AWS services with temporary credentials from a role. Use roles for EC2 instances, execution roles for Lambda functions, Cognito roles for mobile users, or IoT Core policies for devices. For third-party integrations, delegate access to a role. Do not share static access keys with partners.
For secrets that must persist, use a managed service for storage, rotation, and access control. AWS Secrets Manager provides encryption at rest, encryption in transit, auditing, fine-grained access control, and automated rotation. Partner or self-built solutions with the same guarantees also work. Client-side caching speeds up retrieval and lowers API cost (for retrieval options, see Get secrets).
Some languages require you to implement your own in-memory encryption for client-side caching.
Implementation steps
-
Find hard-coded credentials in code: Scan your repositories with automated tooling such as Amazon Inspector code scanning in your CI/CD pipeline, then filter findings for secrets/credentials to locate the offending lines. Treat every finding as a credential to replace with role-based authentication, or at minimum rotate, rather than only a line to edit.
-
Remove or replace what you can: Mark credentials that are no longer needed for deletion. Replace embedded AWS access keys with IAM roles on the associated resources, and for components outside AWS use IAM Roles Anywhere
or AWS Systems Manager hybrid activations. -
Move remaining long-lived secrets into a secrets service: For third-party secrets that need the rotate strategy, integrate AWS Secrets Manager into your code to retrieve them at runtime. Retrieve secrets using the Lambda extension for serverless functions or the client-side examples for instances and containers.
-
Prevent new secrets from entering the codebase: Re-scan periodically, and add a pre-commit guard such as git-secrets
to block new credentials from being committed. -
Monitor secret access: Monitor Secrets Manager activity for unexpected usage, inappropriate access, or deletion attempts.
-
Reduce human exposure to secrets: Restrict read, write, and modify access to a dedicated IAM role, and let only a small set of operators assume it.
Resources
Related best practices:
Related documents:
Related videos:
Related workshops: