assume-role-js v1.1.1
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