Overview

This package's purpose in life is to make it faster and easier to call AWS STS to obtain temporary AWS credentials and write them out to ~/.aws/credentials (which is typically required when using MFA). It attempts to follow a batteries included philosophy. The 6 digit OATH tokens required for MFA authentication can either be provided directly via the --token argument or obtained automatically from a YubiKey by specifying the OATH credential in the --yk-oath-credential argument. The existing OATH credentials stored on your YubiKey can be found using the ykman list command assuming that you have theYubiKey Manager CLI installed.

Installation

Requires Python 3.6 or later and requirements from requirements.txt

pip install aws-mfa-v2
pip install aws-mfa-v2[yubikey] # YubiKey support

Usage

usage: aws-mfa [-h] [--mfa-profile MFA_PROFILE] [--token TOKEN]
               [--yk-oath-credential YK_OATH_CREDENTIAL] [--duration DURATION]
               [--write-env-file] [--force-refresh]

Obtain and make available temporary AWS credentials

optional arguments:
  -h, --help            show this help message and exit
  --mfa-profile MFA_PROFILE
                        Named AWS profile containg the mfa_serial for use in
                        obtaining temporary credentials.
  --token TOKEN         Six digit token code from your MFA device
  --yk-oath-credential YK_OATH_CREDENTIAL
                        YubiKey Manager OATH credential to use. For use with a
                        YubiKey. See 'ykman oath list' output for possible
                        values.
  --duration DURATION   STS token duration in seconds to request, defaults to
                        12 hours
  --write-env-file      Write the temp MFA credentials for hte profile
                        specified in --mfa-profile out to ~/.aws-mfa
  --force-refresh       Force a refresh even if the existing credentials are
                        not yet expired

Environment variable configuration

The following environment variables can be used to provide configuration

AWS_MFA_PROFILE - See --mfa-profile
AWS_MFA_YK_OATH_CREDENTIAL - See --yk-oath-credential
AWS_MFA_DURATION - See --duration
AWS_MFA_WRITE_ENV_FILE - See --write-env-file

Basic example

Steps to run

1. Install the latest version of the aws-mfa-v2 package from pypi

pip install aws-mfa-v2
pip install aws-mfa-v2[yubikey] # If you want YubiKey support

2. Call aws-mfa providing it the name of an existing AWS profile and a valid MFA token code

aws-mfa --mfa-profile existing-profile-name --token 123456 

3. Examine ~/.aws/credentials and see the newly added temporary credentials. Note: The script will insert the temporary STS credentials into a new named profile based on the named profile provided as the first positional argument to this script with "-mfa" appended.
4. Try calling an AWS service using the new named profile created by the script. Following the example above:

aws sts get-caller-identity --profile existing-profile-name-mfa

Configuration example to assume a role that requires MFA

Following the basic example above, here's example content for ~/.aws/config

# This is the user we use to obtain temporary credentials from AWS STS
[profile existing-profile-name]
mfa_serial = arn:aws:iam::123456789012:mfa/existing-user
region = us-east-1

# This profile name should match the credential name the aws-mfa script added to ~/.aws/credentials
[profile existing-profile-name-mfa]
source_profile = existing-profile-name 

# A role (in this case in a different AWS account) which requires MFA
[profile role]
source_profile = existing-profile-name-mfa 
role_arn = arn:aws:iam::098765432101:role/OrganizationAccountAccessRole

Once the configuration has been added you can use the role normally, ie:

aws sts get-caller-identity --profile role

YubiKey Support

Loading OATH tokens directly from a YubiKey is supported. You will need to provide the --yk-oath-credential argument or equivalent environment variable. A list of valid values can be found by running ykman oath list.

Example command to load an MFA token directly from a YubiKey:

aws-mfa --mfa-profile bks-rone --yk-oath-credential "Amazon Web Services:rone-cli@bookshare"

Exposing temporary credentials as environment variables

You can use the --write-env-file option to expose the credentials associated with the profile specified in --mfa-profile as environment variables. This is useful for compatibility with other software that may not support AWS CLI profiles properly. If you set the --write-env-file option credentials will be written to ~/.aws-mfa regardless of whether the credentials are refreshed in the current CLI run. An example usage follows:

aws-mfa --mfa-profile role --write-env-file
. ~/.aws-mfa
aws sts get-caller-identity --profile role-mfa