aws-secrets-manager

# AWS Secrets Manager AWS Secrets Manager helps protect access to applications, services, and IT resources. Store, retrieve, and automatically rotate credentials, API keys, and other secrets. ## Table of Contents - [Core Concepts](#core-concepts) - [Common Patterns](#common-patterns) - [CLI Reference](#cli-reference) - [Best Practices](#best-practices) - [Troubleshooting](#troubleshooting) - [References](#references) ## Core Concepts ### Secrets Encrypted data stored in Secrets Manager. Can contain: - Database credentials - API keys - OAuth tokens - Any key-value pairs (up to 64 KB) ### Versions Each secret can have multiple versions: - **AWSCURRENT**: Current active version - **AWSPENDING**: Version being rotated to - **AWSPREVIOUS**: Previous version ### Rotation Automatic credential rotation using Lambda functions. Built-in support for: - Amazon RDS - Amazon Redshift - Amazon DocumentDB - Custom secrets ## Common Patterns ### Create a Secret **AWS CLI:** ```bash # Create secret with JSON aws secretsmanager create-secret \ --name prod/myapp/database \ --description "Production database credentials" \ --secret-string '{"username":"admin","password":"MySecurePassword123!","host":"mydb.cluster-xyz.us-east-1.rds.amazonaws.com","port":5432,"database":"myapp"}' ``` **boto3:** ```python import boto3 import json secrets = boto3.client('secretsmanager') response = secrets.create_secret( Name='prod/myapp/database', Description='Production database credentials', SecretString=json.dumps({ 'username': 'admin', 'password': 'MySecurePassword123!', 'host': 'mydb.cluster-xyz.us-east-1.rds.amazonaws.com', 'port': 5432, 'database': 'myapp' }), Tags=[ {'Key': 'Environment', 'Value': 'production'}, {'Key': 'Application', 'Value': 'myapp'} ] ) ``` ### Retrieve a Secret ```python import boto3 import json secrets = boto3.client('secretsmanager') def get_secret(secret_name): response = secrets.get_secret_value(SecretId=secret_name) if 'SecretString' in response: return json.loads(response['SecretString']) else: import base64 return base64.b64decode(response['SecretBinary']) # Usage credentials = get_secret('prod/myapp/database') db_password = credentials['password'] ``` ### Caching Secrets (Recommended) ```python from aws_secretsmanager_caching import SecretCache, SecretCacheConfig cache_config = SecretCacheConfig( max_cache_size=100, secret_refresh_interval=3600 ) cache = SecretCache(config=cache_config) def get_cached_secret(secret_name): secret = cache.get_secret_string(secret_name) return json.loads(secret) ``` ### Enable Rotation for RDS ```bash aws secretsmanager rotate-secret \ --secret-id prod/myapp/database \ --rotation-lambda-arn arn:aws:lambda:us-east-1:123456789012:function:SecretsManagerRDSPostgreSQLRotation \ --rotation-rules AutomaticallyAfterDays=30 ``` ### CloudFormation: Secret with Auto-Generated Password ```yaml AWSTemplateFormatVersion: '2010-09-09' Resources: DBSecret: Type: AWS::SecretsManager::Secret Properties: Name: prod/myapp/database GenerateSecretString: SecretStringTemplate: '{"username": "admin"}' GenerateStringKey: password PasswordLength: 32 ExcludeCharacters: '"@/\' DBSecretRotation: Type: AWS::SecretsManager::RotationSchedule Properties: SecretId: !Ref DBSecret RotationLambdaARN: !GetAtt RotationLambda.Arn RotationRules: AutomaticallyAfterDays: 30 ``` ### Use in Lambda with Extension (Zero SDK calls) ```python import json import os import urllib.request def handler(event, context): secrets_port = 2773 secret_name = 'prod/myapp/database' url = f'http://localhost:{secrets_port}/secretsmanager/get?secretId={secret_name}' headers = {'X-Aws-Parameters-Secrets-Token': os.environ['AWS_SESSION_TOKEN']} request = urllib.request.Request(url, headers=headers) response = urllib.request.urlopen(request) secret = json.loads(response.read())['SecretString'] credentials = json.loads(secret) return credentials ``` ## CLI Reference ### Secret Management | Command | Description | |---------|-------------| | `aws secretsmanager create-secret` | Create secret | | `aws secretsmanager describe-secret` | Get secret metadata | | `aws secretsmanager get-secret-value` | Retrieve secret value | | `aws secretsmanager update-secret` | Update secret | | `aws secretsmanager delete-secret` | Delete secret | | `aws secretsmanager restore-secret` | Restore deleted secret | | `aws secretsmanager list-secrets` | List secrets | ### Versions | Command | Description | |---------|-------------| | `aws secretsmanager put-secret-value` | Add new version | | `aws secretsmanager list-secret-version-ids` | List versions | | `aws secretsmanager update-secret-version-stage` | Move staging labels | ### Rotation | Command | Description | |---------|-------------| | `aws secretsmanager rotate-secret` | Configure/trigger rotation | | `aws secretsmanager cancel-rotate-secret` | Cancel rotation | ## Best Practices ### Secret Organization - **Use hierarchical names**: `environment/application/secret-type` - **Tag secrets** for organization and cost allocation - **Separate by environment** (dev, staging, prod) ### Security - **Use resource policies** to control access - **Enable encryption** with customer-managed KMS keys - **Rotate secrets** regularly (30-90 days) - **Audit access** with CloudTrail - **Use VPC endpoints** for private access ### Access Control ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret" ], "Resource": "arn:aws:secretsmanager:us-east-1:123456789012:secret:prod/*", "Condition": { "StringEquals": { "secretsmanager:ResourceTag/Environment": "production" } } } ] } ``` ### Application Integration - **Cache secrets** to reduce API calls - **Handle rotation** gracefully (retry with new credentials) - **Use Lambda extension** for faster access - **Never log secrets** ## Troubleshooting ### AccessDeniedException **Causes:** - IAM policy missing `secretsmanager:GetSecretValue` - Resource policy denying access - KMS key policy missing permissions **Debug:** ```bash # Check secret resource policy aws secretsmanager get-resource-policy --secret-id my-secret # Check IAM permissions aws iam simulate-principal-policy \ --policy-source-arn arn:aws:iam::123456789012:role/my-role \ --action-names secretsmanager:GetSecretValue \ --resource-arns arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret ``` ### Rotation Failed **Debug:** ```bash # Check rotation status aws secretsmanager describe-secret --secret-id my-secret # Check Lambda logs aws logs filter-log-events \ --log-group-name /aws/lambda/SecretsManagerRotation \ --filter-pattern "ERROR" ``` **Common causes:** - Lambda timeout (increase to 30+ seconds) - Network connectivity (VPC configuration) - Database connection issues ### Secret Not Found ```bash # List secrets to find correct name aws secretsmanager list-secrets \ --filters Key=name,Values=myapp ``` ## References - [Secrets Manager User Guide](https://docs.aws.amazon.com/secretsmanager/latest/userguide/) - [Secrets Manager API Reference](https://docs.aws.amazon.com/secretsmanager/latest/apireference/) - [Secrets Manager CLI Reference](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/) - [boto3 Secrets Manager](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/secretsmanager.html)