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. In this topic we describe how to configure rotation for an authentication system that allows you to create a single user, but for which you can have at least two credential sets. An example for this is an IAM user that can have two access keys live at the same time. Your secret points to the newest access key until it is time to rotate. Then you delete the oldest one and create a new one in its place. Then you point your secret to the new key. Clients can continue to access the secured resource with the "old" secret while the password change is in progress, with no downtime because you work on the credentials that are not currently accessed by the users.

As a best practice, we recommend that you set up a second "master" secret to store the credentials of a different IAM user that has permissions to delete and create access keys for the main user. This enables you to limit the permissions granted to the main user to only those required by your application, and offloads the administrative tasks to the second user to which the end users do not have any access. The second user is accessed only 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 explicitly uses the example of IAM access keys because they are automatically generated by IAM and do not need to be generated by your rotation function:

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

  2. The rotation function deletes the access key that is not currently referenced by secret version "A" and creates a new access 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 access key's key ID and secret key details with those from the new access 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 has not yet moved, the app continues to retrieve and use the original A version of the secret for access keys 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 is a need for recovery.

  4. The next request from the custom app now gets the "B" version of the secret because "B" now has the AWSCURRENT label. At this point, the customer app is dependent upon 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. above.

Configuring Rotation to Alternate Credentials for a User

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

To configure rotation for a user that has 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 AWS Secrets Manager secret to store the details of the credentials you created in the previous step. This secret will initially hold Creds1 for the user:

    1. Sign in to the AWS 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, if you're using an IAM users and access keys, enter three key value pairs for the protected secret text. They could look something like:

      Key Value
      UserName <your user name>
      AccessKeyId <your access key id>
      SecretKey <your secret key>
    4. For AWS KMS Encryption Key, select 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 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 wish.

    9. Choose Store secret.

  3. Examine your new secret to get the ARN of the Lambda rotation function.

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

    2. In the Secret details / Secret rotation section, 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 using the GetSecretValue operation.

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

        • Determine which access key is not the one referenced in the AWSCURRENT version of the secret.

        • Issue IAM API commands to delete the access key determined in the previous step.

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

        • Overwrite the access key ID and secret key in the copy of the secret's structure with those from the new key you just created. Keep the username and any other details the same.

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

      • setSecret step:

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

      • testSecret step:

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

        • Issue commands to the secured resource to attempt to access it using the access key found in this version of the secret.

      • finishSecret step:

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

        • Remove the label AWSPENDING from its version.