Rotating AWS Secrets Manager secrets for one user supporting multiple credentials - AWS Secrets Manager

Rotating AWS Secrets Manager secrets for one user supporting multiple credentials

You can configure AWS Secrets Manager to automatically rotate the secret for a secured resource. This topic covers 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 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 you grant to the main user to those required by your application. By doing so, you can offload the administrative tasks to the second user, which the end users cannot access. The rotation function of the main secret accesses the second user 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 not 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. The application then uses the API key in that version of the secret to access the database (step 3) to retrieve the data the application 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, but a new version of the same secret. The rotation function clones the details from the "A" version, except the function 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 application always request the AWSCURRENT label and the label hasn't moved, the application 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 the secret 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 with the staging label AWSCURRENT. This allows the secret to act as "last known good" in case there's a need for recovery.

  4. The next request from the custom application now receives 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.

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, 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. The pairs can be similar the examples:

      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 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 credentials reside in 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, Secrets Manager automatically enables expiration and sets 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. Optionally, you can add tags.

    9. Choose Store secret.

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

    1. On the Secrets list page, choose the name of the secret you created in 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 by using the GetSecretValue operation.

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

        • Determine the inactive API key - the one not referenced in the AWSCURRENT version of the secret.

        • Issue commands to the service to delete the inactive API key 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 the identifier in the copy of the secret structure with those from the new API key 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. Secrets Manager labels the new version of the secret with AWSPENDING.

      • setSecret step:

        • The setSecret step in this scenario doesn't do anything. You created the API key in the createSecret step, because you must have the API key and the identifier to store in the secret. You don't generate your own key as you might 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 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 you just removed AWSCURRENT from.

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