Creating Secrets Using Best Practices

Creating Secrets Using Best Practices

Overview

Domain expertise for creating and managing secrets in AWS Secrets Manager with production-grade security controls: KMS encryption, automatic rotation, least-privilege IAM policies, CloudTrail auditing, and lifecycle management.

Create a secret with best practices

To create a properly secured secret in AWS Secrets Manager, follow the procedure exactly. See secret creation procedure.

The procedure supports four secret types: database credentials, API keys, OAuth tokens, and custom secrets. Each type is structured appropriately and encrypted with a dedicated KMS key.

Troubleshooting

KMS key access issues

Verify the IAM principal has kms:CreateKey and kms:PutKeyPolicy permissions, and that the key policy grants kms:GenerateDataKey, kms:Decrypt, and kms:DescribeKey scoped with kms:ViaService to secretsmanager.<region>.amazonaws.com. See the full procedure for details.

Rotation setup failures

Check that the Lambda rotation function exists, has proper permissions, and can reach the target system. Review CloudWatch logs for the rotation function.

Secret access denied

Verify the IAM policy is attached to the correct principal, the KMS key policy allows decryption (and kms:GenerateDataKey for write/rotation), and the principal is using HTTPS. See the full procedure for details.

Create Secrets Using Best Practices

Overview

This SOP provides a comprehensive approach to creating and managing secrets in AWS Secrets Manager following security best practices. It covers creating secrets with proper encryption using KMS, implementing automatic rotation, configuring least-privilege IAM policies, enabling CloudTrail auditing, and setting up lifecycle management with proper tagging and deletion policies.

Parameters

• secret_name (required): The name of the secret to create
• secret_description (required): Description of what the secret contains
• secret_type (required): Type of secret (database, api-key, oauth, custom)
• secret_value (required): The secret value or JSON structure
• aws_region (required): The AWS region where the secret will be created
• kms_key_id (optional): KMS key ID for encryption (will create if not provided)
• enable_rotation (optional, default: true): Whether to enable automatic rotation
• rotation_interval (optional, default: 30): Rotation interval in days
• lambda_function_arn (optional): ARN of Lambda function for custom rotation
• allowed_principals (optional): List of IAM principals that should have access
• tags (optional): Key-value pairs for resource tagging
• recovery_window (optional, default: 30): Recovery window in days before permanent deletion

Constraints for parameter acquisition:

• You MUST ask for all required parameters upfront in a single prompt rather than one at a time
• You MUST support multiple input methods including:
• Direct input: Text provided directly in the conversation
• File path: Path to a local file containing secret configuration
• URL: Link to configuration resources
• You MUST validate secret_type is one of: database, api-key, oauth, custom
• You MUST confirm successful acquisition of all parameters before proceeding
• You MUST NOT log or display the actual secret value in any output

Steps

1. Verify Dependencies

Check for required tools and warn the user if any are missing.

Constraints:

• You MUST verify the following tools are available in your context:
• call_aws
• You MUST ONLY check for tool existence and MUST NOT attempt to run the tools because running tools during verification could cause unintended side effects
• You MUST inform the user about any missing tools with a clear message
• You MUST ask if the user wants to proceed anyway despite missing tools
• You MUST respect the user's decision to proceed or abort
• You MUST explain the reason for every tool call before executing it throughout the entire SOP
• You MUST verify AWS CLI is properly configured with this command:

  aws sts get-caller-identity

2. Create or Verify KMS Key

Set up KMS key for secret encryption if not provided.

Constraints:

• If kms_key_id is provided, You MUST verify the key exists and is accessible
• If kms_key_id is not provided, You MUST create a new KMS key specifically for secrets
• You MUST configure the KMS key policy to grant the calling principal kms:GenerateDataKey, kms:Decrypt, and kms:DescribeKey permissions, scoped with the condition key kms:ViaService set to secretsmanager.{aws_region}.amazonaws.com so the key can only be used through Secrets Manager
• If allowed_principals is provided, You MUST add those principals to the key policy with kms:Decrypt and kms:DescribeKey permissions (read-only access to decrypt secrets)
• You MUST ensure the key policy retains the root account as key administrator to prevent lockout
• You MUST enable key rotation for the KMS key
• You MUST tag the KMS key with appropriate metadata

3. Create the Secret

Create the secret in AWS Secrets Manager with proper configuration.

Constraints:

• You MUST create the secret using the specified KMS key for encryption
• You MUST set the description and tags as provided
• You MUST configure the secret based on the secret_type:
• For database: Structure as JSON with host, username, password, engine, port, dbname
• For api-key: Structure as JSON with key and optional metadata
• For oauth: Structure as JSON with client_id, client_secret, and optional fields
• For custom: Use the provided structure as-is
• You MUST set the recovery window using the recovery_window parameter for deletion protection
• You MUST NOT display the secret value in any output or logs

4. Configure Automatic Rotation

Set up automatic rotation if enabled.

Constraints:

• If enable_rotation is true, You MUST configure automatic rotation
• You MUST set the rotation interval as specified
• For database secrets, You MUST use the appropriate AWS-managed rotation function
• For custom secrets, You MUST require and use the lambda_function_arn parameter
• You MUST verify the rotation function (specified by lambda_function_arn) has proper permissions to access the secret
• You MUST test the rotation configuration by triggering an initial rotation
• You MUST handle rotation setup failures gracefully and provide clear error messages

5. Create Least-Privilege IAM Policy

Create an IAM policy that grants minimal necessary permissions.

Constraints:

• You MUST create a read-only policy that allows only:
• secretsmanager:GetSecretValue for the specific secret ARN
• secretsmanager:DescribeSecret for the specific secret ARN
• kms:Decrypt for the specific KMS key ARN
• kms:DescribeKey for the specific KMS key ARN
• You MUST include the condition key aws:SecureTransport set to true to enforce HTTPS
• You MUST scope all resource ARNs to the specific secret and KMS key — do NOT use wildcards
• If enable_rotation is true, You MUST create a separate rotation policy that additionally allows:
• secretsmanager:PutSecretValue for the specific secret ARN
• secretsmanager:UpdateSecretVersionStage for the specific secret ARN
• kms:GenerateDataKey for the specific KMS key ARN (required when writing new secret values)
• If allowed_principals is provided, You MUST attach the read-only policy to those specific principals
• If allowed_principals is not provided, You MUST still create the policy but provide guidance for manual attachment
• You MUST provide the policy ARN and JSON for manual attachment if needed

6. Enable CloudTrail Auditing

Ensure CloudTrail is configured to audit Secrets Manager operations.

Constraints:

• You MUST verify CloudTrail is enabled in the region
• You MUST ensure CloudTrail captures Secrets Manager API calls
• You MUST configure CloudTrail to log to a secure S3 bucket with encryption
• You MUST set up CloudWatch Logs integration for real-time monitoring
• You MUST create CloudWatch alarms for suspicious secret access patterns
• You MUST provide guidance on monitoring and alerting best practices

7. Configure Lifecycle Management

Set up proper lifecycle management and monitoring.

Constraints:

• You MUST configure appropriate tags for cost allocation and management
• You MUST set up CloudWatch metrics for secret usage monitoring
• You MUST create CloudWatch alarms for:
• Failed secret retrievals
• Rotation failures
• Unusual access patterns
• You MUST configure backup and disaster recovery procedures
• You MUST document the secret management procedures for the team

8. Validate Configuration

Perform comprehensive validation of the secret setup.

Constraints:

• You MUST test secret retrieval using the created IAM policy
• You MUST verify encryption is working properly
• You MUST validate rotation configuration (if enabled)
• You MUST check CloudTrail logging is capturing secret operations
• You MUST verify all CloudWatch alarms are properly configured
• You MUST provide a summary of all created resources and their ARNs
• You MUST create documentation for ongoing secret management

Examples

Example Input for Database Secret

secret_name: "prod-database-credentials"
secret_description: "Production database credentials for main application"
secret_type: "database"
secret_value: {
  "host": "prod-db.example.com",
  "username": "app_user",
  "password": "secure_password_123",
  "engine": "mysql",
  "port": 3306,
  "dbname": "production"
}
aws_region: "us-east-1"
enable_rotation: true
rotation_interval: 30
tags: {
  "Environment": "Production",
  "Application": "MainApp",
  "Owner": "DevOps"
}

Example Input for API Key Secret

secret_name: "third-party-api-key"
secret_description: "API key for external service integration"
secret_type: "api-key"
secret_value: {
  "api_key": "EXAMPLE-API-KEY-REPLACE-ME",
  "service_name": "ExternalAPI",
  "endpoint": "https://api.external.com"
}
aws_region: "us-west-2"
enable_rotation: false

Troubleshooting

KMS Key Access Issues

If you encounter KMS key access errors, verify that:

• The IAM user/role has kms:CreateKey and kms:PutKeyPolicy permissions
• The key policy includes the necessary principals
• The Secrets Manager service has access to the key

Rotation Setup Failures

If automatic rotation setup fails:

• Verify the Lambda function exists and has proper permissions
• Check that the rotation function can access both the secret and the target system
• Ensure network connectivity between Lambda and the target system
• Review CloudWatch logs for the rotation function

CloudTrail Configuration Issues

If CloudTrail setup encounters problems:

• Verify S3 bucket permissions for CloudTrail
• Check that CloudTrail has proper IAM permissions
• Ensure the S3 bucket is in the same region or properly configured for cross-region access

Secret Access Denied

If secret retrieval fails:

• Verify the IAM policy is correctly attached to the principal
• Check that the KMS key policy allows the principal to decrypt
• Ensure the secret exists in the specified region
• Verify the principal is using HTTPS (aws:SecureTransport condition)