mfaws

A CLI tool to easily manage AWS credentials for MFA-enabled accounts. mfaws talks to the AWS Security Token Service API and allows you to obtain temporary credentials using your AWS access key, AWS secret key and MFA device.

Supported STS operations:

mfaws is heavily inspired by aws-mfa, with two key differences:

If you're migrating and curious, read the section about the differences: Migrating from aws-mfa: What's different?

Installation

mfaws is available for Windows, MacOs and Linux.

Credentials File

Let's assume you have the following AWS credentials file in ~/.aws/credentials. It has a single long-term profile, dev, which can be used to generate short-term profiles.

ini [dev] aws_access_key_id=AKMB6EHIO4AB9FRYI37 aws_secret_access_key=qAnFonnuEUqp

Basic Usage

bash mfaws session-token --profile dev --device arn:aws:iam::3687901:mfa/my-mfa-device

mfaws automatically generates and adds the following profile to your AWS credentials file:

```ini [dev] awsaccesskeyid=AKMB6EHIO4AB9FRYI37 awssecretaccesskey=qAnFonnuEUqp

[dev-short-term] expiration=2023-04-05T21:57:52Z awsaccesskeyid=ASIAVMB6EHIOYTGUOE7T awssecretaccesskey=E6HGxHXHb2hqP3az+UMThIjWGVsdKH3pG1h67FxR awssessiontoken=IQoJb3JpZ2luX2VjECoaCXVzLWVhc3QtMSJHMEUCIDSFI50`

```

bash mfaws assume-role --profile dev --role-arn arn:aws:iam::6823sdf5:role/admin --device arn:aws:iam::3687901:mfa/my-mfa-device

Now, your AWS config file looks like this:

```ini [dev] awsaccesskeyid=AKMB6EHIO4AB9FRYI37 awssecretaccesskey=qAnFonnuEUqp

[dev6823sdf5-role-admin-mfa-usershort-term] assumedrolearn=arn:aws:iam::6823sdf5:role/admin assumedroleid=AROAZ5XVG55QR3R2:mfa-user expiration=2023-04-05T11:02:10Z awsaccesskeyid=ASINQT6HE6ZCS awssecretaccesskey=iqVoWOI8+l6WVBn8pdCc/JxJ6 awssessiontoken=IQoJb3JpZ2luXS4VhObxKg6p79Pm38C4ahGqcGKw== ```

Shell Aliases

I recommended creating bash aliases for any of these operations and then set the AWS_PROFILE environment variable to the name of the genreated profile.

E.g., for bash:

bash alias mfa-admin="mfaws assume-role --profile dev --role-arn arn:aws:iam::6823sdf5:role/admin && export AWS_PROFILE=default_6823sdf5-role-admin-mfa-user_short-term"

You might want to run it manually the first time to see what name is generated for your short-term profile. It's a combination of the assumed role and role name.

Full Usage

In your terminal: Run:

mfaws help

mfaws allows you to customize many things, including the duration of the temporary credentials or the short-term suffix that is used to generate short-term profiles. Many values can also be read from the corresponding environment variables.

```shell Usage: mfaws [OPTIONS]

Commands: assume-role

session-token

help Print this message or the help of the given subcommand(s)

Options: --profile The AWS credentials profile to use.

      [env: AWS_PROFILE=]
      [default: default]

  --device <MFA_DEVICE>
      The MFA Device ARN. This value can also be provided via the ~/.aws/credentials variable 'aws_mfa_device'.

      [env: MFA_DEVICE=]

  --duration <DURATION>
      The duration, in seconds, for which the temporary credentials should remain valid. Defaults to 43200 (12 hours) for session tokens and 3600 (one hour) when assuming a role.

      [env: MFA_STS_DURATION=]

  --short-term-suffix <SHORT_TERM_SUFFIX>
      To identify the auto-generated short term credential profile by [<profile_name>-SHORT_TERM_SUFFIX].

      [default: short-term]

-h, --help Print help (see a summary with '-h')

-V, --version Print version ```

Migrating from aws-mfa: What's different?

  1. By default, all profiles are considered long-term profiles unless they end with the short term suffix set by --short-term-suffix [SHUFFIX]. There is no such thing as an explicit long-term suffix (hence, also no --long-term-suffix flag)
  2. --role-session-name [NAME] does not use the login name of your user by default but the static string mfa-user

Contributing and Notes

Acknowledgements