[](https://pypi.python.org/pypi/awscli-plugin-yubikeytotp/) [](https://github.com/psf/black)
# Yubikey authentication for AWS CLI (and boto) made easy
This plugin enables aws-cli to directly talk to your [YubiKey](https://www.yubico.com/)
to acquire an OATH-TOTP code using the YubiKey's CCID application.
Currently, FIDO-U2F is unsupported on both, [botocore](https://github.com/aws/aws-cli/issues/3607)
and [aws-cli](https://github.com/aws/aws-cli/issues/3607).
Using aws-cli with roles and a regular OATH-TOTP token at least prompts you for
the TOTP code but this is quite cumbersome to use with a YubiKey.
## Installation
`awscli-plugin-yubikeytotp` can be installed from PyPI:
```
$ pip install awscli-plugin-yubikeytotp
```
It's also possible to install it just for your user in case you don't have
permission to install packages system-wide:
```
$ pip install --user awscli-plugin-yubikeytotp
```
### Configure AWS CLI
To enable the plugin, add this to your `~/.aws/config`:
```
[plugins]
yubikeytotp = awscli_plugin_yubikeytotp
```
Also make sure to have your MFA ARN configured for your profile:
```
[profile myprofile]
role_arn = arn:aws:iam::...
mfa_serial = arn:aws:iam::...
source_profile = default
```
## Usage
Just use the `aws` command with a custom role and the plugin will do the rest:
```
$ aws s3 ls --profile myprofile
Generating OATH code on YubiKey. You may have to touch your YubiKey to proceed...
Successfully created OATH code.
2013-07-11 17:08:50 mybucket
2013-07-24 14:55:44 mybucket2
```
---
**NOTE**
To AWS, the M in MFA [still stands for the number 2](https://forums.aws.amazon.com/thread.jspa?threadID=137055). Hence, if you want to log in to the AWS console with OATH-TOTP
enabled, you will have to use `ykman oath code` to generate a key and enter it
manually to log in, just like with Google Authenticator or Yubikey Authenticator
smartphone apps.
If you want to use U2F MFA authentication for login while still being able to
use your YubiKey for command line, you should create multiple IAM users. Use
one user with U2F MFA to log in to the AWS console and disable access keys.
Use the other use with Virtual MFA device and disable console login.
Only ever use one user in the console and the other on your command line.
---
## Tutorial
### Prerequisites
You obviously have to have a YubiKey. A Yubico Security Key (the blue ones)
are not supported as they lack the OATH application.
To setup your YubiKey, you also have to have [yubikey-manager](https://developers.yubico.com/yubikey-manager/) (or `ykman`) installed.
You can use it to verify that OATH is enabled for your YubiKey:
```
$ ykman info
Device type: YubiKey 5 NFC
Serial number: 00000000
Firmware version: 5.2.4
Form factor: Keychain (USB-A)
Enabled USB interfaces: OTP+FIDO+CCID
NFC interface is enabled.
Applications USB NFC
OTP Enabled Enabled
FIDO U2F Enabled Enabled
OpenPGP Enabled Enabled
PIV Enabled Enabled
OATH Enabled Enabled
FIDO2 Enabled Enabled
```
### Setup MFA in AWS
1. Log-in to your AWS account/user and navigate to your *My Security Credentials*
page.
2. Take not of your *AWS account ID* at the top.
2. Under *Multi-factor authentivation (MFA)*, click `Manage MFA device` and add
a *Virtual MFA device*.
3. Instead of showing the QR code, click on `Show secret key` and copy the key.
4. On a command line, run
```
$ ykman oath add -t arn:aws:iam::${ACCOUNT_ID}:mfa/${IAM_USERNAME} ${MFA_SECRET}
```
The strange string `arn:aws:iam::${ACCOUNT_ID}:mfa/${IAM_USERNAME}` will
be your user's MFA serial after you have set up everything. The AWS console
will not tell you the MFA serial in advance, but by replacing the account id
and IAM username, you can build it on your own, e.g.:
```
$ ykman oath add -t arn:aws:iam::123456789012:mfa/tommie-lie ABCD1234...
```
The above command requires you to touch your YubiKey to generate
authentication codes. You can ommit `-t` if you don't want to touch your key
every time you authenticate.
5. Now you have to enter two **consecutive** MFA codes into the AWS website
to assign your key to your AWS login. Just run
`ykman oath code arn:aws:iam::${ACCOUNT_ID}:mfa/${IAM_USERNAME}`
to get an authentication code.
The codes are re-generated every 30 seconds, so you have to run this command
twice with about 30 seconds in between to get two distinct codes.
Enter the two codes in the AWS form and click `Assign MFA`
6. You're done!
### Setup AWS CLI
1. AWS CLI only asks for MFA if you change roles, but role-based access
management is a good practice for AWS security anyway, so we'll assume you
already have a role and a profile configured in your AWS CLI config file.
2. Install `awscli-plugin-yubikeytotp`, see [installation section](#installation).
3. Edit your AWS CLI config file (`~/.aws/config`) and add the MFA serial to
the profile you want to use MFA authentication with:
<pre><code>
[profile yubikey]
role_arn = arn:aws:iam::123456789012:role/yubikey-role
<b>mfa_serial = arn:aws:iam::123456789012:mfa/tommie-lie</b>
source_profile = default
</code></pre>
4. Enable the plugin by appending the following section to your AWS CLI config file:
```
[plugins]
yubikeytotp = awscli_plugin_yubikeytotp
```
5. That's it, you're ready to use AWS CLI with your YubiKey now!
### Test your setup
If you need authentication by switching to another IAM role to access certain
resources, you will normally get a permission denied error:
```
$ aws s3 ls
An error occurred (AccessDenied) when calling the ListBuckets operation: Access Denied
```
If you switch profiles, however, AWS CLI will automatically ask for an MFA code:
```
$ aws s3 ls --profile yubikey
Generating OATH code on YubiKey. You may have to touch your YubiKey to proceed...
Successfully created OATH code.
2013-07-11 17:08:50 mybucket
2013-07-24 14:55:44 mybucket2
```
## Acknowledgements
* Thanks to [@woowa-hsw0](https://github.com/woowa-hsw0) for this
[inspiration for this plugin](https://gist.github.com/woowa-hsw0/caa3340e2a7b390dbde81894f73e379d)
Raw data
{
"_id": null,
"home_page": "https://github.com/tommie-lie/awscli-plugin-yubikeytotp",
"name": "awscli-plugin-yubikeytotp",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<3.10",
"maintainer_email": "",
"keywords": "aws,aws-cli,boto3,yubikey",
"author": "Thomas Liebetraut",
"author_email": "thomas@tommie-lie.de",
"download_url": "https://files.pythonhosted.org/packages/a7/8f/9bfc273f9262b46d1cc639af0fde9376bb118d57fad354f755488ac37b7b/awscli-plugin-yubikeytotp-1.1.0.tar.gz",
"platform": null,
"description": "[](https://pypi.python.org/pypi/awscli-plugin-yubikeytotp/) [](https://github.com/psf/black)\n\n\n# Yubikey authentication for AWS CLI (and boto) made easy\n\nThis plugin enables aws-cli to directly talk to your [YubiKey](https://www.yubico.com/)\nto acquire an OATH-TOTP code using the YubiKey's CCID application.\n\nCurrently, FIDO-U2F is unsupported on both, [botocore](https://github.com/aws/aws-cli/issues/3607)\nand [aws-cli](https://github.com/aws/aws-cli/issues/3607).\nUsing aws-cli with roles and a regular OATH-TOTP token at least prompts you for\nthe TOTP code but this is quite cumbersome to use with a YubiKey.\n\n\n## Installation\n\n`awscli-plugin-yubikeytotp` can be installed from PyPI:\n```\n$ pip install awscli-plugin-yubikeytotp\n```\nIt's also possible to install it just for your user in case you don't have\npermission to install packages system-wide:\n```\n$ pip install --user awscli-plugin-yubikeytotp\n```\n\n\n### Configure AWS CLI\nTo enable the plugin, add this to your `~/.aws/config`:\n```\n[plugins]\nyubikeytotp = awscli_plugin_yubikeytotp\n```\nAlso make sure to have your MFA ARN configured for your profile:\n```\n[profile myprofile]\nrole_arn = arn:aws:iam::...\nmfa_serial = arn:aws:iam::...\nsource_profile = default\n```\n\n\n## Usage\n\nJust use the `aws` command with a custom role and the plugin will do the rest:\n```\n$ aws s3 ls --profile myprofile\nGenerating OATH code on YubiKey. You may have to touch your YubiKey to proceed...\nSuccessfully created OATH code.\n2013-07-11 17:08:50 mybucket\n2013-07-24 14:55:44 mybucket2\n```\n\n---\n**NOTE**\n\nTo AWS, the M in MFA [still stands for the number 2](https://forums.aws.amazon.com/thread.jspa?threadID=137055). Hence, if you want to log in to the AWS console with OATH-TOTP\nenabled, you will have to use `ykman oath code` to generate a key and enter it\nmanually to log in, just like with Google Authenticator or Yubikey Authenticator\nsmartphone apps.\n\nIf you want to use U2F MFA authentication for login while still being able to\nuse your YubiKey for command line, you should create multiple IAM users. Use\none user with U2F MFA to log in to the AWS console and disable access keys.\nUse the other use with Virtual MFA device and disable console login.\nOnly ever use one user in the console and the other on your command line.\n\n---\n\n\n## Tutorial\n\n### Prerequisites\n\nYou obviously have to have a YubiKey. A Yubico Security Key (the blue ones)\nare not supported as they lack the OATH application.\n\nTo setup your YubiKey, you also have to have [yubikey-manager](https://developers.yubico.com/yubikey-manager/) (or `ykman`) installed.\nYou can use it to verify that OATH is enabled for your YubiKey:\n```\n$ ykman info\nDevice type: YubiKey 5 NFC\nSerial number: 00000000\nFirmware version: 5.2.4\nForm factor: Keychain (USB-A)\nEnabled USB interfaces: OTP+FIDO+CCID\nNFC interface is enabled.\n\nApplications USB NFC \nOTP Enabled Enabled\nFIDO U2F Enabled Enabled\nOpenPGP Enabled Enabled\nPIV Enabled Enabled\nOATH Enabled Enabled\nFIDO2 Enabled Enabled\n```\n\n### Setup MFA in AWS\n\n1. Log-in to your AWS account/user and navigate to your *My Security Credentials*\npage.\n2. Take not of your *AWS account ID* at the top.\n2. Under *Multi-factor authentivation (MFA)*, click `Manage MFA device` and add\na *Virtual MFA device*.\n3. Instead of showing the QR code, click on `Show secret key` and copy the key.\n4. On a command line, run\n ```\n $ ykman oath add -t arn:aws:iam::${ACCOUNT_ID}:mfa/${IAM_USERNAME} ${MFA_SECRET}\n ```\n The strange string `arn:aws:iam::${ACCOUNT_ID}:mfa/${IAM_USERNAME}` will\n be your user's MFA serial after you have set up everything. The AWS console\n will not tell you the MFA serial in advance, but by replacing the account id\n and IAM username, you can build it on your own, e.g.:\n ```\n $ ykman oath add -t arn:aws:iam::123456789012:mfa/tommie-lie ABCD1234...\n ```\n \n The above command requires you to touch your YubiKey to generate\n authentication codes. You can ommit `-t` if you don't want to touch your key\n every time you authenticate.\n5. Now you have to enter two **consecutive** MFA codes into the AWS website\n to assign your key to your AWS login. Just run\n `ykman oath code arn:aws:iam::${ACCOUNT_ID}:mfa/${IAM_USERNAME}`\n to get an authentication code.\n The codes are re-generated every 30 seconds, so you have to run this command\n twice with about 30 seconds in between to get two distinct codes.\n \n Enter the two codes in the AWS form and click `Assign MFA`\n6. You're done!\n\n\n### Setup AWS CLI\n\n1. AWS CLI only asks for MFA if you change roles, but role-based access\n management is a good practice for AWS security anyway, so we'll assume you\n already have a role and a profile configured in your AWS CLI config file.\n2. Install `awscli-plugin-yubikeytotp`, see [installation section](#installation).\n3. Edit your AWS CLI config file (`~/.aws/config`) and add the MFA serial to\n the profile you want to use MFA authentication with:\n <pre><code>\n [profile yubikey]\n role_arn = arn:aws:iam::123456789012:role/yubikey-role\n <b>mfa_serial = arn:aws:iam::123456789012:mfa/tommie-lie</b>\n source_profile = default\n </code></pre>\n4. Enable the plugin by appending the following section to your AWS CLI config file:\n ```\n [plugins]\n yubikeytotp = awscli_plugin_yubikeytotp\n ```\n5. That's it, you're ready to use AWS CLI with your YubiKey now!\n\n\n### Test your setup\n\nIf you need authentication by switching to another IAM role to access certain\nresources, you will normally get a permission denied error:\n```\n$ aws s3 ls\n\nAn error occurred (AccessDenied) when calling the ListBuckets operation: Access Denied\n```\nIf you switch profiles, however, AWS CLI will automatically ask for an MFA code:\n```\n$ aws s3 ls --profile yubikey\nGenerating OATH code on YubiKey. You may have to touch your YubiKey to proceed...\nSuccessfully created OATH code.\n2013-07-11 17:08:50 mybucket\n2013-07-24 14:55:44 mybucket2\n```\n\n\n## Acknowledgements\n* Thanks to [@woowa-hsw0](https://github.com/woowa-hsw0) for this\n [inspiration for this plugin](https://gist.github.com/woowa-hsw0/caa3340e2a7b390dbde81894f73e379d)\n",
"bugtrack_url": null,
"license": "GPL-3.0-or-later",
"summary": "",
"version": "1.1.0",
"split_keywords": [
"aws",
"aws-cli",
"boto3",
"yubikey"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fc6765f7cab96d8e295b0b5ea5ce4f3c34c03c7f95b617038f6b6f9ad92402c0",
"md5": "315e1a731f95b5050d22734811800ecc",
"sha256": "858c59068f475a64c85bbc912fdaf5169305eb3e3854150a196439b70aa0d236"
},
"downloads": -1,
"filename": "awscli_plugin_yubikeytotp-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "315e1a731f95b5050d22734811800ecc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<3.10",
"size": 6783,
"upload_time": "2023-01-15T15:10:17",
"upload_time_iso_8601": "2023-01-15T15:10:17.973269Z",
"url": "https://files.pythonhosted.org/packages/fc/67/65f7cab96d8e295b0b5ea5ce4f3c34c03c7f95b617038f6b6f9ad92402c0/awscli_plugin_yubikeytotp-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a78f9bfc273f9262b46d1cc639af0fde9376bb118d57fad354f755488ac37b7b",
"md5": "05a7810a20abc288b63351794ebbc78d",
"sha256": "87daa8ba9119fe9183b05b6a030be697a29ed1e103a5acdc737644748c69f166"
},
"downloads": -1,
"filename": "awscli-plugin-yubikeytotp-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "05a7810a20abc288b63351794ebbc78d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<3.10",
"size": 7055,
"upload_time": "2023-01-15T15:10:13",
"upload_time_iso_8601": "2023-01-15T15:10:13.154810Z",
"url": "https://files.pythonhosted.org/packages/a7/8f/9bfc273f9262b46d1cc639af0fde9376bb118d57fad354f755488ac37b7b/awscli-plugin-yubikeytotp-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-15 15:10:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "tommie-lie",
"github_project": "awscli-plugin-yubikeytotp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "awscli-plugin-yubikeytotp"
}
JSON
