Skip to content
Easily assume AWS roles in your terminal.
Go Makefile
Branch: master
Clone or download
Latest commit 06a34b0 Dec 24, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
vendor Add missing vendored deps Apr 6, 2017
.gitignore Initial commit. Jan 26, 2016
LICENSE Create LICENSE Dec 24, 2018
Makefile Build linux, darwin and windows binaries Jun 12, 2017 Fix assume-role alias for zsh and bash Nov 17, 2017
circle.yml Add circle.yml Apr 6, 2017
main.go Set $ASSUMED_ROLE in environment Feb 8, 2018

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::1234: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 $@);}'
  • bash
function assume-role { eval $( $(which assume-role) $@); }


  • Cache credentials.
You can’t perform that action at this time.