Awsume 4 Released

For detailed documentation and usage, visit the official awsume docs at awsu.me.

Update (April 2020)

"Trek10's help in providing the ability to export credentials to an AWS credentials profile makes my life so much easier.” - Ryan Curtis, SwanLeap

We've worked hard to introduce a few new features based on customer feedback and need:

• Support for invoking awsume from Python scripts. If you just want to get a boto3 session object for an awsume profile, just execute the following code:

  from awsume.awsumepy import awsume
  awsume('myprofile')
  

• Supports fuzzy-matching the given profile name. So if your profile is named dev-admin and you run awsume dev-admni, awsume should be able to match the given mistyped profile name to the intended profile
• Support for SAML1 in addition to SAML2
  • This comes to us courtesy of @tmclaughbos
• Support for SAML profiles
  • Another very useful contribution from @tmclaughbos
• Adds a --principal-arn command-line option to support selecting the SAML assertion principal arn
• Adds chmod to awsume cache file operations
  • A fantastic contribution from lazzurs
• Supports exporting awsume'd credentials to a profile in the ~/.aws/credentials file
• Supports role chaining (awsume-ing role profiles who's source_profile points to another role profile)
• Exports role credential expiration time to environment variables
  • An awesome contribution from parkeyparker

Awsume is a tool we use here at Trek10 pretty often. It's a tool we internally developed, open sourced, and continually improve. While we have blogged about it quite a bit in the past, we recently released a new major version, so I wanted to publish a refresher. I also wanted to talk about why you should incorporate it into your workflow, in case you aren't already.

Ultimately it's a CLI that helps you manage your local environment's AWS credentials (roles, access keys, session tokens, etc). Awsume lets you work faster while making it easier to stay secure with MFA.

Background

Here at Trek10 we have multiple client AWS accounts we have to work with. Following best practices, we utilize cross-account IAM roles for access into those accounts. We also use the aws:MultiFactorAuthPresent condition to enforce that Trek10 employees use MFA.

"Condition": {
  "Bool": {
    "aws:MultiFactorAuthPresent": "true"
  }
}

This is great, but there's still pain in managing your config and credentials files. For each role you want to assume (each client account you want to assume into), you need to make sure you have a profile defined. Although it is error-prone, it's not the worst thing in the world because it's a one-and-done kinda deal. However, where a major headache comes in is making use of those profiles.

You have to remember to pass --profile <profile_name> to each AWS CLI command, otherwise the command will be run against your default profile (if you have one defined). Then, assuming you enforce MFA as we do, you have to re-enter your MFA token whenever the role credentials expire (default 1 hour), since the AWS CLI uses the MFA token to get the role credentials.

What makes awsume different?

In our case, awsume will use the MFA token call get-session-token on the role's source_profile (the user you'll be calling assume-role with), which returns credentials that are valid for 12 hours.

Awsume will then cache those credentials for as long as they're valid. When you want to assume a role using that source_profile, awsume will use those cached credentials, only requiring you to use your MFA code once every 12 hours. Even better, awsume will export those credentials to your environment as environment variables, so you don't even need to remember to pass --profile <profile_name> with every command.

If you need to just assume a role one time with your current credentials and don't want to mess with configuring your config and credentials files, you can do a quick:

awsume --role-arn <account_id>:<role_name> # here we're using short syntax, but you could use the entire role arn

This is perfect for debugging things like lambda role permissions. If you configure the trust policy on that role to trust the account itself too (not just the lambda service), you can assume the lambda role and debug the permissions locally.

Plugins?

Awsume is also extensible, so you can make your own plugins to hook into awsume at various steps (see the plugin development documentation for more details). This is how we developed the awsume console plugin, which allows you to open the console in your default browser with your assume-role credentials.

If you authenticate with SAML, you can even develop your own plugins to provide the SAML assertion so awsume can handle the rest for you.

Where can I get awsume?

Awsume is available through pip. Just follow the quickstart guide here and you'll be good to go.

If you experience any issues with awsume, open an issue. Follow us @Trek10Inc for more awesome serverless and AWS-focused content.