assume-role-js

A simple CLI tool to assume AWS IAM role, written in TypeScript.

This project aims at a drop-in replacement of the most common and basic use cases of https://github.com/uber/assume-role-cli, which has not been updated for years and people keep complaining about some critical issues (such as not usable on windows).

System requirements

• Node.js v16
• AWS CLI v2

Also, please make sure that you have used aws configure to set up the basic IAM user credentials as your default profile. See https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html#cli-configure-quickstart-config for more details.

Install

Run the command below to install:

npm install -g assume-role-js

Features

Run commands inline with assumed role

assume-role-js --role arn:aws:iam::123456789:role/developer aws s3 ls

This line will assume the arn:aws:iam::123456789:role/developer role and use it to run aws s3 ls, without polluting your CLI system environment variables.

Note: same feature exists on https://github.com/uber/assume-role-cli

Print out the system environment variables needed by AWS CLI to run as assumed-role

assume-role-js --role arn:aws:iam::123456789:role/developer

Without inline AWS command, it will just print the system environment variables.

Output example:

AWS_ACCESS_KEY_ID=xxxx
AWS_SECRET_ACCESS_KEY=xxxx
AWS_SESSION_TOKEN=xxxx

Note: same feature exists on https://github.com/uber/assume-role-cli

Cache credentials

You may need to run multiple commands with assumed role, and it is tedious to enter the MFA token code every time.

We got you covered by caching credentials and expiration time via AWS Named Profile without the need to re-assume role every time.

The profile name is automatically generated by the role arn.

For example, role arn arn:aws:iam::123456:role/developer will generate profile name as 123456-developer.

Note: same feature exists on https://github.com/uber/assume-role-cli

Autodetect and use MFA device

This feature requires the IAM user has iam:GetUser and iam:ListMFADevices permission.

Example policy to attach is:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "iam:GetUser",
        "iam:ListMFADevices"
      ],
      "Resource": "arn:aws:iam::<account-ID>:user/${aws:username}"
    }
  ]
}

See https://github.com/uber/assume-role-cli#getting-started for more details

Note: same feature exists on https://github.com/uber/assume-role-cli

Development

If you would like to make changes to this tool, simply clone the repo.

Install dependencies

yarn

Compile and bundle the runnable

yarn build

Hot link the runnable to system

npm link

Run development build

yarn start --role arn:aws:iam::123456789:role/developer

yarn start --role arn:aws:iam::123456789:role/developer aws s3 ls

Troubleshooting

Getting error of "cannot be loaded because running scripts is disabled on this system"

This might happen when trying to run the script under PowerShell due to the execution policy.

Solution:

powershell -ExecutionPolicy Bypass