Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/pbar1/mfaws
:lock: AWS multi-factor authentication for the CLI
https://github.com/pbar1/mfaws
2fa amazon-web-services aws aws-mfa aws-sts awsmfa mfa multi-factor-authentication sts two-factor-authentication
Last synced: 2 months ago
JSON representation
:lock: AWS multi-factor authentication for the CLI
- Host: GitHub
- URL: https://github.com/pbar1/mfaws
- Owner: pbar1
- License: mit
- Created: 2018-07-27T21:12:32.000Z (over 6 years ago)
- Default Branch: develop
- Last Pushed: 2024-11-07T08:19:33.000Z (3 months ago)
- Last Synced: 2024-11-07T08:20:13.785Z (3 months ago)
- Topics: 2fa, amazon-web-services, aws, aws-mfa, aws-sts, awsmfa, mfa, multi-factor-authentication, sts, two-factor-authentication
- Language: Go
- Homepage:
- Size: 7.37 MB
- Stars: 43
- Watchers: 3
- Forks: 3
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
:lock: mfaws :lock:
AWS multi-factor authentication manager
## Installation
[](https://repology.org/project/mfaws/versions)
| Package Manager | Install Command |
|-----------------------|------------------------------------------------------------------------------------------------|
| [Manual][p_man] | Download the binary for your system from the releases page |
| [Nix (flake)][p_nix] | `nix run github:pbar1/mfaws --` |
| [Docker][p_docker] | `docker pull ghcr.io/pbar1/mfaws:latest` |
| [Go][p_go] | `go install github.com/pbar1/mfaws@latest` |
| [Homebrew][p_tap] | `brew tap pbar1/tap`
`brew install pbar1/tap/mfaws` |
| [Scoop][p_scoop] | `scoop bucket add pbar1 https://github.com/pbar1/scoop-bucket`
`scoop install pbar1/mfaws` |
| [Chocolatey][p_choco] | `choco install mfaws` |
| [AUR][p_aur] | `yay -S mfaws-bin` |
## How to use
### CLI help
Expand to see mfaws --help
AWS Multi-Factor Authentication Manager
Usage:
mfaws [flags]
mfaws [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
help Help about any command
version Prints mfaws version information
Flags:
-a, --assume-role string ARN of IAM role to assume [MFA_ASSUME_ROLE]
-c, --credentials-file string Path to AWS credentials file (default "~/.aws/credentials") [AWS_SHARED_CREDENTIALS_FILE]
-d, --device string ARN of MFA device to use [MFA_DEVICE]
-l, --duration int Duration in seconds for credentials to remain valid (default assume-role ? 3600 : 43200) [MFA_STS_DURATION]
-e, --external-id string Unique ID used by third parties to assume a role in their customers' accounts [AWS_EXTERNAL_ID]
-f, --force Force credentials to refresh even if not expired
-h, --help help for mfaws
--long-term-suffix string Suffix appended to long-term profiles (default "-long-term")
-p, --profile string Name of profile to use in AWS credentials file (default "default") [AWS_PROFILE]
-s, --role-session-name string Session name when assuming a role
--short-term-suffix string Suffix appended to short-term profiles (default "")
-t, --token string MFA token to use for authentication
-v, --verbose Enable verbose output
Use "mfaws [command] --help" for more information about a command.
### Setup and usage
`mfaws` works by looking for AWS credentials and an MFA device ARN in profiles suffixed with `-long-term`. It uses those credentials as well as a TOTP code supplied by the user to make an `AssumeRole` call. The outcome of this is another set of short-lived credentials scoped to the role session. These short lived credentials are stored in a separate profile in the credentials file without the `-long-term` suffix.
For example, your `~/.aws/credentials` file should look similar to this. Here we are using the profile `default-long-term`:
```ini
[default-long-term]
aws_access_key_id = $YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = $YOUR_AWS_SECRET_ACCESS_KEY
aws_mfa_device = $YOUR_MFA_DEVICE_ARN
```
Then, simply run the following, and enter the MFA token when prompted:
```sh
$ mfaws
```
If that is sucessful, it will create a another profile in the credentials file called `default` that contains the session-scoped creds:
```diff
[default-long-term]
aws_access_key_id = $YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = $YOUR_AWS_SECRET_ACCESS_KEY
aws_mfa_device = $YOUR_MFA_DEVICE_ARN
+[default]
+aws_access_key_id = ...
+aws_secret_access_key = ...
+aws_session_token = ...
```
In this example we used `default` because it is what tools such as the AWS SDK and `aws` CLI load by default when no profile is specified. Using other profiles is also like so: `mfaws -p myprofile`, which will result in the following:
```diff
[myprofile-long-term]
aws_access_key_id = $YOUR_AWS_ACCESS_KEY_ID
aws_secret_access_key = $YOUR_AWS_SECRET_ACCESS_KEY
aws_mfa_device = $YOUR_MFA_DEVICE_ARN
+[myprofile]
+aws_access_key_id = ...
+aws_secret_access_key = ...
+aws_session_token = ...
```
## Examples
> [!NOTE]
> Make sure your hardware clock is correct, [especially if dual booting](https://wiki.archlinux.org/index.php/Time#UTC_in_Windows). If your time is out of sync, codes generated on your machine will be wrong and your MFA attempts will fail.
### Combine with [`oathtool`](https://www.nongnu.org/oath-toolkit/)
> [!CAUTION]
> While convenient, it's generally not advisable to save the MFA *secret key* to disk, since it does not expire.
You can use `oathtool` to get TOTP codes directly in the CLI without having to copy them from elsewhere. `mfaws` can receive a TOTP code piped from stdin:
```sh
oathtool --totp --base32 $YOUR_AWS_TOTP_KEY | mfaws
```
### Combine with [1Password CLI](https://developer.1password.com/docs/cli/)
You can get TOTP codes from MFA keys that you've saved in your 1Password account. This has the advantage of not leaking the secret to disk. In this example, we're requesting a TOTP code from an item called `AWS` in our 1Password account and piping it into `mfaws`:
```sh
op item get AWS --otp | mfaws
```
### Combine with [HashiCorp Vault](https://developer.hashicorp.com/vault/docs/secrets/totp) TOTP secrets engine
Similar to the above examples, you can request a TOTP code from HashiCorp Vault. In this example, we've enabled the TOTP secret engine and previously saved our MFA secret as an item called `my-aws-totp-secret`. Simply use the Vault CLI to read just the `code` field from that secret:
```
vault read -field=code totp/code/my-aws-totp-secret | mfaws
```
[p_man]: https://github.com/pbar1/mfaws/releases
[p_nix]: https://github.com/pbar1/mfaws/blob/develop/flake.nix
[p_docker]: https://github.com/pbar1/mfaws/pkgs/container/mfaws
[p_go]: https://pkg.go.dev/github.com/pbar1/mfaws
[p_tap]: https://github.com/pbar1/homebrew-tap/blob/main/mfaws.rb
[p_scoop]: https://github.com/pbar1/scoop-bucket/blob/master/bucket/mfaws.json
[p_choco]: https://community.chocolatey.org/packages/mfaws
[p_aur]: https://aur.archlinux.org/packages/mfaws-bin