Awsume

04 November 2022

We use AWS at work… I mean, who doesn’t these days? I have learned to like it, despite the myriad of flaws and frustration it comes with.

The context

The way we’re set up is simple: an account for each project/environment, with a central account used as a bastion. As such, you could end up with this type of architecture:

AWS Bastion account
 |-- Management account
 |-- Security account
 |-- Production account
 |-- Development account
 |-- Infrastructure account 
 |-- Public account
 |-- etc...

All users have access to the bastion and, from there, they assume the relevant role that gives them the right accesses, in the account required.

aws sts assume-role --role-arn "arn:aws:iam:123456789012:role/example-role" --role-session-name example-cli-session

Neat, right?

The problem

WRONG! I mean, yes, in theory, wonderful; segregation of accounts, accesses, resources… A Sysadmin’s dream! Until you realise the limitations: role chaining only allows sessions of max 1 hour:

Note: Role chaining limits your AWS CLI or AWS API role session to a maximum of one hour and can’t be increased.

The other inconvenience is having to input your MFA in every 60 minutes. Surely your devs have given out about this already!

Nightmare!

The solution

In comes: AWSume: a convenient way to manage session tokens and assume role credentials.

Quick examples from their own site:

Examples

The concept is simple:

awsume <profile_name>

First login of the day:

$: awsume prod
Enter MFA token: ******
Session token will expire at 2022-11-05 01:37:55
[prod] Role credentials will expire 2022-11-04 14:37:55

If you need to switch roles:

awsume dev
Session token will expire at 2022-11-05 01:37:55
[dev] Role credentials will expire 2022-11-04 14:39:18

😯 Notice how the MFA was not asked this time?

Features

• Reads your credentials from ~/.aws/config and ~/.aws/credentials
• Extensible - add custom hooks to make awsume do whatever you need it to (SAML provider, profile provider, etc.)
• Set your environment variables to your AWS credentials so any cli/api call you make uses those credentials
• Use MFA-authenticated credentials on the command-line
• Use assume-role credentials to your on the command-line
• Cache MFA-authenticated credentials for up to 12 hours
• Role-chain as many role assumptions as you need
• Show the commands you need to export environment variables in another terminal (awsume -s)
• Export awsume’d credentials into a profile in the ~/.aws/config and ~/.aws/credentials files (awsume -o)
• Auto-refresh assume-role credentials as long as source credentials are valid, up to 12 hours (awsume -a)
• Get a pretty listing of your awsume-able profiles (awsume -l)
• Autocomplete your awsume-able profiles
• Assume arbitrary role-arns from the command-line, using full role arn or short-hand syntax (with optional partition defaulting to aws, awsume --role-arn [partition]:{account_id}:{role_name})
• Set a custom session name for assume-role credentials (awsume --session-name)
• Assume a role for a custom duration for up to 12 hours or whatever the role’s maximum is configured as (awsume --role-duration)
• Use separate config/credentials files, also supports the appropriate environment variables (awsume --config-file ... --credentials-file ...)

Installation

For detailed instructions, click here.

Installation:

pip install awsume