Package: vodou-aws-mfa
aws-mfa: Easily manage your AWS Security Credentials when using Multi-Factor Authentication (MFA)aws-mfamakes it easy to manage your AWS SDK Security Credentials when Multi-Factor Authentication (MFA) is enforced on your AWS account. It automates the process of obtaining temporary credentials from theAWS Security Token Serviceand updating yourAWS Credentialsfile (located at~/.aws/credentials). Traditional methods of managing MFA-based credentials requires users to write their own bespoke scripts/wrappers to fetch temporary credentials from STS and often times manually update their AWS credentials file.The concept behindaws-mfais that there are 2 types of credentials:long-term- Your typcial AWS access keys, consisting of anAWS_ACCESS_KEY_IDandAWS_SECRET_ACCESS_KEYshort-term- A temporary set of credentials that are generated by AWS STS using yourlong-termcredentials in combination with your MFA device serial number (either a hardware device serial number or virtual device ARN) and one time token code. Your short term credentials are the credentials that are actively utilized by the AWS SDK in use.If you haven't yet enabled multi-factor authentication for AWS API access, check out theAWS articleon doing so.Installation:Option 1$pipinstallaws-mfaOption 21.Clonethisrepo2.$pythonsetup.pyinstallCredentials File SetupIn a typical AWS credentials file (located at~/.aws/credentials), credentials are stored in sections, denoted by a pair of brackets:[]. The[default]section stores your default credentials. You can store multiple sets of credentials using different profile names. If no profile is specified, the[default]section is always used.By default long term credential sections are identified by the convention[<profile_name>-long-term]and short term credentials are identified by the typical convention:[<profile_name>]. The following illustrates how you would configure you credentials file usingaws-mfawith your default credentials:[default-long-term]aws_access_key_id=YOUR_LONGTERM_KEY_IDaws_secret_access_key=YOUR_LONGTERM_ACCESS_KEYAfter runningaws-mfa, your credentials file would read:[default-long-term]aws_access_key_id=YOUR_LONGTERM_KEY_IDaws_secret_access_key=YOUR_LONGTERM_ACCESS_KEY[default]aws_access_key_id=<POPULATED_BY_AWS-MFA>aws_secret_access_key=<POPULATED_BY_AWS-MFA>aws_security_token=<POPULATED_BY_AWS-MFA>Similarly, if you utilize a credentials profile nameddevelopment, your credentials file would look like:[development-long-term]aws_access_key_id=YOUR_LONGTERM_KEY_IDaws_secret_access_key=YOUR_LONGTERM_ACCESS_KEYAfter runningaws-mfa, your credentials file would read:[development-long-term]aws_access_key_id=YOUR_LONGTERM_KEY_IDaws_secret_access_key=YOUR_LONGTERM_ACCESS_KEY[development]aws_access_key_id=<POPULATED_BY_AWS-MFA>aws_secret_access_key=<POPULATED_BY_AWS-MFA>aws_security_token=<POPULATED_BY_AWS-MFA>The default naming convention for the credential section can be overriden by using the--long-term-suffixand--short-term-suffixcommand line arguments. For example, in a multi account scenario you can have one AWS account
that manages the IAM users for your organization and have other AWS accounts for development, staging and production
environments.After runningaws-mfaonce for each environment with a different value for--short-term-suffix, your credentials
file would read:[myorganization-long-term]aws_access_key_id=YOUR_LONGTERM_KEY_IDaws_secret_access_key=YOUR_LONGTERM_ACCESS_KEY[myorganization-development]aws_access_key_id=<POPULATED_BY_AWS-MFA>aws_secret_access_key=<POPULATED_BY_AWS-MFA>aws_security_token=<POPULATED_BY_AWS-MFA>[myorganization-staging]aws_access_key_id=<POPULATED_BY_AWS-MFA>aws_secret_access_key=<POPULATED_BY_AWS-MFA>aws_security_token=<POPULATED_BY_AWS-MFA>[myorganization-production]aws_access_key_id=<POPULATED_BY_AWS-MFA>aws_secret_access_key=<POPULATED_BY_AWS-MFA>aws_security_token=<POPULATED_BY_AWS-MFA>This allows you to access multiple environments without the need to runaws-mfaeach time you want to switch
environments.If you don't like the a long term suffix, you can omit it by passing the valuenonefor the--long-term-suffixcommand line argument. After runningaws-mfaonce for each environment with a different value for--short-term-suffix, your credentials file would read:[myorganization]aws_access_key_id=YOUR_LONGTERM_KEY_IDaws_secret_access_key=YOUR_LONGTERM_ACCESS_KEY[myorganization-development]aws_access_key_id=<POPULATED_BY_AWS-MFA>aws_secret_access_key=<POPULATED_BY_AWS-MFA>aws_security_token=<POPULATED_BY_AWS-MFA>[myorganization-staging]aws_access_key_id=<POPULATED_BY_AWS-MFA>aws_secret_access_key=<POPULATED_BY_AWS-MFA>aws_security_token=<POPULATED_BY_AWS-MFA>[myorganization-production]aws_access_key_id=<POPULATED_BY_AWS-MFA>aws_secret_access_key=<POPULATED_BY_AWS-MFA>aws_security_token=<POPULATED_BY_AWS-MFA>Usage--device arn:aws:iam::123456788990:mfa/dudeman
                        The MFA Device ARN. This value can also be provided
                        via the environment variable 'MFA_DEVICE' or the
                        ~/.aws/credentials variable 'aws_mfa_device'.
--duration DURATION     The duration, in seconds, that the temporary
                        credentials should remain valid. Minimum value: 900
                        (15 minutes). Maximum: 129600 (36 hours). Defaults to
                        43200 (12 hours), or 3600 (one hour) when using
                        '--assume-role'. This value can also be provided via
                        the environment variable 'MFA_STS_DURATION'.
--profile PROFILE       If using profiles, specify the name here. The default
                        profile name is 'default'. The value can also be
                        provided via the environment variable 'AWS_PROFILE'.
--long-term-suffix LONG_TERM_SUFFIX
                        To identify the long term credential section by
                        [<profile_name>-LONG_TERM_SUFFIX]. Use 'none' to
                        identify the long term credential section by
                        [<profile_name>]. Omit to identify the long term 
                        credential section by [<profile_name>-long-term].
--short-term-suffix SHORT_TERM_SUFFIX
                        To identify the short term credential section by
                        [<profile_name>-SHORT_TERM_SUFFIX]. Omit or use 'none'
                        to identify the short term credential section by
                        [<profile_name>].
--assume-role arn:aws:iam::123456788990:role/RoleName
                        The ARN of the AWS IAM Role you would like to assume,
                        if specified. This value can also be provided via the
                        environment variable 'MFA_ASSUME_ROLE'
--role-session-name ROLE_SESSION_NAME
                        Friendly session name required when using --assume-
                        role. By default, this is your local username.Argument precedence: Command line arguments take precedence over environment variables.Usage ExampleRunaws-mfabeforerunning any of your scripts that use any AWS SDK.Using command line arguments:$>aws-mfa--duration1800--devicearn:aws:iam::123456788990:mfa/dudeman
INFO-Usingprofile:default
INFO-Yourcredentialshaveexpired,renewing.
EnterAWSMFAcodefordevice[arn:aws:iam::123456788990:mfa/dudeman](renewingfor1800seconds):123456
INFO-Success!Yourcredentialswillexpirein1800secondsat:2015-12-2123:07:09+00:00Using environment variables:exportMFA_DEVICE=arn:aws:iam::123456788990:mfa/dudeman
$>aws-mfa--duration1800INFO-Usingprofile:default
INFO-Yourcredentialshaveexpired,renewing.
EnterAWSMFAcodefordevice[arn:aws:iam::123456788990:mfa/dudeman](renewingfor1800seconds):123456
INFO-Success!Yourcredentialswillexpirein1800secondsat:2015-12-2123:07:09+00:00exportMFA_DEVICE=arn:aws:iam::123456788990:mfa/dudemanexportMFA_STS_DURATION=1800$>aws-mfa
INFO-Usingprofile:default
INFO-Yourcredentialshaveexpired,renewing.
EnterAWSMFAcodefordevice[arn:aws:iam::123456788990:mfa/dudeman](renewingfor1800seconds):123456
INFO-Success!Yourcredentialswillexpirein1800secondsat:2015-12-2123:07:09+00:00Output of runningaws-mfawhile credentials are still valid:$>aws-mfa
INFO-Usingprofile:default
INFO-Yourcredentialsarestillvalidfor1541.791134secondstheywillexpireat2015-12-2123:07:09Using a profile: (profiles allow you to reference different sets of credentials, perhaps for different users or different regions)$>aws-mfa--duration1800--devicearn:aws:iam::123456788990:mfa/dudeman--profiledevelopment
INFO-Usingprofile:development
EnterAWSMFAcodefordevice[arn:aws:iam::123456788990:mfa/dudeman](renewingfor1800seconds):666666
INFO-Success!Yourcredentialswillexpirein1800secondsat:2015-12-2123:09:04+00:00Using a profile that is set via the environment variableAWS_PROFILE:$>exportAWS_PROFILE=development
$>aws-mfa--duration1800--devicearn:aws:iam::123456788990:mfa/dudeman
INFO-Usingprofile:development
EnterAWSMFAcodefordevice[arn:aws:iam::123456788990:mfa/dudeman](renewingfor1800seconds):666666
INFO-Success!Yourcredentialswillexpirein1800secondsat:2015-12-2123:09:04+00:00Assuming a role:$>aws-mfa--duration1800--devicearn:aws:iam::123456788990:mfa/dudeman--assume-rolearn:aws:iam::123456788990:role/some-role--role-session-namesome-role-session
INFO-Validatingcredentialsforprofile:defaultwithassumedrolearn:aws:iam::123456788990:role/some-role
INFO-Obtainingcredentialsforanewroleorprofile.
EnterAWSMFAcodefordevice[arn:aws:iam::123456788990:mfa/dudeman](renewingfor1800seconds):123456
INFO-Success!Yourcredentialswillexpirein1800secondsat:2016-10-2418:58:17+00:00Assuming a role: Assume a role specified in yourlong-termconfiguration[default-long-term]aws_access_key_id=YOUR_LONGTERM_KEY_IDaws_secret_access_key=YOUR_LONGTERM_ACCESS_KEYassume_role=arn:aws:iam::123456788990:role/some-role$>aws-mfa--duration1800--devicearn:aws:iam::123456788990:mfa/dudeman--role-session-namesome-role-sessionAssuming a role using a profile:$>aws-mfa--duration1800--devicearn:aws:iam::123456788990:mfa/dudeman--profiledevelopment--assume-rolearn:aws:iam::123456788990:role/some-role--role-session-namesome-role-session
INFO-Validatingcredentialsforprofile:developmentwithassumedrolearn:aws:iam::123456788990:role/some-role
INFO-Obtainingcredentialsforanewroleorprofile.
EnterAWSMFAcodefordevice[arn:aws:iam::123456788990:mfa/dudeman](renewingfor1800seconds):123456
INFO-Success!Yourcredentialswillexpirein1800secondsat:2016-10-2418:58:17+00:00Assuming a role in multiple accounts and be able to work with both accounts simultaneously (i.e. production an staging):$>aws-mfa—profilemyorganization--assume-rolearn:aws:iam::222222222222:role/Administrator--short-term-suffixproduction--long-term-suffixnone--role-session-nameproduction
INFO-Validatingcredentialsforprofile:myorganization-productionwithassumedrolearn:aws:iam::222222222222:role/Administrator
INFO-Yourcredentialshaveexpired,renewing.
EnterAWSMFAcodefordevice[arn:aws:iam::111111111111:mfa/me](renewingfor3600seconds):123456
INFO-Success!Yourcredentialswillexpirein3600secondsat:2017-07-1007:16:43+00:00

$>aws-mfa—profilemyorganization--assume-rolearn:aws:iam::333333333333:role/Administrator--short-term-suffixstaging--long-term-suffixnone--role-session-namestagingINFO-Validatingcredentialsforprofile:myorganization-stagingwithassumedrolearn:aws:iam::333333333333:role/Administrator
INFO-Yourcredentialshaveexpired,renewing.
EnterAWSMFAcodefordevice[arn:aws:iam::111111111111:mfa/me](renewingfor3600seconds):123456
INFO-Success!Yourcredentialswillexpirein3600secondsat:2017-07-1007:16:44+00:00

$>awss3list-objects—bucketmy-production-bucket—profilemyorganization-production

$>awss3list-objects—bucketmy-staging-bucket—profilemyorganization-staging