Revision Date: 2018-10-22
The purpose of this document is to provide instructions on how to implement and use YubiKeys with Azure MFA. Azure MFA recently provided support for hardware tokens using time-based one time passcodes (OATH TOTP). OATH hardware tokens are now supported as part of a public preview. For more information about previews, see Azure public preview, Azure Active Directory conditional access preview.
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 now be used as a second factor for Azure MFA protected properties such as Office 365. This document will walk through the steps to setup YubiKeys with Azure Active Directory accounts.
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 through AAD
Have an Office 365 license if you want to set up OTP through the O365 portal.
Microsoft Azure MFA leverages the OATH TOTP protocol, which is based on time. 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.
If you plan to upload TOTP secret keys, you need
The Yubico Manager Command Line Interface Tool (CLI). Download the latest version of the tool at https://developers.yubico.com/yubikey-manager-qt/.
Deploying YubiKeys with Azure MFA
AAD supports the use of OATH-TOTP 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).
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.
As an alternative to uploading TOTP secrets, the individual user can associate the Yubico Authenticator with their Azure and Office 365 accounts as described in Self Service Hardware Token Setup.
Pre-Seeding TOTP Keys
Pre-seeding requires generating base32 secret keys and programming YubiKeys using the Yubico Manager Command Line Interface Tool (CLI). Download this before starting.
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. When generating the secret, ensure the time interval used to generate the secret matches what you upload to Azure.
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 ykman.exe oath add [OPTIONS] USER NAME [SECRET] command with the appropriate configuration options.
- The optional issuer parameter (as seen in Example 2) is a string value indicating the provider or service with which the account is associated.
- The optional label parameter (as seen in Example 2) is used to identify the account with which a key is associated.
Note: If both issuer parameter and issuer label prefix are present, they should be the same.
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 (x86)\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. This example includes the optional issuer information. The issuer parameter is a string value indicating the provider or service this account is associated with. The label is used to identify which account a key is associated with. If both issuer parameter and issuer label prefix are present, they should be equal. “Example” is used as an issuer and as the label information, showing that when both these parameters are used, they must have equal values:
PS C:\Program Files (x86)\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 and 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 characters/digits) 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 Server > OATH tokens, and uploads the file as shown in the screenshot below.
Note: Even though the GUI indicates that this section is designated for the MFA Server, this is the place to upload secrets for Azure MFA as well.
Depending on the size of the CSV file, it may take a few minutes to process. Click the Refresh button to get the current status. If there are any errors in the file, you will have the option to download a CSV file listing the errors to be resolved. If there is an error anywhere in the entry for a particular user, the entry for that user might need to be deleted before you can upload a new secret with the same information.
Once any errors have been addressed, the administrator can then activate each key. Start the Yubico Authenticator application and connect the YubiKey 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 for the user to authenticate to Azure or Office 365.
Azure MFA must be enabled for the individual users and Office 365 must be tied to the AAD where Azure MFA is being leveraged.
Self Service Hardware Token Setup
As an alternative to uploading TOTP secrets, the individual user can associate the Yubico Authenticator 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 one through Office 365.
Note: At this time, tokens setup via self service can be managed only by the individual, not an administrator.
Azure Management Portal
- Log in to portal.azure.com.
- In the search bar at the top of the screen search for “users”, and select Users in the drop down results.
- In the User search field search for your username and select it by clicking it.
- Scroll down to find the Authentication contact information section.
- Click the Access Panel Profile link. A new page opens.
- Click the Additional security verification link.
- Skip to the Additional Security Verification section.
Office 365 Portal
Log in to Office.com.
Click the profile icon in the upper right corner.
Click My account.
In the Security & privacy section, click on Manage security & privacy.
Click Additional security verification.
Click Update your phone numbers used for account security. A new page opens.
Continue to Additional security verification.
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. Click Configure app without notifications. The code to be scanned is displayed as shown in the screenshot below.
3. Insert the YubiKey into the computer and open the Yubico Authenticator application.
4. In the Authenticator, select the File-Scan QR code option. This will scan the QR code displayed in the Azure screen and will populate the scanned data in Yubico Authenticator as shown in the screenshot below.
5. Click Save credential. This completes the configuration.
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 the computer.
Log into Azure with username and password.
At the prompt from Azure, enter the TOTP code displayed by the Yubico Authenticator, as shown on the right in the screenshot below. Either copy and paste or enter the code into the Azure window and then click Verify.
Once the code is verified, the user will be logged into Azure.
Logging into Office 365 with YubiKeys as a Second Factor
Once you have set up the YubiKey with Office 365, the end user will be required to do the following:
Log into Office 365 with username and password.
At the prompt from Office 365, enter the TOTP code displayed by the Yubico Authenticator, shown on the right in the screenshot below. Either copy and paste or enter the code into the Office 365 window shown on the left in the screenshot below and then click Verify.
For additional information about
Azure MFA, review the Microsoft Authentication documentation.
The Yubico Authenticator, refer to the Yubico Authenticator.
OATH - TOTP, refer to the Yubico OATH site.
Azure has published an article in their blog, Hardware OATH tokens in Azure MFA in the cloud are now available.