Sign In to the Console
AWS Secrets Manager
User Guide

AWS Documentation » AWS Secrets Manager » User Guide » AWS Secrets Manager Best Practices

AWS Secrets Manager Best Practices

The following recommendations help you securely use AWS Secrets Manager:

Protect Additional Sensitive Information

A secret often includes several pieces of information beyond the user name and password. Depending on the database, service, or website, you can opt to include additional sensitive data. This data can include password hints, or question-and-answer pairs that you can use to recover your password if you forgot it.

Make sure you securely protect any information that might be used to gain access to the credentials in the secret as securely as the credentials themselves. Don't store such information in the Description or any other non-encrypted part of the secret.

Instead, store all such sensitive information as part of the encrypted secret value (in either the SecretString or SecretBinary field). You can store up to 10240 bytes in the secret. In the SecretString field, the text usually takes the form of JSON key-value string pairs, as shown in the following example: 

{
  "engine": "mysql",
  "username": "user1",
  "password": "i29wwX!%9wFV",
  "host": "my-database-endpoint.us-east-1.rds.amazonaws.com",
  "dbname": "myDatabase",
  "port": "3306"
}

Improving Performance by Using the AWS provided Client-side Caching Components

To use your secrets most efficiently, you should not simply retrieve the secret value from Secrets Manager every time you want to use the credentials. Instead, use a Secrets Manager client component that knows how to cache your secrets and updates them only when required because of rotation. AWS has created such client components for you and made them available as open-source. For more information, see Use the AWS-developed open source client-side caching components to improve performance and reduce your costs

Mitigating the Risks of Logging and Debugging Your Lambda Function

When you create a custom Lambda rotation function to support your Secrets Manager secret, be careful about including debugging or logging statements in your function. These statements can cause information in your function to be written to CloudWatch. Ensure that the logging of information to CloudWatch doesn't include any of the sensitive data stored in the encrypted secret value. Also, if you do choose to include any such statements in your code during development for testing and debugging purposes, make sure that you remove those lines from the code before using it in production. Also, remember to remove any logs that include sensitive information collected during development after you no longer need it.

These kinds of logging and debug statements aren't included in any of the Lambda functions that AWS provides for supported databases.

Mitigating the Risks of Using the AWS CLI to Store Your Secrets

When you use the AWS Command Line Interface (AWS CLI) to invoke AWS operations, you enter those commands in a command shell. For example, you can use the Windows command prompt or Windows PowerShell, or the Bash or Z shell, among others. Many of these command shells include functionality designed to increase productivity. But this functionality can be used to compromise your secrets. For example, in most shells, you can use the up arrow key to see the last command entered. This command history feature could be exploited by anyone who sees your unsecured session. Also, other utilities that work in the background may have access to your command parameters with the intended goal of helping you get your tasks done more efficiently. To mitigate such risks, ensure you take the following steps:

  • Always lock your computer when you walk away from your console.

  • Uninstall or disable console utilities that you don't need or no longer use.

  • Ensure that both the shell and the remote access program, if you are using one, don't log the commands you type.

  • Use techniques to pass parameters not captured by shell command history. The following example shows how you can type the secret text into a text file, which then passes to the AWS Secrets Manager command and immediately destroyed. This means that the secret text isn't captured by the typical shell history.

    The following example shows typical Linux commands (your shell might require slightly different commands): 

    $ touch secret.txt                                                                           # Creates an empty text file
$ chmod go-rx secret.txt                                                                     # Restricts access to the file to only the user
$ cat > secret.txt                                                                           # Redirects standard input (STDIN) to the text file
ThisIsMyTopSecretPassword^Z                                                                  # Everything the user types from this point up to the CTRL-Z (^Z) is saved in the file
$ aws secretsmanager create-secret --name TestSecret --secret-string file://secret.txt       # The Secrets Manager command takes the --secret-string parameter from the contents of the file
$ shred -u secret.txt                                                                        # The file is destroyed so it can no longer be accessed.

After you run these commands, you should be able to use the up and down arrows to scroll through the command history and see that shell does not display the secret text on any line.

Important

By default, you can't perform an equivalent technique in Windows unless you first reduce the size of the command history buffer to 1.

To configure the Windows Command Prompt to have only 1 command history buffer of 1 command

  1. Open an Administrator command prompt (Run as administrator).

  2. Select the icon in the upper left on the title bar, and then select Properties.

  3. On the Options tab, set Buffer Size and Number of Buffers both to 1, and then click OK.

  4. Whenever you have to type a command that you don't want in the history, immediately follow it with one other command, such as: 

    echo.

    This ensures that the sensitive command is flushed.

For the Windows Command Prompt shell, you can download the SysInternals SDelete tool, and then use commands that are similar to the following: 

C:\> echo. 2> secret.txt                                                                       # Creates an empty file
C:\> icacls secret.txt /remove "BUILTIN\Administrators" "NT AUTHORITY/SYSTEM" /inheritance:r   # Restricts access to the file to only the owner
C:\> copy con secret.txt /y                                                                    # Redirects the keyboard to text file, suppressing prompt to overwrite
THIS IS MY TOP SECRET PASSWORD^Z                                                             # Everything the user types from this point up to the CTRL-Z (^Z) is saved in the file
C:\> aws secretsmanager create-secret --name TestSecret --secret-string file://secret.txt      # The Secrets Manager command takes the --secret-string parameter from the contents of the file
C:\> sdelete secret.txt                                                                        # The file is destroyed so it can no longer be accessed.

Cross-Account Access – Should I Specify a User/Role or the Account?

When you want to use a resource-based policy attached to a secret to grant access to an IAM principal in a different AWS account, you have two options:

  • Specify only the other account ID – In the Principal element of the statement, you specify the Amazon Resource Name (ARN) of the foreign account root. This enables the administrator of the foreign account to delegate access to roles in the foreign account. The administrator must then assign IAM permission policies to the role or roles that must access the secret. 

    "Principal": {"AWS": arn:aws:iam::AccountId:root}

  • Specify the exact user or role in the other account – You specify an exact user or role ARN as the Principal of a secret-based policy. You get the ARN from the administrator of the other account. Only that single user or role in the account can to access the resource. 

    "Principal": [ 
    {"AWS": "arn:aws:iam::AccountId:role/MyCrossAccountRole"},
    {"AWS": "arn:aws:iam::AccountId:user/MyUserName"}
]

As a best practice, we recommend that you specify only the account in the secret-based policy, for the following reasons:

  • In both cases, you're trusting the administrator of the other account. In the first case, you trust the administrator to ensure that only authorized individuals have access to the IAM user, or can assume the specified role. This is essentially the same level of trust as specifying only the account ID. You trust that account and the administrator. When you specify only the account ID, you give the administrator the flexibility to manage their users.

  • When you specify an exact role, IAM internally converts the role to a "principal ID" unique to that role. If you delete the role and recreate it with the same name, the role receives a new principal ID. This means that the new role doesn't automatically obtain access to the resource. This functionality is for security reasons, but it means that an accidental delete and restore can result in "broken" access.

When you grant permissions to only the account root, that set of permissions then becomes the limit of what the administrator of that account can delegate to their users and roles. The administrator can't grant a permission to the resource that you didn't grant to the account first.

Important

If you choose to grant cross-account access directly to the secret without using a role, then the secret must be encrypted by using a custom AWS KMS customer master key (CMK). A principal from a different account must be granted permission to both the secret and the custom AWS KMS CMK.

Run Everything in a VPC

Whenever possible, you should run as much of your infrastructure on private networks unaccessible from the public internet. To do this, host your servers and services in a virtual private cloud (VPC) provided by Amazon VPC. This is a virtualized private network accessible only to the resources in your account. It's invisible to or unaccessible by the public Internet, unless you explicitly configure the VPC with access. For example, you could add a NAT gateway. For complete information about Amazon VPC, see the Amazon VPC User Guide.

To enable secret rotation within a VPC environment, perform these steps:

  1. Configure your Lambda rotation function to run within the same VPC as the database server or service secret you want ro rotate. For more information, see Configuring a Lambda Function to Access Resources in an Amazon VPC in the AWS Lambda Developer Guide.

  2. The Lambda rotation function, running from within your VPC, must be able to access a Secrets Manager service endpoint. If the VPC has no direct internet connectivity, then you can configure your VPC with a private Secrets Manager endpoint that can be accessed by all of the resources in your VPC. For details, see Configuring Your Network to Support Rotating Secrets.

Tag Your Secrets

Several AWS services enable you to add tags to your resources. Secrets Manager lets you tag your secrets. A tag is a simple label that consists of a customer-defined key and an optional value. You can use these to make it easier to manage, search for, and filter the resources in your AWS account. When you tag your secrets, be sure to follow these guidelines:

  • Use a standardized naming scheme across all of your resources. Remember that tags are case sensitive.

  • Create tag sets that enable you to perform the following:

    • Security/access control – You can grant or deny access to a secret by checking the tags attached to the secret.

    • Cost allocation and tracking – You can group and categorize your AWS bills by tags. For more information, see Using Cost Allocation Tags in the AWS Billing and Cost Management User Guide.

    • Automation – You can use tags to filter resources for automation activities. For example, some customers run automated start/stop scripts that turn off development environments during non-business hours to reduce costs. You can create and then check for a tag that indicates whether a specific Amazon EC2 instance should be included in the shutdown.

    • AWS Management Console – Some AWS service consoles enable you to organize the displayed resources according to their tags, and to sort and filter by tags. AWS also provides the Resource Groups tool to create a custom console that consolidated and organizes your resources based on the tags. For more information, see Working with Resource Groups in the AWS Management Console Getting Started Guide.

You can use tags for almost anything and limited only by your imagination. However, remember that you must never store sensitive information for a secret in a tag.

You can tag your secrets when you create them or when you edit them.

For more information, see AWS Tagging Strategies on the AWS Answers website.