{"id":16895950,"url":"https://github.com/stevenacoffman/keyfob","last_synced_at":"2025-04-11T13:38:31.959Z","repository":{"id":57553829,"uuid":"193271735","full_name":"StevenACoffman/keyfob","owner":"StevenACoffman","description":"Two-factor authentication on the command line using the OS keychain","archived":false,"fork":false,"pushed_at":"2019-08-26T16:34:21.000Z","size":211,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-15T17:36:44.730Z","etag":null,"topics":["aws","aws-vault","golang","two-factor-authentication"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/StevenACoffman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-22T19:24:55.000Z","updated_at":"2024-03-30T09:25:06.000Z","dependencies_parsed_at":"2022-09-26T18:51:49.119Z","dependency_job_id":null,"html_url":"https://github.com/StevenACoffman/keyfob","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevenACoffman%2Fkeyfob","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevenACoffman%2Fkeyfob/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevenACoffman%2Fkeyfob/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/StevenACoffman%2Fkeyfob/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/StevenACoffman","download_url":"https://codeload.github.com/StevenACoffman/keyfob/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239658348,"owners_count":19675934,"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":["aws","aws-vault","golang","two-factor-authentication"],"created_at":"2024-10-13T17:27:09.585Z","updated_at":"2025-02-19T12:32:27.356Z","avatar_url":"https://github.com/StevenACoffman.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![GoDoc](https://godoc.org/github.com/StevenACoffman/keyfob?status.svg)](https://godoc.org/github.com/StevenACoffman/keyfob)\n[![GoReportcard](https://goreportcard.com/badge/github.com/StevenACoffman/keyfob?status.svg)](https://goreportcard.com/report/github.com/StevenACoffman/keyfob)\n# Keyfob\nkeyfob is a two-factor authentication agent suitable for AWS and Github. Works pretty much the same as Google Authenticator or Authy, but uses your laptop's keychain.\n\n## Installation\n\nIf you use homebrew:\n\n```\nbrew tap StevenACoffman/keyfob\nbrew install keyfob\n```\nAny subsequent releases should get picked up automatically with `brew upgrade`\n\nIf don't use homewbrew, and you're on a mac, you can just do this:\n\n    wget -O - https://raw.githubusercontent.com/StevenACoffman/keyfob/master/install.sh | bash\n\n\nThis will download the github 0.3.0 binary release for mac, and move any of your MFA secrets from `2fa` over to your keychain.\n\n## Usage\n\n    keyfob add [name] [key]\n    keyfob otp [name]\n    keyfob list\n    keyfob qr [name]\n    keyfob vault [name] [profile]\n    keyfob help\n\n+ `keyfob add name` adds a new key to the keyfob keychain with the given name. It\nprints a prompt to standard error and reads a two-factor key from standard\ninput. Two-factor keys are short case-insensitive strings of letters A-Z and\ndigits 2-7.\n\n  The new key generates time-based (TOTP) authentication codes.\n\n+ `keyfob otp [name]` prints a One Time Password (aka two-factor authentication) code from the key with the\ngiven name. If `--clip` is specified, `keyfob` also copies to the code to the system\nclipboard.\n\n+ `keyfob list` prints the names of all the added keys, if any.\n\n+ `keyfob qr [name]` prints a QR Code for the key with the given name. This can be useful for backing up QR Codes to Google Authenticator or Authy or whatever.\n\n+ `keyfob vault [name] [profile]` acts as a will act as an [AWS credential helper](https://docs.aws.amazon.com/cli/latest/topic/config-vars.html#sourcing-credentials-from-external-processes) using [AWS Vault](https://github.com/99designs/aws-vault/) and a One Time Password.\n\nThe Time-based One Time Password (TOTP) authentication codes are derived from a hash of the\nkey and the current time, so it is important that the system clock have at\nleast one-minute accuracy.\n\nThe keychain is stored unencrypted in the text file `$HOME/.keyfob`.\n\n## Example\n\nDuring GitHub 2FA setup, at the “Scan this barcode with your app” step,\nclick the “enter this text code instead” link. A window pops up showing\n“your two-factor secret,” a short string of letters and digits.\n\nAdd it to keyfob under the name github and append the secret:\n\n    $ keyfob add github nzxxiidbebvwk6jb\n\nThen whenever GitHub prompts for a 2FA code, run keyfob to obtain one:\n\n    $ keyfob otp github\n    268346\n\n## Derivation (Credit where Credit is due)\n\nThis is just a little toy cobbled together from [2fa](https://github.com/rsc/2fa/), [cobra](https://github.com/spf13/cobra), and [go-keyring](https://github.com/zalando/go-keyring) and using [goreleaser](https://github.com/goreleaser/goreleaser).\nThe directions I had below this were confusing, so I stole some of the directions from [this article on how to do a similar thing with a yubikey](https://hackernoon.com/use-a-yubikey-as-a-mfa-device-to-replace-google-authenticator-b4f4c0215f2).\n\n## Really, does this make sense?\n\nAt least to me, it does. My laptop features encrypted storage, a stronger authentication mechanism, and I take good care of its physical integrity.\n\nMy phone also runs arbitrary apps, is constantly connected to the Internet, gets forgotten on tables.\n\nThanks to the convenience of a command line utility, I'm more likely to enable MFA in more places.\n\nClearly a win for security.\n\n## Dependencies\n\n#### OS X\n\nThe OS X implementation depends on the `/usr/bin/security` binary for\ninterfacing with the OS X keychain. It should be available by default.\n\n#### Linux\n\nThe Linux implementation depends on the [Secret Service][SecretService] dbus\ninterface, which is provided by [GNOME Keyring](https://wiki.gnome.org/Projects/GnomeKeyring).\n\nIt's expected that the default collection `login` exists in the keyring, because\nit's the default in most distros. If it doesn't exist, you can create it through the\nkeyring frontend program [Seahorse](https://wiki.gnome.org/Apps/Seahorse):\n\n * Open `seahorse`\n * Go to **File \u003e New \u003e Password Keyring**\n * Click **Continue**\n * When asked for a name, use: **login**\n \n \n## Usage with aws-vault\n\nThis assumes you have installed `keyfob` and `aws-vault` but need to set up your secrets. See [aws-vault](https://github.com/99designs/aws-vault) for instructions on setting that up.\n\n__*Note:*__ Your own organization __*might*__ have a different preferred `source_profile` name from `source` below, and your AWS account number is probably not `111111111111`.\n\n1. Skip to **[2](#2)** if you already added your AWS access key and secret access key to aws vault. Otherwise do this:\n```\n$ brew cask install aws-vault\n$ brew install go zbar awscli\n$ aws-vault add source --keychain login\n```\n\n2. \u003ca name=\"2\"\u003e\u003c/a\u003eGo to the AWS Web console to [make a new MFA token](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html#enable-virt-mfa-for-iam-user). \n\n3. After login, go to IAM \u003e Users and click in your user name. Then you need to click on the “Security credentials” tab. \n\u003cimg src=\"./images/aws_iam_users_security_credentials.png\" /\u003e\n\n4. To assign an MFA device, just click Manage. If you have an existing one, you must remove it. In the next screen, select “Virtual MFA device”.\n\u003cimg src=\"./images/manage_virtual_mfa_device.png\" /\u003e\n\n5. Here you can choose to show the QR code or to show the text of the MFA secret key. For our purposes, we want the secret key only.\n\u003cimg src=\"./images/get_mfa_secret_key.png\" /\u003e\n  \n6. Add your MFA secret (from above) to keyfob:\n```\nkeyfob add aws-source \u003cYOUR_BASE_32_KEY\u003e\n```\n\n7. Then run `keyfob otp aws-source` a few times, to get two different, but consecutive 6-digit codes and complete the set up.\n\u003cimg src=\"./images/mfa_setup_correctly.png\" /\u003e\n\n8. Add to your `.aws/config` file something like this:\n```\n[default]\ncredential_process = keyfob vault aws-source engineer\nregion = us-east-1\noutput = json\n \n[profile source]\nregion = us-east-1\nmfa_serial = arn:aws:iam::111111111111:mfa/scoffman\n \n[profile engineer]\nmfa_serial = arn:aws:iam::111111111111:mfa/scoffman\nregion = us-east-1\nrole_arn = arn:aws:iam::111111111111:role/put-power-role-here\nsource_profile = source\n```\n9. Run `aws-vault add source --keychain login` and provide your AWS secret access key and AWS access key when prompted.\n\nHere `default` profile depends on `engineer` profile which depends on `source` profile.\n  1. The `default` profile specifies a `credential_process`, which will tell `keyfob` to use the `engineer` profile when invoking `aws-vault`\n  2. The `engineer` profile specifies a `source_profile` which uses the `source` profile for credentials in `aws-vault`.\n  3. The `source` profile has credentials stored by `aws-vault` in the keychain.\n\n\u003ctable\u003e\u003ctr\u003e\u003ctd\u003e:bulb: \u003cb\u003eNOTE:\u003c/b\u003e Make sure you've edited and replaced the AWS account, userid, and power-role above.\u003c/td\u003e\u003c/tr\u003e\u003c/table\u003e\n\nIf your AWS user doesn't need to assume a privileged role, then omit the `engineer` profile and use `keyfob vault aws-source source` as the `credential_process`.\n\nYou also don't have to make the keyfob profile be the default, but some AWS SDKs (looking at you Java) may struggle otherwise.\n\nYou also may want to export something like these environment variables in your `.bash_profile` or `.bashrc` (or whatever zsh uses):\n```\nexport AWS_MY_USERNAME='scoffman'\nexport AWS_SDK_LOAD_CONFIG=true\nexport AWS_REGION=\"us-east-1\"\nexport AWS_DEFAULT_REGION=\"us-east-1\"\nexport AWS_DEFAULT_OUTPUT=\"json\"\nexport AWS_VAULT_KEYCHAIN_NAME='login'\nexport AWS_MFA_NAME='aws-source'\n# 3600s is max for chaining roles\nexport AWS_ASSUME_ROLE_TTL='3600s'\nexport AWS_SESSION_TTL='12h'\nexport AWS_FEDERATION_TOKEN_TTL='12h'\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevenacoffman%2Fkeyfob","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstevenacoffman%2Fkeyfob","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevenacoffman%2Fkeyfob/lists"}