Skip to content

Commit

Permalink
Updated README.md on points that confused me
Browse files Browse the repository at this point in the history
I've never used assume role on the CLI before so these additional words seemed to help my understanding.
  • Loading branch information
russellballestrini authored Jun 2, 2017
1 parent 40a3af7 commit f0bd2f3
Showing 1 changed file with 28 additions and 8 deletions.
36 changes: 28 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
This is a small utility that makes it easier to use the `aws sts assume-role` command:
This tool will request and set temporary credentials in your shell environment variables for a given role.

## Installation

Expand All @@ -8,31 +8,51 @@ On OS X, the best way to get it is to use homebrew:
brew install remind101/formulae/assume-role
```

If you have a working Go 1.6 environment:
If you have a working Go 1.6/1.7 environment:

```bash
$ go get -u github.com/remind101/assume-role
```

## Configuration

The first step is to setup profiles for the different roles you'd like to assume in `~/.aws/config`. Follow the official AWS docs on how to do this at https://docs.aws.amazon.com/cli/latest/userguide/cli-roles.html.
Setup a profile for each role you would like to assume in `~/.aws/config`.

**Example**
**For example, `~/.aws/config`:**

```ini
[profile usermgt]
# IAM user management AWS Account.
region = us-east-1
aws_access_key_id = AKIMYFAKEEXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/MYxFAKEYEXAMPLEKEY

[profile stage]
# Stage AWS Account.
region = us-east-1
role_arn = arn:aws:iam::1234:role/SuperUser
mfa_serial = arn:aws:iam::5678:mfa/eric-holmes
source_profile = default
usermgtsource_profile = usermgt

[profile prod]
# Production AWS Account.
region = us-east-1
role_arn = arn:aws:iam::9012:role/SuperUser
source_profile = default
mfa_serial = arn:aws:iam::5678:mfa/eric-holmes
source_profile = usermgt
```

Reference: https://docs.aws.amazon.com/cli/latest/userguide/cli-roles.html

In this example, we have three AWS Account profiles:

* usermgt
* stage
* prod

Each member of the org has their own IAM user and access/secret key in the `usermgt` AWS Account.
The `stage` and `prod` AWS Accounts have an IAM role named `SuperUser`.
The `assume-role` tool helps a user authenticate and then assume the privilege of the `SuperUser` role, even across AWS accounts!

## Usage

Perform an action as the given IAM role:
Expand All @@ -41,7 +61,7 @@ Perform an action as the given IAM role:
$ assume-role stage aws iam get-user
```

The command provided after the role will be executed with the `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` environment variables set.
The `assume-role` tool sets `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` and `AWS_SESSION_TOKEN` environment variables and then executes the command provided.

If the role requires MFA, you will be asked for the token first:

Expand Down

0 comments on commit f0bd2f3

Please sign in to comment.