Doppler rotates AWS IAM user keys by leveraging role assumption using a supplied AWS IAM role.


  • Understand the Doppler rotation methodology
  • AWS Account
    • Ability to create IAM roles and Policies
    • Ability to access IAM users
    • [Optional] Ability to update or add IAM users


Each IAM user can be issued access keys, which consist of an access key ID and a secret access key. These values enable programmatic access to resources in AWS. Each IAM user may have up to two pairs of access keys at any time (or none). By rotating the access keys instead of the IAM user itself, the user name and ARN can be maintained while rotating the sensitive properties of the user.


Two access key limit

Because an IAM user may only have two access keys at any time, it should be assumed that Doppler will delete one access key pair each time we rotate the keys.


There are four steps to configure AWS IAM rotation

  1. Create an IAM policy for role assumption
  2. Create an IAM role for role assumption
  3. Retrieve or create the IAM user to be rotated
  4. Create the rotated secret in Doppler

Create the Managing User IAM Role Policy

Doppler uses an IAM role you provide to assume into your account. This role requires a specific IAM policy.

  1. Navigate to the Create New Policy section in the AWS IAM console
  2. Switch to the JSON tab
  3. Enter the following minimally scoped policy:
        "Version": "2012-10-17",
        "Statement": [
                "Effect": "Allow",
                "Action": [
                "Resource": "arn:aws:iam::*:user/doppler/rotate/*"


Resource Filtering

AWS IAM does not support providing a path when creating an IAM user through the UI. You can provide a path when creating or updating a user via the API or CLI. We highly recommend providing a path - /doppler/rotate/ is used above - to allow resource filtering to be utilized. If a path is not set on the IAM user, * must be used for the resource value in your IAM policy.

  1. Optionally provide tags
  2. Name your policy and hit create

Create the Managing User IAM Role

To rotate your IAM user keys, Doppler uses an IAM role you provide to assume into your account

  1. Navigate to the create role section of the AWS IAM console
  2. Select AWS account for the Trusted entity type
  3. Select Another AWS account under An AWS account
    1. Enter 299900769157 for the Account ID. This is the account ID for Doppler's rotator service.
  4. Under Options check Require external ID
    1. Enter your workplace slug for the External ID. You can obtain your workplace slug by visiting the Doppler dashboard. In the URL, grab the value after /workplace/
    2. Leave require MFA unchecked
  1. On the next screen, search for and select the policy you created above. Click next
  2. Name your role and optionally complete the other fields
  3. Create your role. Make note of the ARN

Obtain the AWS IAM user name

  1. If rotating an existing user, obtain the user name of the IAM user to rotate from the AWS console,
    1. Ensure the user has no access keys attached to it. You can locate them on the Security Credentials tab for the specific user. If any exist, they must be deleted - just be careful if they're already in use.
    2. Optional but highly recommended: Add a path to the user using the API or CLI - the option is not supported in the UI. We recommend a path of /doppler/rotate/. This enables tighter resource filtering in the IAM policy. Otherwise, Doppler will be granted access to all IAM users using *
  2. If rotating a new user, create it via the CLI or API so that a path can be specified. We recommend /doppler/rotate/, which is used in the policy above.

Rotated Secret Configuration

  1. Navigate to the Doppler config you would like to add an AWS IAM rotated secret to
  2. Click the dropdown next to Add Secret and select Add Rotated Secret
  1. In the modal, select AWS IAM User Keys
  2. Name your integration and enter the ARN for the role you created above
  1. Provide a name for the rotated secret, which will be the prefix for the secrets that are injected into your config.
  2. Enter the user name of the AWS IAM user you obtained above
  1. Set the interval of how often you want to rotate your secret instances

Injected Secrets

For each AWS IAM user rotated secret, a set of secrets are injected into the applicable config. They are prefixed with the name provided for the rotated secret.

For example, a rotated secret named MY_IAM_USER would have the following secrets injected: