{"id":20657723,"url":"https://github.com/boltops-tools/aws-mfa-secure","last_synced_at":"2025-04-19T13:18:11.543Z","repository":{"id":38620919,"uuid":"220595547","full_name":"boltops-tools/aws-mfa-secure","owner":"boltops-tools","description":"AWS MFA Secure Session for CLI and SDK","archived":false,"fork":false,"pushed_at":"2024-09-24T16:51:00.000Z","size":75,"stargazers_count":23,"open_issues_count":3,"forks_count":5,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-11-14T00:13:10.224Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/boltops-tools.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-11-09T05:21:51.000Z","updated_at":"2024-09-24T16:51:03.000Z","dependencies_parsed_at":"2022-09-13T11:00:48.267Z","dependency_job_id":null,"html_url":"https://github.com/boltops-tools/aws-mfa-secure","commit_stats":null,"previous_names":["tongueroo/aws-mfa-secure"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boltops-tools%2Faws-mfa-secure","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boltops-tools%2Faws-mfa-secure/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boltops-tools%2Faws-mfa-secure/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/boltops-tools%2Faws-mfa-secure/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/boltops-tools","download_url":"https://codeload.github.com/boltops-tools/aws-mfa-secure/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224954277,"owners_count":17397841,"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":[],"created_at":"2024-11-16T18:22:36.948Z","updated_at":"2024-11-16T18:22:37.646Z","avatar_url":"https://github.com/boltops-tools.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS MFA Secure\n\n[![Watch the video](https://img.boltops.com/boltopspro/youtube/aws-mfa.png)](https://www.youtube.com/watch?v=cYqKeMUS9pc)\n\n[![Gem Version](https://badge.fury.io/rb/aws-mfa-secure.png)](http://badge.fury.io/rb/aws-mfa-secure)\n\n[![BoltOps Badge](https://img.boltops.com/boltops/badges/boltops-badge.png)](https://www.boltops.com)\n\nSurprisingly, the [aws cli](https://docs.aws.amazon.com/cli/latest/reference/) does not yet support MFA for normal IAM users. See: [boto/botocore/pull/1399](https://github.com/boto/botocore/pull/1399)  The aws-mfa-secure tool decorates the AWS CLI or API to handle MFA authentication.  The MFA prompt only activates if `mfa_serial` is configured.\n\nAn advantage of the aws-mfa-secure is that it caches the temporary credentials `~/.aws/aws-mfa-secure-sessions` and reuses them until they expire. The expiration is 8 hours by default. This means that when you open a new terminal tab, you won’t have to re-enter the MFA code.\n\n## Installation\n\n    gem install aws-mfa-secure\n\nPrerequisite: The [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/) is required. You can install the AWS CLI via pip.\n\n    pip install awscli --upgrade --user\n\n## Usage\n\n**Summary**:\n\n1. Configure `~/.aws/credentials` with `mfa_serial`\n2. Set up bash alias\n3. Use aws cli like you normally would\n\n### Configure ~/.aws/credentials with mfa_serial\n\nSet up `mfa_serial` in credentials file for the profile section that requires it. Example:\n\n~/.aws/credentials:\n\n    [mfa]\n    aws_access_key_id = BKCAXZ6ODJLQ1EXAMPLE\n    aws_secret_access_key = ABCDl4hXikfOHTvNqFAnb2Ea62bUuu/eUEXAMPLE\n    mfa_serial = arn:aws:iam::112233445566:mfa/MFAUser\n\nNote: AWS already supports `mfa_serial` for assumed roles: [AWS Configuration and Credential File Settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).  The aws-mfa-secure tool does not decorate for assumed roles and lets the AWS CLI or SDK handle it.  The aws-mfa-secure tool adds support for standard IAM users, which is not currently supported. See: [boto/botocore/pull/1399](https://github.com/boto/botocore/pull/1399)\n\n### Set up bash alias\n\n    alias aws=\"aws-mfa-secure session\"\n\nThe alias allows us to intercept the normal aws cli command and decorate it. The `aws-mfa-secure session` only activates if `mfa_serial` is configured in your `~/.aws/credentials` file. Otherwise, it will pass the command through to the normal aws cli.  You may want to add the alias to your `~/.bash_profile` do you don't have to alias it every time you open a new terminal.\n\nAutocompletion still works with the alias.\n\n### Use aws cli like usual\n\nCall `aws` command like you usually would:\n\n    aws s3 ls\n\n### Example with Output\n\n    $ export AWS_PROFILE=mfa\n    $ aws s3 ls\n    Please provide your MFA code: 751888\n    2019-09-21 15:53:34 my-example-test-bucket\n    $ aws s3 ls\n    2019-09-21 15:53:34 my-example-test-bucket\n    $\n\nExpiration: You get prompted for the MFA token once, and the MFA secure session lasts for 12 hours. You can override the default expiration time with `AWS_MFA_TTL`. For example, `AWS_MFA_TTL=3600` means the session expires in 1 hour instead.\n\n## Calling Directly\n\nYou can also call `aws-mfa-secure session` directly.\n\n    aws-mfa-secure session --version\n    aws-mfa-secure session s3 ls\n\nThe arguments of `aws-mfa-secure session` are delegated to the `aws` command.  So:\n\n    aws-mfa-secure session s3 ls\n\nIs the same as:\n\n    aws s3 ls\n\nExcept `aws-mfa-secure session` will use the temporary session environment `AWS_*` variables values.\n\n## Exports\n\nYou can also generate an exports script. The exports technique is useful for tools that do not yet support MFA.  Using `AWS_*` env variables for credentials should allow those tools to work. Though, it may depend on the tool as they sometimes hardcode a credentials configuration.  Example:\n\n    $ aws-mfa-secure exports\n    Please provide your MFA code: 147280\n    export AWS_ACCESS_KEY_ID=ASIAXZ6ODJLBCEXAMPLE\n    export AWS_SECRET_ACCESS_KEY=HgYHvNxacSsFSwls1FO9RoF5+tvYCFIABEXAMPLE\n    export AWS_SESSION_TOKEN=IQoJb3JpZ2luX2VjEJ3//////////wEaCXVzLWVhc3QtMSJGMEQCIGnuGzUr8aszNWMFlFXQvFVhIA6aGdx3DskqY1JaIZWVAiANfE3xA79vIMVTqLnds4F2LpDy/qUeNRr7e9g9VQoS9SqyAQi2//////////8BEAEaDDUzNjc2NjI3MDE3NyIMgDgauwgJ4FIOMRV+KoYBRKR/MnKFB9/Q0Isc6D8gpG404xGJWqStNfGS0sHNsB5vVP/ccaAj4MG54p0Pl+V0LuIMXy345ua/bxxQFDWqhG0ORsXFEOo3iD1IQ+YA/yougAUl/0hbyvK3Jnf3NEHDejdL95iFCluJhoR0zFlDv7GwwBSXLUxS9K96/vgA0MmgK9a7kaAwoYiZ7gU63wHVDNYa1myqIP16Mi6KZ2zm9inMofixNN1ea3JMyRW+chWW8kdjjW4R3MFecpwoIayE7g3QLanmjE3jzrlxjIJWnl8tiipV+jassiSdlxLL2j1IIFH2pNEqrn4hkHG5t7OG+qZCTl8AnQ4W5wusmBoSIavr5w0dOdyx2mdsBMFtO82ZXvHSryY1gbIM9JyUd7dJ9h/mkfGL2p0n0R/lya8s9j8P8/8if+2uQcF+/BGDxojJ67kYXgstgfLjM5j8pZgyYj6YUFyTpyiOkllbPk/AjyxJY1svxW25wbNO+c13\n    $\n\nYou can eval it to set the environment variables in one go. Note, the MFA code prompt is written to standard error so it won't affect the eval.\n\n    $ eval `aws-mfa-secure exports`\n\nIf you're using the `aws-mfa-secure exports` command, the `aws-mfa-secure unsets` command is useful to unset the `AWS_*` env variables quickly.  For more info: `aws-mfa-secure unsets -h`.\n\n## Ruby AWS SDK Extension\n\nYou can also use `aws-mfa-secure` to add MFA support to Ruby libraries. Do so by requiring the `aws_mfa_secure/ext/aws`.\n\n```ruby\nrequire \"aws_mfa_secure/ext/aws\" # add MFA support\n```\n\nThis patches the aws-sdk-ruby library and adds MFA support.\n\n## Setting MFA Info with Env Variables\n\nYou can also set the MFA info with env variables. They take the highest precedence and override what's in `~/.aws/credentials`. Example:\n\n    AWS_MFA_TOKEN=112233 AWS_MFA_SERIAL=arn:aws:iam::112233445566:mfa/MFAUser aws s3 ls\n\n## How It Works\n\nDocs: [How It Works](docs/how-it-works.md)\n\n## Linux Support\n\nThis tool only supports Linux. For Windows, you'll have to set the `AWS_*` env variables manually. Refer to these resources:\n\n* [Switching to an IAM Role (Tools for Windows PowerShell)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-twp.html)\n* [How do I use an MFA token to authenticate access to my AWS resources through the AWS CLI?](https://aws.amazon.com/premiumsupport/knowledge-center/authenticate-mfa-cli/)\n\n## Related\n\nYou may also be interested in [tongueroo/aws-rotate](https://github.com/tongueroo/aws-rotate). It's an easy way to rotate all your AWS keys in your `~/.aws/credentials`.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am \"Add some feature\"`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboltops-tools%2Faws-mfa-secure","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fboltops-tools%2Faws-mfa-secure","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fboltops-tools%2Faws-mfa-secure/lists"}