This guide will show you how to automate the process of MFA authentication to access your AWS CLI with a YubiKey. With a simple command, you can generate and inject temporary session credentials directly into your AWS configuration, making your access seamless.

Why Automate AWS CLI MFA with YubiKey?

Here’s the problem: AWS MFA works great for console access, but when it comes to the CLI, it gets tedious. If your account enforces MFA for CLI operations, you need to generate a session token manually like this:

1. Open your authenticator app.
2. Enter the OTP code into a command like this:
   aws sts get-session-token --serial-number <MFA-ARN> --token-code <MFA-Code>
3. Copy-paste the session token into your ~/.aws/credentials file or set an environment variable.

Doable, but repetitive and error-prone. When you're in the middle of debugging a Lambda function or deploying infrastructure with CDK, this is the last thing you want to deal with.

Now let's look at it using the YubiKey and some simple bash scripting. With the companion CLI ykman and the YubiKey plugged in, we can streamline this process:

1. You trigger the key generation with the YubiKey
2. Automatically fetch an MFA code
3. Get a session token from AWS STS and add it to .aws/credentials automatically

Prerequisites

Before we dive in, make sure you have:

• AWS CLI installed and configured with your profiles.
• YubiKey CLI (ykman) installed. Check the docs here.
• jq for parsing JSON.
• A YubiKey.

To configure YubiKey for MFA, follow AWS’s instructions. Once set up, you should have the ARN of your MFA device handy.

Step 1: Register YubiKey as MFA device

To automate AWS MFA, your YubiKey must be registered as a TOTP-based MFA device in your AWS account.

1. Log-in into your AWS account and go to the account dropdown in the top right and click on Security Credentials.
2. Scroll down and in the Multi-factor authentication (MFA) section, click on the Assign MFA device button.
3. Give it a descriptive name, e.g. Yubikey, and chose the Authenticator App option.
4. Click on Show Secret Key and copy the key. Leave the page open, we need it again after the next step.
5. Open a terminal and use this command to register the Yubikey as MFA device where <profile-name> should be replaced with a name for the ykman profile and <secret> should be replaced with the Secret Key you copied in the previous step.
   
   ykman oath accounts add -t <profile-name> <secret>
   
   The -t flag controls, if touching the Yubikey is required to get the OTP from it. You are free to omit it, if you want to fully automate the process.
6. Check if the setup works by running this command, where you should enter the ykman profile name from the previous step.
   
   ykman oath accounts code <profile-name>
7. Enter two consecutive OTP codes generated by ykman into the AWS page. You might need to wait up to 30 seconds to get a new code from the device.
8. Click on Add MFA to finish registration of the Yubikey.

Now as we successfully registered the Yubikey as MFA device, we can continue automating the session token insertion.

Step 2: Automate AWS CLI Session Generation

The last part is bringing all together.

You can find the script on Github.

Make sure you have your ykman profile name, your AWS CLI profile name and the MFA Identifier of your Yubikey at hand. You can find the identifier on the AWS Security Credentials page under the Multi-factor authentication (MFA) section.

• Checkout the script from GitHub and put it your system. For example in ~/scripts/aws-session.sh.
• Make it executable by running chmod +x ~/scripts/aws-session.sh.
• To make it easier to run the script, we need to set up an alias for it. Depending on which shell you are using, put this at the end of either your .bashrc or .zshrc.
  
  alias aws-session='source "~/scripts/aws-session.sh"
  
  This will create an alias for our script so you can use it as aws-session command directly.
• To apply the changes, source the shell config file you just edited. e.g. for .bashrc run:
  
  source ~/.bashrc or
  source ~/.zshrc for zsh
  
  
• Now run the script with the aws-session command. The script will ask for the ykman profile, device ARN and AWS profile upon first execution. Whenever you chose to include the -t flag when setting up the Yubikey, you may be asked to touch the keys button.
• When successful, you should see AWS session credentials successfully updated.

You can now manage your MFA restricted AWS accounts without manually dealing with session tokens and with minimal scripting.