Awesome Open Source
Awesome Open Source

This tool will request and set temporary credentials in your shell environment variables for a given role.


On OS X, the best way to get it is to use homebrew:

brew install remind101/formulae/assume-role

If you have a working Go 1.6/1.7 environment:

$ go get -u

On Windows with PowerShell, you can use

$ scoop bucket add extras
$ scoop install assume-role


Setup a profile for each role you would like to assume in ~/.aws/config.

For example:


[profile usermgt]
region = us-east-1

[profile stage]
# Stage AWS Account.
region = us-east-1
role_arn = arn:aws:iam:🔢role/SuperUser
source_profile = usermgt

[profile prod]
# Production AWS Account.
region = us-east-1
role_arn = arn:aws:iam::9012:role/SuperUser
mfa_serial = arn:aws:iam::5678:mfa/eric-holmes
source_profile = usermgt


aws_access_key_id = AKIMYFAKEEXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/MYxFAKEYEXAMPLEKEY


In this example, we have three AWS Account profiles:

  • usermgt
  • stage
  • prod

Each member of the org has their own IAM user and access/secret key for the usermgt AWS Account. The keys are stored in the ~/.aws/credentials file.

The stage and prod AWS Accounts have an IAM role named SuperUser. The assume-role tool helps a user authenticate (using their keys) and then assume the privilege of the SuperUser role, even across AWS accounts!


Perform an action as the given IAM role:

$ assume-role stage aws iam get-user

The assume-role tool sets AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY and AWS_SESSION_TOKEN environment variables and then executes the command provided.

If the role requires MFA, you will be asked for the token first:

$ assume-role prod aws iam get-user
MFA code: 123456

If no command is provided, assume-role will output the temporary security credentials:

$ assume-role prod
export ASSUMED_ROLE="prod"
# Run this to configure your shell:
# eval $(assume-role prod)

Or windows PowerShell:

# Run this to configure your shell:
# assume-role.exe prod | Invoke-Expression

If you use eval $(assume-role) frequently, you may want to create a alias for it:

  • zsh
alias assume-role='function(){eval $(command assume-role [email protected]);}'
  • bash
function assume-role { eval $( $(which assume-role) [email protected]); }


  • [ ] Cache credentials.

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Golang (164,214
Amazon Web Services (38,681
Powershell (19,571
Role (17,527
Credentials (5,992
Iam (2,915
Sts (75
Iam Role (60