{"id":23500420,"url":"https://github.com/eegli/mfaws","last_synced_at":"2025-04-15T18:42:24.035Z","repository":{"id":151188523,"uuid":"621743531","full_name":"eegli/mfaws","owner":"eegli","description":"A cross-platform CLI tool to manage AWS credentials for MFA-enabled accounts","archived":false,"fork":false,"pushed_at":"2025-01-21T07:26:27.000Z","size":164,"stargazers_count":6,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T23:44:07.643Z","etag":null,"topics":["2fa","aws","credentials","mfa","rust","sts"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/mfaws","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eegli.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-03-31T09:40:05.000Z","updated_at":"2025-01-21T07:26:03.000Z","dependencies_parsed_at":null,"dependency_job_id":"57c12ed1-1541-48cf-a56a-4d497704730b","html_url":"https://github.com/eegli/mfaws","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eegli%2Fmfaws","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eegli%2Fmfaws/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eegli%2Fmfaws/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eegli%2Fmfaws/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eegli","download_url":"https://codeload.github.com/eegli/mfaws/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249131146,"owners_count":21217682,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2fa","aws","credentials","mfa","rust","sts"],"created_at":"2024-12-25T06:44:15.503Z","updated_at":"2025-04-15T18:42:24.017Z","avatar_url":"https://github.com/eegli.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mfaws\n\nA cross-platform CLI tool to easily manage AWS credentials for MFA-enabled accounts. **mfaws** talks to the [AWS Security Token Service API](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) and allows you to obtain temporary credentials using your AWS access key, AWS secret key and MFA device.\n\nSupported STS operations:\n\n- AssumeRole\n- GetSessionToken\n\n**mfaws** is heavily inspired by [`aws-mfa`](https://github.com/broamski/aws-mfa), with a few key differences:\n\n- Assume multiple short-term profiles for a single long-term profile\n- A single native binary - no dependency on Python\n- Pass the one-time password (OTP) as a flag argument\n- Option to set the [STS service endpoint](https://docs.aws.amazon.com/general/latest/gr/sts.html#sts_region)\n- Utility commands to manage short-term profiles\n\nIf you're migrating and curious, read the section about the differences: [Migrating from `aws-mfa`: What's different?](#migrating-from-aws-mfa-whats-different)\n\n## Installation\n\n**mfaws** is available for Windows, MacOs and Linux.\n\n- Via cargo:\n\n```shell\ncargo install mfaws\n```\n\n- From GitHub:\n\n1. Download the latest binary from the [release page](https://github.com/eegli/mfaws/releases/latest)\n2. Extract it\n3. Add it to your `PATH`\n\n## Credentials File\n\nLet'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. Short-term profiles are identified by the `-short-term` suffix (or a custom one that you provide). Short-term profiles are generated automatically and should not be fiddled with manually.\n\n```ini\n[dev]\naws_access_key_id=AKMB6EHIO4AB9FRYI37\naws_secret_access_key=qAnFonnuEUqp\n```\n\n- You can set `aws_mfa_device=[MFA DEVICE ARN]` in your AWS credentials profile so you don't have to pass it as a flag every time\n- If you don't specify a profile name with `--profile`, the app looks for the profile named `default`\n\n## Basic Usage\n\n- Get a **temporary session token** for profile `dev`:\n\n```shell\nmfaws session-token \\\n    --profile dev \\\n    --device arn:aws:iam::3687901:mfa/my-mfa-device\n```\n\n**mfaws** automatically generates and adds the following short-term profile to your AWS credentials file:\n\n```ini\n[dev]\naws_access_key_id=AKMB6EHIO4AB9FRYI37\naws_secret_access_key=qAnFonnuEUqp\n\n[dev-short-term]\nexpiration=2023-04-05T21:57:52Z\naws_access_key_id=ASIAVMB6EHIOYTGUOE7T\naws_secret_access_key=E6HGxHXHb2hqP3az+UMThIjWGVsdKH3pG1h67FxR\naws_session_token=IQoJb3JpZ2luX2VjECoaCXVzLWVhc3QtMSJHMEUCIDSFI50`\n\n```\n\n- **Assume a role** for profile `dev`, pass the otp as an argument and use region `eu-central-2`:\n\n```shell\nmfaws assume-role \\\n    --profile dev \\\n    --role-arn arn:aws:iam::6823sdf5:role/admin \\\n    --device arn:aws:iam::3687901:mfa/my-mfa-device \\\n    --otp 123456 \\\n    --sts-region eu-central-2\n```\n\nNow, your AWS config file looks like this:\n\n```ini\n[dev]\naws_access_key_id=AKMB6EHIO4AB9FRYI37\naws_secret_access_key=qAnFonnuEUqp\n\n[dev_6823sdf5-role-admin-mfa-user_short-term]\nassumed_role_arn=arn:aws:iam::6823sdf5:role/admin\nassumed_role_id=AROAZ5XVG55QR3R2:mfa-user\nexpiration=2023-04-05T11:02:10Z\naws_access_key_id=ASINQT6HE6ZCS\naws_secret_access_key=iqVoWOI8+l6WVBn8pdCc/JxJ6\naws_session_token=IQoJb3JpZ2luXS4VhObxKg6p79Pm38C4ahGqcGKw==\n```\n\nWhenever you run an operation, **mfaws** checks your existing short-term profiles to see if there is still a valid (i.e., not yet expired) profile around. If that is the case, the operation is gracefully aborted and you'll be notified. You can also force new credentials by passing the `--force` flag.\n\n## Shell Aliases\n\nI recommended creating bash aliases for any of these operations and then set the [`AWS_PROFILE` environment variable](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html#cli-configure-files-using-profiles) to the name of the genreated profile.\n\nE.g., for bash:\n\n```shell\nalias mfa-admin=\"mfaws assume-role --profile dev --role-arn arn:aws:iam::6823sdf5:role/admin \u0026\u0026 export AWS_PROFILE=default_6823sdf5-role-admin-mfa-user_short-term\"\n```\n\nYou 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.\n\n## Commands\n\nIn your terminal, run `mfaws help` to see all (sub)commands and their usage:\n\n```\nA CLI tool to manage AWS credentials for MFA-enabled accounts\n\nUsage: mfaws [OPTIONS] \u003cCOMMAND\u003e\n\nCommands:\n  assume-role    Temporary credentials for an assumed AWS IAM Role\n  session-token  Temporary credentials for an AWS IAM user\n  clean          Remove short-time profiles from your credentials file\n  list           List profiles in your credentials file\n  help           Print this message or the help of the given subcommand(s)\n\nOptions:\n      --credentials-path \u003cCREDENTIALS_PATH\u003e\n          Location of the AWS credentials file. Can be a relative path from your home directory or an absolute path to the file [env: AWS_SHARED_CREDENTIALS_FILE=] [default: .aws/credentials]\n  -h, --help\n          Print help\n  -V, --version\n          Print version\n```\n\n**mfaws** allows you to customize many things, including the duration of the temporary credentials, the short-term suffix that is used to generate short-term profiles or the path to the credentials file. Many values can also be read from the corresponding environment variables.\n\n### `assume-role`\n\n```shell\nmfaws assume-role --help\n```\n\n```\nTemporary credentials for an assumed AWS IAM Role\n\nUsage: mfaws assume-role [OPTIONS] --role-arn \u003cROLE_ARN\u003e\n\nOptions:\n      --role-arn \u003cROLE_ARN\u003e\n          The ARN of the AWS IAM Role you want to assume [env: AWS_ROLE_ARN=]\n      --role-session-name \u003cROLE_NAME\u003e\n          Custom friendly session name when assuming a role [env: AWS_ROLE_SESSION_NAME=] [default: mfa-user]\n      --profile \u003cPROFILE_NAME\u003e\n          The AWS credentials profile to use [env: AWS_PROFILE=] [default: default]\n      --device \u003cMFA_DEVICE\u003e\n          The MFA Device ARN [env: MFA_DEVICE=]\n      --credentials-path \u003cCREDENTIALS_PATH\u003e\n          Location of the AWS credentials file. Can be a relative path from your home directory or an absolute path to the file [env: AWS_SHARED_CREDENTIALS_FILE=] [default: .aws/credentials]\n      --otp \u003cOTP\u003e\n          The one-time password from your MFA device\n      --duration \u003cDURATION\u003e\n          The duration, in seconds, for which the temporary credentials should remain valid [env: MFA_DURATION=]\n      --short-term-suffix \u003cSHORT_TERM_SUFFIX\u003e\n          To identify the auto-generated short-term credential profile [default: short-term]\n      --force\n          Force the creation of a new short-term profile even if one already exists\n      --sts-region \u003cSTS_REGION\u003e\n          The STS region to use for the AWS client [default: us-east-1]\n  -h, --help\n          Print help\n```\n\n### `session-token`\n\n```shell\nmfaws session-token --help\n```\n\n```\nTemporary credentials for an AWS IAM user\n\nUsage: mfaws session-token [OPTIONS]\n\nOptions:\n      --profile \u003cPROFILE_NAME\u003e\n          The AWS credentials profile to use [env: AWS_PROFILE=] [default: default]\n      --device \u003cMFA_DEVICE\u003e\n          The MFA Device ARN [env: MFA_DEVICE=]\n      --otp \u003cOTP\u003e\n          The one-time password from your MFA device\n      --duration \u003cDURATION\u003e\n          The duration, in seconds, for which the temporary credentials should remain valid [env: MFA_DURATION=]\n      --credentials-path \u003cCREDENTIALS_PATH\u003e\n          Location of the AWS credentials file. Can be a relative path from your home directory or an absolute path to the file [env: AWS_SHARED_CREDENTIALS_FILE=] [default: .aws/credentials]\n      --short-term-suffix \u003cSHORT_TERM_SUFFIX\u003e\n          To identify the auto-generated short-term credential profile [default: short-term]\n      --force\n          Force the creation of a new short-term profile even if one already exists\n      --sts-region \u003cSTS_REGION\u003e\n          The STS region to use for the AWS client [default: us-east-1]\n  -h, --help\n          Print help\n```\n\n### `clean`\n\n```shell\nmfaws clean --help\n```\n\n```\nRemove short-time profiles from your credentials file\n\nUsage: mfaws clean [OPTIONS]\n\nOptions:\n      --short-term-suffix \u003cSHORT_TERM_SUFFIX\u003e\n          To identify the short-term credential profiles [default: short-term]\n      --credentials-path \u003cCREDENTIALS_PATH\u003e\n          Location of the AWS credentials file. Can be a relative path from your home directory or an absolute path to the file [env: AWS_SHARED_CREDENTIALS_FILE=] [default: .aws/credentials]\n  -h, --help\n          Print help\n```\n\n### `list`\n\n```shell\nmfaws list --help\n```\n\n```\nList profiles in your credentials file\n\nUsage: mfaws list [OPTIONS]\n\nOptions:\n      --credentials-path \u003cCREDENTIALS_PATH\u003e\n          Location of the AWS credentials file. Can be a relative path from your home directory or an absolute path to the file [env: AWS_SHARED_CREDENTIALS_FILE=] [default: .aws/credentials]\n  -h, --help\n          Print help\n```\n\n## STS Regions\n\nIn most cases, you will not have to speficy the STS endpoint to retrieve temporary credentials. The default region is `us-east-1`. If you need to use a different region, you can set the `--sts-region` flag with a [regional endpoint identifier](https://docs.aws.amazon.com/general/latest/gr/sts.html#sts_region) (_not_ URL). Note that the region configured in `./aws/config` is not used.\n\n## Migrating from `aws-mfa`: What's different?\n\n1. By default, all profiles are considered long-term profiles unless they end with the short term suffix set by `--short-term-suffix [SUFFIX]`. There is no such thing as an _explicit_ long-term suffix (hence, also no `--long-term-suffix` flag)\n2. Unlike `aws-mfa`, where actions (AssumeRole/GetSessionToken) are implicitly given by the presence of the `--assume-role` flag, **mfaws** has dedicated sub-commands for each operation\n3. `--assume-role` is `--role-arn`\n4. `--role-session-name [NAME]` does not use the [login name of your user](https://docs.python.org/3/library/getpass.html) by default but the static string `mfa-user`\n5. Some environment variables have different names\n\n## Contributing\n\nGeneral feedback, bugfixes and feature ideas are very welcome! Please open an issue first.\n\n## Acknowledgements\n\n- [broamski](https://github.com/broamski) for the MIT license of [`aws-mfa`](https://github.com/broamski/aws-mfa). The general idea for this tool and much of the help command descriptions were stolen from his work.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feegli%2Fmfaws","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feegli%2Fmfaws","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feegli%2Fmfaws/lists"}