Skip to content

Lock Down Your AWS Account with Yubikey

TL;DR: If knowing the why isn’t your thing and you’re only concerned with the how, you’re welcome to skip to here.

Engage the Snark Drive

Anyone who has created an AWS account will relate to the experience of being greeted with a very red and very urgent warning: “Activate MFA on your root account.” This is as it should be. The keys to your root user account are the keys to your cloud computing kingdom.
Ok. So. You’re logged in, and because you are a good, security-minded cloud citizen, you follow the directions to enable said MFA (Multi-Factor Authentication):

  1. You select virtual authenticator device, wonder why only Google Authenticator gets a special call-out, when LastPass Authenticator and Authy, among others, are just fine. Next.
  2. You go through the trouble of downloading Google Authenticator on your phone if you don’t have it and wonder to yourself why it doesn’t have a touch id screen lock like everything else does days (even banks are beating you here, Google. Banks…like Wells Fargo). Next.
  3. You take a picture of the QR code, try to remember what QR stands for, and wait very patiently for the thirty or so seconds to elapse before the number you are now staring at on your phone presumably changes to another number. Three… two… one… Next.
  4. You hurriedly type the new number into the first of two boxes in the next section, courageously swallowing a panic attack because you typed it wrong and must backspace three times, check your phone again, and re-enter the numbers correctly before the bomb goes off—I mean, the TOTP code resets. You wait again. Three… two… one… Next.
  5. The code resets and you enter the second code, more carefully and with greater deliberateness than the last one and, because it turns out that thirty seconds is actually longer than you thought, click to finish the process.

You did it! You defused the bomb and are a truly a hero. The big scary warning is gone; in its place a calming green box with a white check mark. With a sharp jolt, you snap back to reality and remind yourself you actually enjoy being a software engineer, confused about why, out of nowhere, you started imagining yourself as CISO.
You’re safe now. You have multi-factor authentication set up on the root account of your AWS account. Hackerman ain’t gonna get you now, no he ain’t.
… Or is he?

Your Smartphone Will Never Betray You

That was a lie.
Unfortunately, Hackerman still has ways to ruin your day—and more often than not, Hackerman isn’t this guy. Sometimes it’s this guy, this guy (you really should be backing up your data and applications), this guy, or you.
To put it another way:

  • If you have authorized your employer to remotely manage in exchange for permission to check the company Slack on your phone, your virtual authenticator could be gone before you can finish saying “Wait! If you do this, you’ll lock the entire company out of the prod…”
  • If you make a habit of reading Hacker News whilst relieving yourself at work and are at least as clumsy as I am, there is a significant chance you’ll become the harbinger of your own account lockoutocalypse.
  • There is always the possibility that your phone simply gets stolen.

Look. Virtual authentication mobile applications aren’t bad, per se. They’re a good solution for most problems, and definitely preferable to nothing, but hopefully I’ve convinced you they aren’t perfect. Nothing ever is. If you believe otherwise, you’re setting yourself up for failure.
If you haven’t adopted it already, one of the tenets of modern security thinking which should be adopted immediately, goes something like this “nothing is completely secure, and at best, we are simply unaware of the existing vulnerabilities.”

Back To AWS-Land

Ok. Let’s circle back and summarize what we’ve learned so far, before pressing onward:

  • Sophia’s sense of humor may be slightly overbearing for some people and she probably spends way too much time online
  • Enabling Multi-Factor Authentication (MFA) for your AWS root user account is the first and most important security precaution that every AWS account owner should take.
  • While MFA on your personal flavor of mobile device via virtual authenticator applications is orders of magnitude more secure than having no MFA at all, there are many ways that your trusty device can fail you.
  • Sometimes things out of your control will have a non-trivial chance of corrupting your device or permanently preventing your access to it.

If you’re thinking “Well, this situation just sucks,” you’re right. However, not all hope is lost.

Yubikey, Hero of the People

Yubikey, a series of hardware security devices, manufactured by Yubico, gives us a better way. These devices collectively support just about every multi-factor authentication protocol you can imagine—or in the least—would want to use to secure your AWS accounts.
Recently, Yubico released a software product called Yubico Authenticator. It is supported on both desktop (MacOS, Linux, and Windows) and mobile (Android only, at this point in time, unfortunately). When properly configured, Yubico Authenticator will generate OTP codes—and this is the important part—only when a Yubikey which was configured with the cryptographic secret data provided by the account for which you have enabled this MFA scheme is connected to the system.
Yes. It’s a mouthful. Let’s distill it.
Yubico Authenticator is an application that lives on your computer and is responsible for two things:

  • Configuring a connected Yubikey for multi-factor authentication, a la TOTP code generation, according to the data provided by the service for which TOTP-based multi-factor authentication is supported.
  • Reading the contents of authenticated Yubikey devices connected to the system and generating the appropriate TOTP codes necessary to authenticate to your MFA-enabled service.

The actual secret data required to generate the TOTP codes necessary to authenticate with your MFA-enabled service (AWS, in our case) is stored on the Yubikey, not your computer, not your smartphone, and not by the Yubikey Authenticator application.
This is a big deal. Why?
Here are some major reasons:

  • Yubikeys don’t depend on your mobile carrier or a Wi-Fi connection to access the internet.
  • Yubikeys don’t require a battery to work—they’re USB-powered, so there is no risk of losing data because of a faulty battery. Your Yubikey is only ever powered when it is plugged into the machine that needs it for authentication.
  • Yubikeys are discreet. Smaller than most USB drives, Yubikeys don’t pull on the heartstrings of thieves the same way that your fancy new smartphone does.
  • Yubikeys can hold multiple security credential configurations at the same time, so you can use the same Yubikey to generate TOTP codes for multiple accounts and across multiple services.
  • Yubikey configuration slots can be encrypted. By password-protecting the secret data in your Yubikey configuration slots, even if a Yubikey is inserted into a system by a malicious agent, Yubico Authenticator will not begin generating TOTP codes until the configuration is unlocked with your password.
  • Yubikeys are affordable, and due to their small size, you don’t have to feel bad about toting around multiple keys configured for various systems.
  • Due to their affordability, they are a great for backing up configurations. Suppose you lose one of your Yubikeys. If you have bothered to store the same configuration data on multiple other Yubikeys, you can simply go grab your backup from wherever you store your backup credentials. Depending on your particular security needs, you may choose to store your backup key in a vault at your company’s headquarters, a safety deposit box at your personal bank, a fireproof safe in your home, etc. I personally keep two copies of my keys for backup, one in a safety deposit box and one in a fireproof safe in my home. The key that I carry around with me on the daily goes on my lanyard with my ID badge.

Hopefully, by now, I’ve convinced you this is worth doing. Let’s walk through it.

Yubikey + Yubico Authenticator + AWS IAM = Awesome

Down to business: I am going to walk you through setting up Yubico Authenticator and using a Yubikey as your multi-factor authentication device for IAM. There is a specific sequence of steps to do this, as well as configuration value requirements.
IMPORTANT: You will not be able to actually do this unless you have a Yubikey device on hand.

Install Yubico Authenticator on your computer

Yubico Authenticator must be installed on your machine prior to proceeding to subsequent steps of the configuration process. It can be found here.

Begin the process to enable a virtual MFA device for your user

Proceed as you normally would to enable MFA for a user; when given the option to select A virtual MFA device or A hardware MFA device, choose A virtual MFA device and proceed to the next step.

Continue to the page displaying the QR code

If you end up on a page that looks like this, ignore the text and click the Next Step button, which will take you to the most important page of the process.

You should now be on a page displaying a single QR that looks similar to the following image. Stop here and move on to the next step without further interaction with this page. We will come back to it in a future step.
NOTE You will see a QR code and not a giant black square you see here; I’ve blocked out the QR code in our example.

Prepare Yubico Authenticator & Yubikey

The desktop version of the Yubico Authenticator application supports Windows, Linux, and macOS. The layout and exact steps here may vary from operating system to operating system. I am demonstrating this on macOS Sierra. The procedure will not vary much between operating systems, so the general concepts here will apply to any supported system.

Open the Yubico Authenticator App

Having opened the Yubico Authenticator application, and before inserting the Yubikey, you want to use to store your MFA credentials; you should be presented with the following screen (or something similar). Notice that the application indicates no Yubikey is currently connected to the system.

If you navigate to the File menu in the Yubico Authenticator toolbar, you’ll notice that the options Scan QR code... and New credential... are disabled. This is because the there is no Yubikey connected to the system.

Let’s move on to the next step.

Insert Your Yubikey

Insert the Yubikey on which you want to store your TOTP-based MFA secrets and notice how the Yubico Authenticator GUI changes. If you did it right, the application should no longer indicate that no Yubikey is connected to the system. Since I have already gone through this process with the Yubikey I am using in this tutorial, you’ll notice that having inserted the Yubikey, TOTP codes are being generated. Here is what it looks like for me:

Yubico Authenticator will not display similar keys for you, provided you have not gone through this process before.
Open the File menu drop-down from the Yubico Authenticator toolbar again. This time, the Scan QR code... option should be enabled.

Before you click it, position the browser window displaying the QR code such that it is fully-visible and unimpeded by other windows. Once you have done so, navigate back to the Yubico Authenticator application and click the Scan QR code... option in the File drop-down. Here is how this looks on my computer right before I click the option:


Configure the Yubikey and Create a New Credential

If you did this correctly, Yubico Authenticator will open a new window titled “New credential” with a bunch of data filled in. This is the configuration data derived from the QR code on the screen by Yubico Authenticator’s image recognition algorithm.
WARNING: Do not alter any of the populated values. If you do, the configuration will not function correctly, and you will have to wipe your credentials configuration and start over.
Here is how it looks on my machine (I’ve redacted my account name and the secret key associated with it, because they are not for sharing and neither are yours):

Click on the Save Credential button to save the credential data to the inserted Yubikey and complete this step of the process.

Last Step

It’s smooth sailing from here. You’re almost done. Having saved the credentials correctly to your Yubikey, the Yubikey Authenticator application will start generating TOTP codes. Enter two consecutive values into the Authentication code 1 box and Authentication code 2 box, respectively.
Once you’ve entered the codes, click the Activate Virtual MFA button at the bottom of the same screen.
If you followed the steps correctly, the IAM console will indicate that you correctly enabled MFA for your user.
You’re done. You’ve successfully set up a Yubikey to act as the multi-factor authentication mechanism for your AWS IAM user.
PRO TIP: Test the credentials by trying to log into your account from a separate browser and/or browser session with the new user’s credentials, in order to verify they work. If you log out of the current session having misconfigured your Yubikey, you won’t be able to log in again. Always dry-run processes like this so that you get the hang of it before locking down an account that you can’t afford to lose access to.

Conclusion & Final Thoughts

Experiment with It

Now that you have your credentials set up and stored in your Yubikey, you can remove it and re-insert it with whatever frequency and degree of dramatization you desire. When you remove the key, Yubico Authenticator will cease generating codes. When you re-insert it, it will re-commence code generation.

Taking It Further

With a little thought and creativity, the process I’ve outlined here can be applied to configure arbitrarily many Yubikeys against the same QR code, so you can generate as many backup keys as you like. This can be especially useful in cases where it’s important to achieve redundancy across multiple geographies in order to offset the risk of any individual key getting lost. If you’re running your business out of AWS, locking away multiple keys in various places to protect yourself is a smart idea.
I’ve done this and tested it. It works just fine. The key material for your Yubikey configuration is derived directly from the QR code, so it is identical from key to key. All that’s left from here is to decide how to secure your new collection of MFA keys and who else should have them, if any.


This was a fun one to learn how to do and I hope you found it useful. I’ve been looking for ways to separate my multi-factor authentication process from my mobile phone for quite a while and I think I’ve finally settled on an alternative I’m happy with.
If you have any AWS questions that we can help with, please contact us at
Keep learning and stay awesome!