Token2 Hardware OAuth Tokens and Azure AD Access

This blog post walks through the process of logging into Azure AD resources (Office 365, other SaaS applications registered in Azure AD and on-premises applications that utilise Azure AD App Proxy).

First step is to order your desired hardware. For this article we are looking at the devices manufactured by Token2 (www.token2.com). These include credit card style and dongle type devices. The options are available at https://www.token2.com/site/page/product-comparison

For the purposes of this blog post I have been using the TOTP emulator on the Token2 website. This allows you to create virtual TOTP devices and step through and test the entire process without buying a physical token. The TOTP device emulator can be found at https://www.token2.com/site/page/totp-toolset. Each time you browse to this site a new device is emulated, but using key=XXXX, where XXXX is the 32 character device seed. Longer testing will require you to keep a record of the seed ID and use it in the emulator, or keep the browser window open.

Step 1: Order Devices

For this, I am using the emulator mentioned above, but you would order a number of devices and upon arrival request the unique secret identifiers for each device over encrypted email. In Feb 2019 a programmable device with time sync is being released which will allow you to set the secrets yourself and ensure that clock drift on the device is not a reason for them to stop working after a few years!

The secret is required for upload to Azure AD and is required in the form of a CSV file with six columns:

upn,serial number,secret key,timeinterval,manufacturer,model

For example, it could look like this for a two emulated devices:

upn,serial number,secret key,timeinterval,manufacturer,model
user1@token2.com,2300000000001,BMUOZOAFVH4ZYRXU7SFRIIQ3FQNKTDVL,30,Token2,miniOTP-1

user2@token2.com,2300000000002,R5AGIKGVCCGIV275IDTCI2HWDQK3PK2R,30,Token2,miniOTP-1

Ensure each UPN in the first column matches the device you are issuing to the user and upload the CSV file to Azure AD. This is done from Azure Portal > Azure Active Directory left menu > MFA (in Security area) > OAUTH tokens (in settings area):

Click Upload and browse for your CSV file. As long as there are no errors it will upload fine. Errors are displayed in the notifications area. Once the upload is complete click Refresh to see the imported hardware tokens. Tokens assigned to users that do not exist will appear after the user is created, if the user is created within 30 days.

I have in the below screenshot uploaded one token for a test user.

The token needs activating before it can be used. Activation is to confirm the token works and so you will need the next six digit sequence from the device and so have physical access to the device. End user activation is planned, but as of writing in Jan 2019 the administrator needs to activate the hardware token.

Click Activate and enter the current TOTP six digit number. The CSV file contains information about the time change for the device, which is 30 seconds for these Token2 devices, and so you need to enter the current, previous or next ID (next ID is shown in the emulator and not on the hardware token).

Click Activate button when the six digit code is entered. The green ticky ticky next to the number just means you have entered a six digit number, and not that it is the correct number!

After activation you will see the Activated column ticked.

You can now distribute the token to the user.

Step 2: Require token for login

Other blog posts and documentation on the internet cover the requirements for forcing the user to use an MFA device, so here I will just cover what is different when tokens are used. Firstly the user does not need to register their device – the upload of the CSV file and the activation of the token by the administrator covers this step. This does mean though that the user needs the token before they next are required to login with the MFA device or they will not be able to login. Therefore distribution of token following activation, or activation before MFA requirement is currently needed. End user activation which is coming soon will reduce this distribution gap.

Secondly, the code from an Authenticator app (such as Microsoft Authenticator or Google Authenticator) can be used as well as the code from the hardware token device (if the app is registered as well). Microsoft allow multiple devices to provide codes, so the user message on-screen at login will not say “Enter the code from your token2 device” but currently says “Please type in the code displayed on your authenticator app from your device”, but the current code from your hardware device and not only a registered app will work here as well. This is probably the most confusing stage of the process. The hardware token works wherever authenticator app is displayed – maybe this will change.

Finally, the user will only be required for an MFA login if either MFA is enabled for the account or conditional access enabled and the login or application access triggers an MFA requirement. The second of these is the better one to use. The admin configuration to force the user to enter their token one time code though is as follows:

1. Ensure that MFA service settings allows verification code from mobile app or hardware token as shown:
   
2. Ensure that the IP range where MFA is skipped is not the range the user is currently located on, otherwise the user will not be prompted for their MFA token. This IP range is configured in the above settings as well.
3. Ensure that the user requires MFA to login from the MFA users page as shown. Select the user and click Enable:
    
4. Or, if using Conditional Access, that the Grant option includes MFA as one of the requirements as shown:#
   
5. In the first step above you can see that phone calls, text and notification through app are all also enabled. These do not need to be enabled for the hardware device to work.
6. The user needs an Azure AD P1 or P2 licence to use hardware tokens.

Step 3: The user login experience

When the user logs in or accesses an app that is MFA restricted via Conditional Access they will see the MFA login prompt as shown:

The code entered needs to come from their hardware device, as shown below:

The token changes every 30 seconds and is valid for a short while either side of the time it is displayed for on the device. Over time tokens will suffer from clock skew and eventually stop working. The new token2 programmable tokens available in Feb 2019 can have their clocks resynced to fix this issue.

As mentioned above, any registered authenticator app or hardware token uploaded against the user will work – the UX asks for an app at present, maybe this wording will get more clarification when the user has a token registered as well.

Step 4: User experience

Apart from the login, the other place where a user will see their token listed is the My account > Security and Privacy option (click your picture in an Office 365 app to see My account menu). If you have MFA enabled for the user (not just Conditional Access) then the user will see “Additional security verification” on the Security & Privacy page. Here is says “Update your phone numbers used for account security” – but this will list your hardware token as well. This is shown below:

In the above you can see that the user has an iPhone as well as the token, where the hardware token ID matches the serial number on the device that they hold, as well as a phone in this scenario. This allows the user to have a backup MFA method of more than one authenticator (Microsoft Authenticator on iPhone or MFA by phone call in this case) as well as the Authenticator app or hardware token. Your users can now have up to five devices in any combination of hardware or software based OATH tokens and the Microsoft Authenticator app. This gives them the ability to have backup devices ready when they need them and to use different types of credentials in different environments.

The use of a hardware token and its OAUTH code currently still requires a password before MFA token. Password-less token only is expected later in 2019.