This document provides instructions for implementing and using YubiKeys with an enterprise Azure Active Directory (AAD) with Azure Multi-Factor Authentication (MFA). Azure MFA provides support for hardware tokens using time-based one time passcodes (TOTP) as part of the Initiative for Open Authentication (OATH), and hardware tokens are supported as part of a public preview. For more information about Azure MFA, see Microsoft’s “How it works: Azure Multi-Factor Authentication”.
The cloud-based Azure MFA can now leverage YubiKeys the way the on-prem Azure MFA server solution does. This document focuses on cloud-based Azure MFA implementations and not on the on-prem Azure MFA Server. YubiKeys can be used as a second factor for Azure MFA-protected properties such as Office 365 (O365). This document provides instructions for setting up YubiKeys with Azure Active Directory accounts.
Prerequisites to Using YubiKeys with Azure MFA
For YubiKeys to work with Azure MFA, you need an Azure AD Premium subscription for Azure MFA, and the account must:
Reside within the Azure Active Directory (AAD)
Have an Azure AD Premium license assigned
Have MFA enabled for each user through AAD
To leverage Azure MFA with the O365 portal, each end-user needs to have an Office 365 license assigned to his or her Azure account.
Microsoft Azure MFA leverages the OATH TOTP protocol. Because the YubiKey does not contain a battery and thus cannot track time, a further requirement is the Yubico Authenticator for desktop and/or Android phone, to generate time-based one time passcodes for OATH-TOTP credentials. Download the latest version of it at https://www.yubico.com/products/services-software/download/yubico-authenticator/.
You can either upload TOTP secrets as admin, or the individual user can do self-service token setup to associate the Yubico Authenticator application with their Azure AD Account.
Note: Self-service token setup cannot be managed by an administrator, only by the individual.
- If you plan to upload TOTP secret keys, you also need the YubiKey Manager CLI tool, the latest version of which is here: https://developers.yubico.com/yubikey-manager-qt/.
Deploying YubiKeys with Azure MFA
AAD supports the use of OATH-TOTP Secure Hash Algorithm 1 (SHA-1) tokens with 30-second or 60-second refresh intervals. Microsoft specifies that up to five MFA tokens can be associated with one account. The limit applies to hardware and software OATH-TOTP tokens and to Microsoft Authenticator apps. For example, you can associate three YubiKeys, one Microsoft Authenticator app, and a phone number to an individual account if no other OATH token is being used. YubiKeys can be deployed into Azure in two ways. A YubiKey can be paired with an individual account, or the OATH tokens can be uploaded into Azure.
Uploading OATH Tokens
OATH tokens can be uploaded for one YubiKey or multiple YubiKeys. The process requires pre-seeding the YubiKeys and then uploading those secret keys into Azure and activating the user’s account.
Yubico can provide bulk provisioning that will pre-seed YubiKeys with TOTP secret keys for larger orders. Contact your Yubico sales representative or Yubico directly for more information on this. The instructions provided below are for users who do not require bulk provisioning.
Pre-Seeding TOTP Keys
Pre-seeding requires first generating base32 secret keys and then programming YubiKeys using the YubiKey Manager CLI (ykman) tool. You will need to generate your own TOTP base32 secrets. If you do not have a way to create them yourself, there are a number of sites that will do this for you.
Note: When generating a secret, ensure the time interval used to generate the secret matches what you upload to Azure.
- Download and install the latest version of the Yubico Manager CLI (ykman) tool.
- To program a YubiKey for OATH TOTP using the Yubico Manager CLI, navigate to the ykman.exe directory, and in PowerShell, CMD, or Terminal, run the command
ykman.exe oath add [OPTIONS] USERNAME(UPN) [SECRET]
with the appropriate configuration options:
- The optional issuer parameter (as seen in Example 2 below) is a string value indicating the provider or service with which the account is associated.
- The optional label parameter (as seen in Example 2 below)) is used to identify the account with which a key is associated.
Note: If both issuer parameter and issuer label prefix are present, they must have identical values.
To see all the configuration options, consult the YubiKey Manager CLI (ykman) User Manual: https://support.yubico.com/support/solutions/articles/15000012643-yubikey-manager-cli-ykman-user-manual.
The following examples provision a TOTP key.
The TOTP key is provisioned using the add command for user alice@<tenant name>.onmicrosoft.com:
PS C:\Program Files\Yubico\YubiKey Manager> .\ykman.exe oath add alice@<tenant name>.onmicrosoft.com
After pressing Enter, the following prompt appears. The example input entered is the secret key:
Enter a secret key (base32): aqon zybi 4tdq zi6b oqwa scx6 gfje tu2v
The TOTP key is provisioned using the uri command for the account name and the secret set in the same command line. “Example” is used as an issuer and as the label information, showing that when both these parameters are used, they must have identical values:
PS C:\Program Files\Yubico\YubiKey Manager> .\ykman.exe oath uri 'otpauth://totp/Example:alice@<tenant name>.onmicrosoft.com?secret=aqonzybi4tdqzi6boqwascx6gfjetu2v&issuer=Example'
Uploading TOTP keys to Azure
Once the YubiKey is programmed with TOTP, the information must be uploaded in a comma-separated values (CSV) file format that includes the header row with the following values:
The content of the example file shown below uses the YubiKey serial number found on the back of the key; however, any alphanumeric string (max. 42 alphanumeric characters) can be used for the serial number. Leveraging the YubiKey serial number provides a simple way to ensure uniqueness.
upn,serial number,secret key,timeinterval,manufacturer,model
alice@<tenant name>.onmicrosoft.com,1234567, 1234567890abcdef1234567890abcdef,30,YubiKey,HardwareKey
To upload the CSV file, an administrator signs in to the Azure portal and navigates to Azure Active Directory > MFA > OATH tokens, and uploads the file as shown in the screenshot below.
Depending on the size of the CSV file, it may take a few minutes to process. Click Refresh to get the current status. If there are any errors in the file, you will have the option to download a file listing the errors to be resolved. Correct the errors and upload your CSV file again. If it tells you that you have a duplicate entry, delete the duplicate and upload the CSV file again. For a different error, you might need to go into Azure MFA and delete the TOTP code that is already there in order to be able to upload your current CSV file.
Once the CSV file(s) have been successfully uploaded, the administrator can then activate each key. Start the Yubico Authenticator application and insert the YubiKey into a port connected to the computer. Click Activate for the token as shown in the screenshot above. The Yubico Authenticator will start displaying the TOTP codes which can either be copied or typed into the activation input box. Once the code is validated, the YubiKey is ready to be used by the end-user to authenticate to Azure or O365.
Self-Service Hardware Token Setup
As an alternative to uploading TOTP secrets, the individual user (not the administrator) can associate the Yubico Authenticator application with their Azure AD Account. There are two portals that can be used to access the Azure MFA configuration screen, one through the Azure management portal and the other through O365. Instructions are given for each. “Security info” Screen (the section that follows these two), is common to both portals.
Via the Azure Management Portal
Note: If the instructions below do not correspond to your Azure screens, Appendix A provides instructions for the legacy screens.
Log in to portal.azure.com.
In the search bar at the top of the screen enter “users”, then select Users from the list of results.
In the Name field at the top of the Users - All Users screen, enter your name (unless it is immediately visible in the list of users displayed on the page, in which case you can select it directly).
Click on your name in the list of results.
Scroll down to find the Authentication contact info section and click Authentication methods.
Click Access Panel Profile to open a new page.
Click Edit security info.
Skip to the "Security info" Screen section below.
Via the O365 Portal
Log in to Office.com.
Click on the profile icon in the upper right corner.
Click My account.
Find the Security & privacy section and click Manage security & privacy.
Click Additional security verification.
Click Update your phone numbers used for account security to open the Security Info screen..
Continue on with the "Security info" Screen section below.
“Security info” Screen
On the Security info screen, click Add method.
On the Add a method screen, make sure Authenticator app is shown and click Add.
To use the Yubico Authenticator app with the YubiKey, on the next screen (shown below), select I want to use a different authenticator app.
A QR code will be displayed, as shown in the following screenshot:
Insert the YubiKey into the computer and open the Yubico Authenticator application.
On the Authenticator application, select the File-Scan QR code option. This will scan the code from the Azure screen to populate the Yubico Authenticator as shown in the screenshot below.
Click Save credential. This completes the configuration. Once the credential is saved, the Yubico Authenticator should generate TOTP codes. If it does not, restart the Yubico Authenticator.
Once the Yubico Authenticator app is generating TOTP codes, without closing the Yubico Authenticator app, return to the authenticator app setup screen in Azure and click Next.
Copy the TOTP code from the Yubico Authenticator app and paste it into the Authenticator app screen in Azure, as shown in the screenshot below:
- Click Done and Azure MFA will validate and activate the Yubico Authenticator app.
Set Default Sign-in Method
Return to Azure’s Security info screen and set the default sign-in method to Authenticator app or hardware token.
Logging into Azure with YubiKeys as a Second Factor
Once you have set up the YubiKey with Azure MFA, the end user will be required to do the following:
Launch the Yubico Authenticator application.
Insert the YubiKey into their computer.
Log into Azure with their username and password.
At the prompt from Azure, the user enters the TOTP code displayed by the Yubico Authenticator, as shown on the right in the screenshot below. The user either copies and pastes or manually enters the code into the Azure window and then clicks Verify.
Once the code is verified, the user will be logged into Azure.
Logging into O365 with YubiKeys as a Second Factor
Once you have set up the YubiKey with O365, the end user will be required to do the following:
Log into O365 with their username and password.
At the prompt from O365, the user enters the TOTP code displayed by the Yubico Authenticator, as shown on the right in the screenshot below. The user either copies and pastes or manually enters the code into the O365 window and then clicks Verify.
Password Reset With Your YubiKey
A convenient way to reset the password for your Azure account is to use your YubiKey to validate your ownership of the account. If you forget your password, you can use your YubiKey to generate a TOTP code so that you can reset the password.
For additional information about
Azure MFA, review the Microsoft Authentication documentation.
The Yubico Authenticator, refer to the documentation for the Yubico Authenticator.
OATH - TOTP, refer to the Yubico OATH site.
In addition, Azure has published an article in their blog, "Hardware OATH tokens in Azure MFA in the cloud are now available".
Listed below are some common troubleshooting tips. In addition, you can visit Microsoft’s “Troubleshooting Azure Multi-factor Authentication issues” site.
CSV file (OATH script) will not load
The most common reasons for failure to upload are:
- The file is improperly formatted
- The header row is not included in the file
- There are duplicate entries in the file
Make sure you are looking at the current status of the upload by clicking on the refresh button. If an error message appears, click on the Details link and download the file that had failures. The downloaded file will have a Status column that will include information on the failure.
CSV file (script) installed but YubiKey is not working
The problems and fixes for this might be any of the following:
- If the script loads properly but the YubiKey TOTP code does not authenticate properly so that you see the login screen stating, “You didn't enter the expected verification code”, verify that the OATH token is activated within Azure.
- The YubiKey will not authenticate if the TOTP secret key is not properly installed on the YubiKey. To ensure the OTP credential is correct, you might need to delete the credential and add the secret again. To add the secret again, follow the instructions in the Resetting the OTP Applet on the YubiKey guide.
Appendix - Alternate Self-Service Setup
Some Azure tenants might have a legacy UI to setup the Yubico Authenticator application. Follow these instructions if the instructions described and illustrated above in Via Azure Management Portal do not match what you are seeing.
Via Legacy Azure Management Portal
- Log in to portal.azure.com.
- In the search bar at the top of the screen enter “users”, then select Users from the list of results.
- In the Name field at the top of the Users - All Users screen, enter your name (unless it is immediately visible in the list of users displayed on the page, in which case you can select it directly).
- Click on your name and scroll down to find the Authentication contact information section.
- Click Access Panel Profile. A new page opens.
- Click Additional security verification.
- Skip to the Additional Security Verification section below.
Via Legacy O365 Portal
- Log in to Office.com.
- Click the profile icon in the upper right corner.
- Click My account.
- In the Security & privacy section, click Manage security & privacy.
- Click Additional security verification.
- Click Update your phone numbers used for account security. A new page opens.
- Continue to the Additional Security Verification section below.
Additional Security Verification
- Click Set up Authenticator app as shown in the screenshot below.
The system asks you to configure a mobile app and a QRCode is displayed, as shown in the screenshot below:
2. To display the code to be scanned (which is not the one shown in the screenshot above), click Configure app without notifications. The code to be scanned is displayed on the next screen, as shown in the screenshot below.
3. Insert the YubiKey into the computer and open the Yubico Authenticator application.
4. To scan the QR code in the Azure screen and populate the Yubico Authenticator with it, select File-Scan QR code as shown in the screenshot below:
5. Click Save credential. This completes the configuration.