Assumes an IAM role via awscli STS call, injecting temporary credentials into shell environment
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


The IAM Role Injector is a tool for easily assuming an IAM Role with Multi-Factor Authentication (MFA). It manipulates environment variables to allow codebases already using AWS credentials to use IAM roles with minimal to no refactoring. In the same vein, the Role Injector can also be used to help users using the command line tools to assume a role.


  • AWS CLI configured correctly, storing 'aws_access_key_id' and 'aws_secret_access_key' in either environment variables -OR- in ~/.aws/credentials
  • One of the following Scenarios apply:

Scenario One: Federated AWS Accounts

  • At least two AWS Accounts:
    • AWS Account 1 must have a policy that includes sts:AssumeRole to AWS Account 2
    • AWS Account 2 must have a Trust Relationship on a role that references AWS Account 1
  • AWS Account 1 may now assume the role in AWS Account 2 that has the Trust Relationship

Scenario Two: Single AWS Account

  • An IAM User Account with a policy that include sts:Assume on an IAM Role.
  • The IAM Role has a trust relationship that allows entities in the account to assume it
  • In this case, AWS Account 1 and AWS Account 2 are the same.


  1. Install AWS CLI
  2. Configure AWS CLI with required credentials, either as Environment Variables or by running 'aws configure'
  3. wget -N -O ~/

Command Line Usage

source ~/ {sourceAccountNumber} {username} {destinationAccountNumber} {rolename}
  • sourceAccountNumber: AWS Account Number of AWS Account 1
  • username: AWS Account 1 username
  • destinationAccountNumber: AWS Account Number of AWS Account 2
  • rolename: the name of the role to assume in AWS Account 2 that has the Trust Relationship to AWS Account 1

Calling the script with 'source' is required for the environment variables to persist past the runtime of the script.

The script will also protect your original credentials if you chose to store them as environment variables.


Please report any bugs to:


Open an issue or a pull request if you see how we can improve the script!


iam-role-injector is released under the BSD 3-Clause License.