https://github.com/uber/assume-role-cli
CLI for AssumeRole is a tool for running programs with temporary credentials from AWS's AssumeRole API.
https://github.com/uber/assume-role-cli
Last synced: 7 months ago
JSON representation
CLI for AssumeRole is a tool for running programs with temporary credentials from AWS's AssumeRole API.
- Host: GitHub
- URL: https://github.com/uber/assume-role-cli
- Owner: uber
- License: apache-2.0
- Created: 2018-06-02T14:44:57.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-03-19T22:42:17.000Z (almost 3 years ago)
- Last Synced: 2024-06-20T00:35:40.295Z (over 1 year ago)
- Language: Go
- Homepage:
- Size: 80.1 KB
- Stars: 47
- Watchers: 1,519
- Forks: 12
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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:::user/${aws:username}"
}
]
}
```
(Replace `` 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: ` (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: ` (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: ` (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 `-`. 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.