How to use AWS Secret Manager

AWS created Secrets Manager after hearing from customers that managing secrets was critical but difficult. IAM Roles help because they provide temporary credentials automatically. Attach a role to an EC2 instance, and your application gets short-term credentials without you having to manage them. AWS rotates these credentials multiple times a day.

Secrets Manager lets you manage the entire lifecycle of secrets: database credentials, SSH keys, tokens. You can store them, distribute them, and rotate them automatically.

How to use AWS Secret Manager

Capabilities and Advantages

Secrets Manager uses storage with 99.999% availability. Your secrets stay encrypted by default, so you won’t accidentally leave one unencrypted. The encryption keys live in your account.

Managing Secrets

You control access to your secrets. Once encrypted, you can retrieve them through a VPC endpoint specific to your organization.

Caching and Compliance

Secrets Manager provides client-side caching libraries for Java and JDBC. These cache secrets locally so your application stays stable during network issues. Secrets Manager complies with HIPAA, PCI, and ISO standards.

After storing secrets in Secrets Manager, you can control which developers can see them. You have tools to hide secrets from people who shouldn’t access them.

IAM Policies with Secret Manager

Access Control

Secrets Manager integrates tightly with IAM policies for fine-grained control over who can access what.

Resource-Based Policies

Resource-based policies control access from outside your account. A practical example: a business partner needs SSH access to an EC2 instance. You could email them the private key, but then you lose control. Instead, store the key in Secrets Manager and attach a resource-based policy allowing a role in their account to retrieve it. When the work is done, rotate the SSH key.

Tag-Based Access

You can tag secrets in Secrets Manager. Tag your dev team’s secrets with team:Dev. Then create one IAM policy that grants the entire team access to all their secrets. When someone new joins, attach them to the policy and they’re ready to go. When you add new resources, just store credentials with the right tag. No need to update policies.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Sid":"PermissionByDepartment",
         "Effect":"Allow",
         "Principal":{
            "AWS":"*"
         },
         "Action":"secretsmanager:GetSecretValue",
         "Resource":"*",
         "Condition":{
            "StringLike":{
               "SecretManager:RequestTag/Team":"Dev"
            }
         }
      }
   ]
}

New database? Store credentials with the team:Dev tag and your team gets access automatically. No policy updates needed.

Policy Example

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "secretsmanager:DescribeSecret",
        "secretsmanager:List*",
        "secretsmanager:GetSecretValue"
       ],
      "Resource": "arn:aws:secretsmanager:Region:AccountId:secret:a_secret_name-here"
    }
  ]
}

This policy grants read access to a specific secret. You can describe secrets to see metadata (description, rotation status, tags) without retrieving the actual value. Restricting access to specific secrets keeps employees from seeing things they shouldn’t.

Rotating Secrets

Secrets Manager has built-in rotation for RDS and EC2 databases. For other secret types, you write a custom Lambda function.

How Rotation Works

When you configure rotation, Secrets Manager creates a Lambda function in the same VPC as your target database. The function generates new credentials, stores them with a label called AWSPENDING, and tests them before going live.

Enabling Automatic Rotation

Automatic rotation converts a long-term secret into a short-term one. A credential that lived for years becomes one rotated every 15 or 30 days. The default rotation window is 30 days.

Here’s the tricky part: how does AWS ensure your application doesn’t fail when the password changes? Versions.

Secret Versions

When rotation triggers, Secrets Manager creates new credentials labeled AWSPENDING. It stores these in the database and runs tests to verify they work.

AWS Secret Manager Version: AWSPREVIOUS, AWSCURRENT, and AWSPENDING

During this validation period, AWSCURRENT still works, so your application keeps running normally. Once Secrets Manager confirms the new credentials are valid, it promotes them to AWSCURRENT and demotes the old ones to AWSPREVIOUS.

For details on keeping applications updated in real-time, see our guide on Approaches for Real-time Updates of AWS Secrets Manager Secrets in Applications.

From this point, when your application requests the secret, it gets the new credentials. AWSPREVIOUS becomes invalid at the next rotation or immediately, depending on your configuration.

AWS Secret Manager Workflow for Versioning: AWSPREVIOUS, AWSCURRENT, and AWSPENDING

JDBC Support

AWS provides a caching library for Java and JDBC. It reduces API calls to Secrets Manager by keeping secrets locally. Find the JDBC library on GitHub.

Best Practices

Here are six things to keep in mind when getting started with Secrets Manager.

• Rotate frequently
• Retrieve secrets programmatically
• Remove plain-text passwords
• Lock down permissions with IAM roles
• Use unique secrets per resource

Define your rotation schedule based on security and compliance requirements. Decide how you’ll retrieve secrets (programmatically, with caching, or both) based on your network setup. Map where your secrets currently live and plan your migration. Set up permissions for storing, retrieving, and rotating. Decide what to audit. Use unique secrets per region and environment.

Removing Plain-Text Secrets

Start by deciding your account strategy. One account or multiple? Then work with application owners to find where secrets are currently used.

Moving Secrets to Secret Manager

Keep secrets in the same account as the resource. Benefits: everything needed to run an application lives together, accounts act as security boundaries, and application owners can manage their own secrets while you maintain oversight and compliance.

Naming Secrets

Use clear, hierarchical names. Add descriptions with owner info and purpose. A developer can look at a description and know which secret they need and who to ask for access. Good naming scales.

Using Tags

Tags matter at scale. Ten secrets? You can manage without tags. Hundreds? Tags become essential.

{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Sid":"PermissionByEnvironment",
         "Effect":"Allow",
         "Principal":{
            "AWS":"*"
         },
         "Action":"secretsmanager:GetSecretValue",
         "Resource":"*",
         "Condition":{
            "StringLike":{
               "SecretManager:RequestTag/ENV":"PROD"
            }
         }
      }
   ]
}

Add this to your IAM policy to enforce tagging. Require tags when creating secrets.

KMS and Secret Manager

Secrets Manager uses your KMS key to generate a data key for each secret value. If you don’t specify a KMS key when creating a secret, it uses the AWS-managed key for Secrets Manager (aws/secretsmanager) in your region.

Secrets Manager calls KMS when it needs to decrypt a secret.

Before using a KMS key, make sure your EC2 role (or whatever retrieves secrets) has the right permissions. I learned this the hard way. If you see an error like:

com.amazonaws.services.secretsmanager.model.AWSSecretsManagerException: Access to KMS is not allowed

Your role needs these permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "KMSKeyForSM",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:GenerateDataKey"
            ],
            "Resource": "*"
        }
    ]
}

About the Default KMS Key

The default key works without extra permissions. AWS creates a unique encryption key per account and region. For cross-account access or compliance requirements, you might need customer-managed keys (CMKs). CMKs also add another layer of access control.

Rotation Frequency

How often you rotate depends on your security requirements. The console defaults to 30 days, which works for most situations. You pay per rotation API call, not per new secret version. Rotation creates a new version, not a new secret, so you’re not charged extra.

Lambda Rotation Functions

Secrets Manager creates Lambda functions to handle rotation. These need permissions to talk to the target database and Secrets Manager. VPC endpoints help here. Without internet routing, your Lambda and application connect to Secrets Manager privately.

The Lambda generates new credentials by calling a password API. By default, it creates the most complex password possible. For legacy applications that don’t support special characters, you can pass a parameter to exclude them:

# Get exclude characters from environment variable
exclude_characters = os.environ.get('EXCLUDE_CHARACTERS', ':/@"\'\\')
# Generate a random password
service_client = boto3.client('secretsmanager', region_name='us-east-1')
passwd = service_client.get_random_password(ExcludeCharacters=exclude_characters)

One Lambda Per Secret?

Not necessarily. Rotation Lambdas need IAM roles with specific permissions. It’s easier to let a small team create and manage the rotation Lambdas while others get permission to use them. Reusing Lambdas scales better than creating one per secret.

Consider your downstream applications when designing rotation Lambdas. Try to reuse them across similar resources.

IAM Roles for Applications

Create IAM roles for your applications with appropriate permissions. Retrieving a secret once an hour works for most cases. Client-side caching libraries handle refresh automatically. AWS provides caching for Java and JDBC, with more languages planned.

For serverless: retrieve secrets outside the Lambda handler. This lets the Lambda cache the secret for the container’s lifetime, reducing API calls.

Deleting Secrets

Don’t delete secrets immediately. Schedule them for deletion instead. If someone still needs access, you can restore the secret quickly and get things working again.

Locking Down Permissions

Few people need full Secrets Manager access. Be strict here. You can be more liberal with list and describe permissions because they help people find the right secret before requesting access.

Rotation requires IAM permissions. Consider separating duties. Some people store and retrieve secrets. Others configure rotation. Tags help manage this at scale.

Cross-account access requires CMKs.

Unique Secrets

Use unique secrets per environment, per region, per account. This limits the blast radius if a secret is compromised and makes recovery easier. It also avoids synchronization headaches across regions.

Use CloudFormation, Terraform, or similar tools to provision secrets consistently. Automation helps maintain good practices across accounts.

Auditing and Monitoring

IAM Access Advisor shows who accessed what. For detailed records, use CloudTrail. It integrates with the AWS ecosystem and shows the full story: who logged in, retrieved credentials, and used them with RDS or other services. CloudWatch Events monitors secret usage.

What to Monitor

Watch for attempts to retrieve secrets scheduled for deletion. If an application calls a deleted secret, it breaks. Catch this early.

Monitor access to high-value secrets from production: production database credentials, SSH keys. CloudTrail logs every Secrets Manager API call, so expect larger trail files once you start using the service.

Pricing

AWS Secrets Manager pricing (verify current rates on AWS pricing page):

• $0.40 per secret per month
• $0.05 per 10,000 API calls
• No annual contracts or upfront costs
• Free trial period available

You pay for what you use. Rotating a secret costs an API call. Creating a new version isn’t an extra secret charge.

Exam Tip

When you enable rotation, Secrets Manager rotates immediately to verify the configuration works. Watch for exam questions about enabling rotation when applications still have hard-coded passwords. The application must be updated to retrieve credentials from Secrets Manager using the SDK. Environment variables aren’t secure. If an attacker compromises the server, they can read everything.

Example

See our CloudFormation example for deploying Secrets Manager.

Conclusion

Secrets Manager gives you four things: secure storage, fine-grained access control, rotation without affecting applications, and pay-as-you-go pricing. No long-term contracts or hidden operational costs.