uber / assume-role-cli

CLI for AssumeRole is a tool for running programs with temporary credentials from AWS's AssumeRole API.

CLI for AssumeRole

CLI for AssumeRole is a CLI tool for running programs with temporary AWS credentials. It is intended to be used by operators for running scripts and other tools that don't have native AssumeRole support.

Example

Run myscript.py using the "admin" role in your AWS account:

assume-role --role admin ./myscript.py

Features

• Caches credentials with configurable expiry time (e.g. 15 mins before credentials are due to expire)
• Interoperability with awscli
• Supports MFA and attempts to autodetect when MFA is required
• Configurable via autoloading config file

Getting started

Set up base policy

assume-role requires the user performing the AssumeRole call has the iam:GetUser permission, to identify the username and use that as the session name (so the user's name shows up in the CloudTrail UI).

If MFA needs to be provided, assume-role also requires that the current user can list their own MFA devices.

Create the following policy (e.g. named "allow-assume-role-script") and attach this to users or groups who will be performing the AssumeRole:

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

(Replace <account-ID> with your AWS account ID.)

Create a configuration file

The --role option takes the full ARN of the role you want to assume (e.g. arn:aws:iam::1234567890:role/admin). To save humans on typing, you can specify the role prefix in configuration, so that you only need to use the named part of the role (i.e. --role admin).

Create a YAML-based configuration file called assume-role.yaml in root of your project directory:

role_prefix: arn:aws:iam::1234567890:role/

This allows you to execute assume-role by using the short role name, e.g.:

assume-role --role myrolename

To see other useful configuration, see Configuration options below.

Install and run it

You can install assume-role using go get:

go get -u github.com/uber/assume-role-cli/cli/assume-role

Now, run a command:

assume-role --role admin ./myscript.py

If you run it without a command to execute, environment variables will be printed to the console instead:

assume-role --role admin
AWS_ACCESS_KEY_ID=ASIAQWERTYUIOPASDFGHJKL
AWS_SECRET_ACCESS_KEY=8qLCbGYKhOWXU38ZVj+RhY1f7+zvuZ3vHMIhNGTxnhs=
AWS_SESSION_TOKEN=Wt5owtYQ/zObHy+8KLAgejM/CKGlt3Fa67PpRt+dVaDv4+NqmuFBu6VCkV1jmtfr82eABf9R2sN76ezZ1NIaaKnnkx8fk1WIH7jb7e5KYD0gsaOaAFIKEsMBMixvrFcxTe4Xth8D7lCohZZLTU2I2kazJxOrE249Xwq61hh1ZTezKHNvqek9BbItQdaWoniEkJz9vtTgXYSxnBJoV+VIsSa7KyDcLrteHVKdLx7qkxvsZvXkvmPRnQtnrGBeT3pm7LIlc2xOiKgAxuDf8gW5RWORrz71DdzFfPVqi0lAw5Hx0Qx/9gipuTPr5DICUzah8l64w4t21R0L9T1r84NAjA==

That's it!

Configuration options

Configuration is done by placing a file named assume-role.yaml in your project directory, or in ~/.aws.

assume-role will locate this file if you are running it from within a project subdirectory.

The following configuration options are available:

• refresh_before_expiry: <duration> (default 15m)

  When you run assume-role credentials are cached and subsequent invocations just read from the cache. When the credentials expire, a refresh is triggered (doing the AssumeRole again).

  This value controls how long before the credentials are due to expire we'll refresh them anyway. This is so that credentials don't expire in the middle of running a command.

• role_prefix: <string> (default: empty)

  To avoid typing the full ARN at the command-line every time, you can a prefix so you no longer have to type:

  assume-role --role arn:aws:iam::123:role/admin
  

  Instead you can do:

  assume-role --role admin
  

  By configuring arn:aws:iam::123:role/ as the prefix.

• profile_name_prefix: <string> (defaults to empty, which uses your AWS account ID instead)

  When you do an assume-role, the credentials are saved to ~/.aws/credentials under a name in the format <profile_name_prefix>-<role_name>. This allows you to then use the profile with other tools using the AWS_PROFILE variable, or for example when executing awscli directly: aws --profile=myaccount-admin s3 ls bucket://mybucket/.

  This is a convenience helper but is generally not needed if you always just run all your commands through assume-role.

assume-role-cli's Issues

Support use as a git credential helper

I would be nice to be able to use this to wrap the aws codecommit command as a git credential helper, e.g.:

$ git config credential.helper
!assume-role --role myrole aws codecommit credential-helper $@

But this fails with:

$ git pull
Enter MFA token: ERROR: 2 errors occurred:

* error trying to AssumeRole without MFA: AccessDenied: Access denied
	status code: 403, request id: 42a4c511-cbd4-11e8-a46c-f1a97ee7f6a3
* error trying to AssumeRole with MFA: ValidationError: 2 validation errors detected: Value 'protocol=https' at 'tokenCode' failed to satisfy constraint: Member must have length less than or equal to 6; Value 'protocol=https' at 'tokenCode' failed to satisfy constraint: Member must satisfy regular expression pattern: [\d]*
	status code: 400, request id: 4308b78d-cbd4-11e8-a46c-f1a97ee7f6a3; giving up
Username for 'https://git-codecommit.us-east-1.amazonaws.com/v1/repos/payment-config-management': 
Password for 'https://git-codecommit.us-east-1.amazonaws.com/v1/repos/payment-config-management': 
^C

aws codecommit is able to do this (with the MFA prompt) but using that command directly means you will be prompted for MFA again (instead of pulling from assume-role-cli's cache).

Make temporary credential duration configuration

At the moment, the length of temporary credentials is hardcoded to 1 hour . AWS provides an option to set these values from anywhere between 15 mins to 12 hours. Some of the use-cases might require credentials longer than 1 hour.

It would be nice to have a configuration option to do it.

Travis build failure because of missing environment variables

Travis does not allow access to encrypted environment variables for PRs from a different repository (because of security reasons). This will always fail the build because some of the tests rely on these environment variables. On such example is this build.

My proposed solution is to skip the test if the environment variables are missing. These tests will be run anyways when the PR is merged.

Start an infinite loop and get stuck on Windows

There is a bug with this cli when running on Windows, the assume-role.exe command will start an infinite loop and get stuck, the total memory use will reach 99%. So a few lines of codes need to be commented out or fix and the assume-role.exe needs to be recreated by go build command

Add --refresh flag

It would be nice to force refresh the credentials (i.e. bypass and update the cache).

install not working?

The install does not seem to work?

go get -u github.com/uber/assume-role-cli

It doesn't seem to install a binary?