aws-mfa-v2 0.3.5

Description:

awsmfav2 0.3.5

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 the YubiKey Manager CLI installed.
Installation
Requires Python 3.8 or later and uses Poetry for dependency management
pip install aws-mfa-v2
pip install aws-mfa-v2[yubikey] # YubiKey support

Usage
usage: aws-mfa [-h] [--mfa-profile MFA_PROFILE] [--sts-creds-profile STS_CREDS_PROFILE] [--token TOKEN]
[--yk-oath-credential YK_OATH_CREDENTIAL] [--duration DURATION] [--write-env-file] [--force-refresh]
[--min-remaining MIN_REMAINING]

Obtain and make available temporary AWS credentials

options:
-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.
--sts-creds-profile STS_CREDS_PROFILE
Optional, the named AWS profile where the AWS STS credentials will be stored.
--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 the profile specified in --mfa-profile out to ~/.aws-mfa. If set via environment
variable this should be set to true or false
--force-refresh Force a refresh even if the existing credentials are not yet expired
--min-remaining MIN_REMAINING
Set a minimum number of seconds existing credentials must be valid for before a refresh is performed

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

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


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


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.
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

Contribution Guidelines
I look forward to accepting more contributions to this project. The requirements are very simple right now:

Format the code with Black
Submit a PR

Release Process
The current release process is:

poetry build
poetry publish