From 451f69cc6e5c804290e6835dccfb10fc24c86adb Mon Sep 17 00:00:00 2001 From: Thomas Liebetraut Date: Fri, 28 Feb 2020 16:13:29 +0100 Subject: [PATCH] add tutorial --- README.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/README.md b/README.md index 80eb7fd..5cf0265 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,124 @@ Successfully created OATH code. 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: + 

+   [profile yubikey]
+   role_arn = arn:aws:iam::123456789012:role/yubikey-role
+   mfa_serial = arn:aws:iam::123456789012:mfa/tommie-lie
+   source_profile = default
+
+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