AWS Secrets Manager
User Guide

Rotating AWS Secrets Manager Secrets For One User that Supports Multiple Credentials

You can configure AWS Secrets Manager to automatically rotate the secret for a secured resource. This topic describes configuring rotation for an authentication system that allows you to create a single user with at least two credential sets.

As a best practice, we recommend that you set up a second "master" secret to store the credentials of a different user with permissions to delete and create credentials for the main user. This enables you to limit the permissions that you grant to the main user to only those required by your application. And it offloads the administrative tasks to the second user, which the end users cannot access. Secrets Manager accesses the second user by the rotation function of the main secret to delete the old access key and create a new one.

How Rotation Uses Labels to Manage a Single User with Multiple Credentials

The following example explains this scenario in more detail. It uses the example of a service that enables a user to have two separate "API keys" generated by the service and don't need to be generated by your rotation function:

  1. The scenario begins with an application accessing the secured resource (the database) by using one of the API keys stored in a secret with a single version "A". This A version of the secret has the staging label AWSCURRENT attached. The application retrieves the secret by requesting the version with the staging label AWSCURRENT (steps 1 and 2 in the following graphic). The application then uses the API key in that version of the secret to access the database (step 3) to retrieve the data it needs (step 4).

  2. The secret rotation function deletes the API key not currently referenced by secret version "A", and creates a new API key for the same user. The rotation function then creates a new "B" version of the secret (not a new secret, a new version of the same secret). It basically clones the details from the "A" version, except that it replaces the API key details with those from the newly created API key. This secret version "B" initially has the staging label AWSPENDING attached by the rotation process. Because the custom app is programmed to always request the AWSCURRENT label and that hasn't yet moved, the app continues to retrieve and use the original A version of the secret, for the API key to access the secured resource.

  3. After testing the "B" version of the secret to ensure that it works, the rotation process moves the AWSCURRENT label from the "A" version and attaches it to the new "B" version of the secret. This also automatically moves AWSPREVIOUS staging label to the version that had previously had the AWSCURRENT staging label. This allows it to act as "last known good" in case there's a need for recovery.

  4. The next request from the custom application now gets the "B" version of the secret because "B" now has the AWSCURRENT label. At this point, the customer application uses the API key in the new version of the secret. When the next rotation cycle occurs, the "B" version of the secret becomes the "A" version, and you start again in step a (earlier in this section).

Configuring Rotation to Alternate Credentials for a User

To configure a rotation mechanism for an authentication system that allows only one user, follow the steps in this procedure:

To configure rotation for a user with two sets of credentials

  1. Create your user in the authentication system that protects the secured resource. Make note of the user name and credentials that you set. For this discussion, we'll refer to them as Creds1 and Creds2.

  2. Create one Secrets Manager secret to store the details of the credentials you created in the previous step. This secret initially holds Creds1 for the user:

    1. Sign in to the Secrets Manager console at

    2. Choose New secret.

    3. For Select secret type, choose Other type of secret, including the user name and the first set of credentials. For example, enter two key-value pairs for the protected secret text. They could look something like:

      Key Value
      UserName <your user name>
      APIKey <your API key>
      APIKeyId <identifies which of the two API keys is stored in this version>
    4. For AWS KMS Encryption Key, choose the key you want to use to encrypt this secret, or leave the default set to the DefaultMasterKey for the account. To use the default key, the credentials that access the secret must be from the same account that owns the secret. If the user's credentials are from a different account, then you must create and specify a custom customer master key (CMK).

    5. For Select rotation period, choose or type the number of days between rotations.


      When you use the Secrets Manager console to configure rotation, by default, expiration is automatically enabled and set to the number of days between rotations + 7.

    6. For Select the Lambda rotation function, choose Create function.

    7. Choose Next step.

    8. Type a Secret name and optional Description. You can also choose to add tags if you want to.

    9. Choose Store secret.

  3. Examine your new secret to get the Amazon Resource Name (ARN) of the Lambda rotation function.

    1. On the Secrets list page, choose the name of the secret that you created in step 2.

    2. In the Secret details, choose the ARN of the rotation function to open it in Lambda.

    3. Use the following logic as the basis for writing your rotation function:

      • createSecret step:

        • Retrieve the AWSCURRENT version of the secret by using the GetSecretValue operation.

        • Extract the SecretString value from the secret and store it in a structure that you can modify.

        • Determine which API key is the inactive one - the one that isn't referenced in the AWSCURRENT version of the secret.

        • Issue commands to the service to delete the inactive API key that you determined in the previous step.

        • Issue commands to the service to create a new access key for the same user.

        • Overwrite the API key and its identifier in the copy of the secret's structure with those from the new API key that you just created. Keep all other details the same.

        • Store the modified copy of the protected secret text by passing it as the SecretString parameter in a call to PutSecretValue. The new version of the secret is labeled AWSPENDING.

      • setSecret step:

        • The setSecret step in this scenario doesn't do anything. The API key is created in the createSecret step, because you must have the API key and its identifier to store in the secret. You don't generate your own key like you do for most other scenarios.

      • testSecret step:

        • Retrieve the AWSPENDING version of the secret by using the GetSecretValue operation.

        • Issue commands to the secured resource to attempt to access it by using the API key that's in this version of the secret.

      • finishSecret step:

        • Move the label AWSCURRENT to the version labeled AWSPENDING. This automatically also moves the staging label AWSPREVIOUS to the secret that you just removed AWSCURRENT from.

        • (Optional) Remove the label AWSPENDING from its version of the secret.