Classic Hardware Tokens for Entra ID MFA - Graph API Method with Self-Service and SHA-256 Tokens Support

To enhance security and simplify administration, Microsoft has introduced the Authentication Methods policy for Microsoft Entra ID. This policy allows administrators to manage Multi-Factor Authentication (MFA) and Self-Service Password Reset (SSPR) settings from a single location, improving the overall user experience. With the migration process now complete, let’s review the key improvements made to the Authentication policy.

According to Microsoft documentation, the ‘Hardware OATH Tokens (Preview)’ feature has received several key updates, including:

• Removal of the global administrator requirement.
• End users can now self-assign and activate tokens directly from their Security Info page.
• Support for SHA-256 tokens, which was previously announced but has now been fully implemented.

Additionally, Microsoft Entra ID now features a new Microsoft Graph API (in preview) for managing tokens in Azure. Administrators can use Microsoft Graph APIs with least-privileged roles to manage tokens in this preview. However, there are no options to manage hardware OATH tokens directly through the Microsoft Entra admin center in this refresh. You can still manage hardware OATH tokens from the original preview in the Entra admin center, but in this new refresh, management is exclusively available through the Microsoft Graph APIs. Tokens added via Microsoft Graph in this preview refresh will appear alongside other tokens in the admin center but can only be managed using Graph APIs.

In this post, we’ll demonstrate how administrators can use the new hardware token repository to enable end users to self-assign a hardware token to their account via the My Security Info page.

Requirements:

The following are the prerequisites to complete this configuration:

• Microsoft Entra ID Premium P1 or P2 license
• Token2 TOTP hardware token(s). With this method, both SHA-1 and SHA-256 models can be used.
• A JSON file for your token device(s). You can request the JSON file from your order page after successful delivery (currently, the first option, as shown below).
  

Please remember to send your public GPG/PGP key when requesting the JSON file to ensure that sensitive data is not transmitted over insecure channels (as most email systems still use insecure protocols).

Enable Hardware OATH Tokens in the Authentication Methods Policy

First, ensure that hardware tokens are enabled for your tenant. The configuration location may vary depending on whether you’ve migrated to the new authentication method policies. Assuming you’ve already migrated, verify that the method is enabled for either all users or for a specific group of users who will be using hardware tokens.

To enable hardware OATH tokens in the Microsoft Entra admin center:

1. Sign in to the Microsoft Entra admin center with at least Authentication Policy Administrator permissions.
2. Navigate to Security > Authentication methods > Hardware OATH tokens (Preview).
3. Enable the method, select the user groups to include in the policy, and then click Save.

Get the JSON File

Microsoft Entra ID supports OATH-TOTP tokens (SHA-1 and SHA-256) that refresh every 30 or 60 seconds. Customers can purchase these tokens from Token2. The JSON file sent by Token2 contains data like the following:

The HashFunction key with the value "hmacsha1" indicates SHA-1, while "hmacsha256" indicates SHA-256. The algorithm will be specified in the JSON file automatically based on the token model.

Upload New Tokens to the Tenant

In this step, we will add the tokens to the tenant, making them available for self-service. We will not assign the tokens directly to users, but instead, make them available in the "public repository" of your tenant. For convenience, we will use Graph Explorer in this example.

Follow this link to access Graph Explorer: https://developer.microsoft.com/en-us/graph/graph-explorer

• Sign in using your credentials.
• Grant consent for the "Policy.ReadWrite.AuthenticationMethod" permission from the "Modify permissions" tab.
• To upload tokens to the tenant, use the PATCH method with the tokens received in the JSON file. The destination endpoint is: https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
• Open the JSON file in a text editor, copy all the contents, and paste the data into the Request body area in Graph Explorer.
• Click the Run query button.

The token will be available for self-service as soon as it is uploaded. You can check the current repository at any time by running the following query:
GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices

User Token Enrollment Process

From the My Security Info page, click "Add sign-in method".

Select the "Hardware token" method from the available options.

Next, the user will be prompted to enter the serial number, typically located on the back of the key.

The user should then enter a name for the new token.

In the final step, the user must enter a 6-digit OTP from the hardware token.

If everything matches, the token will be added to the account.

Logging in

Once the TOTP token is activated and set as the default MFA method, users can use it to log in. The login page will prompt for an 'Authenticator Code' and the OTP generated by the hardware token will be accepted seamlessly.

When the end-user completes the enrollment, the token will be visible in the Entra admin center.

Troubleshooting

Legacy token uploading via CSV allows the addition of duplicate tokens assigned to different users. When uploading tokens via JSON, duplicates should not be allowed, and the serial number and secret key must be unique.

In some cases, a user may have two instances of the same hardware OATH token registered as authentication methods. This occurs if the legacy token is not removed from the OATH tokens (Preview) section in the Microsoft Entra admin center after it has been uploaded using Microsoft Graph. Both instances of the token will be listed in OATH tokens (Preview) in the Microsoft Entra admin center:

You can identify and remove the legacy token by following the steps in the Microsoft documentation

FAQ

How can hardware OATH tokens be managed in Microsoft Entra ID?

In the current preview refresh, hardware OATH tokens can only be managed via the Microsoft Graph API. Although they will appear alongside other tokens in the Microsoft Entra admin center, the management of these tokens is done exclusively through the Graph API. The admin center still supports management of tokens from the original preview, with limited functionality in this refresh.

Does adding a token to the new portal affect its functionality in the legacy portal?

No, adding a token via the Graph API in JSON format will not disable it in the legacy portal. The token will remain functional in both portals until it is explicitly removed from the legacy portal. It will not appear in the 'Hardware OATH Tokens (Preview)' section of the admin center until the token is added through the 'My Security Info' page.

Can a token be added to the new portal if it still exists in the legacy portal?

Yes, a token can be added to the new portal even if it exists in the legacy portal. However, when uploading tokens via JSON, duplicates are not allowed, and the serial number and secret key must be unique. If the legacy token is not removed from the 'OATH tokens (Preview)' section in the admin center after being uploaded via Microsoft Graph, two instances of the same token may appear.

How can tokens be imported into the new portal without requiring any user action?

Tokens can be uploaded to the new portal via the Graph API, and end users will not be aware of the upload. The user will need to take action to activate the token by entering the serial number, token name, and OTP (One-Time Password) on the 'My Security Info' page. They can also delete the token if necessary.

How much time does the user have to activate the token?

There is no limit defined by Microsoft, but we recommend not waiting longer than 2 years. After this period, the token may fail to activate due to time drift.

Does the new provisioning method allow duplicate tokens, as was possible in the legacy portal?

No, the new provisioning method requires that serial numbers be unique and that the secret key cannot be repeated. However, there is a simple workaround to this: you can add an extra zero to the serial number and append "AA" to the secret key ("AA" represents zero in base32). This will make the Graph API treat the token as unique, while the OTP generated and accepted will remain the same as the original token. See the JSON example below:
Original token data:

{
    "@context": "#$delta",
    "value": [
        {
            "@contentId": "1",
            "serialNumber": "865923712",
            "manufacturer": "Token2",
            "model": "C202",
            "secretKey": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP",
            "timeIntervalInSeconds": 30,
            "hashFunction": "hmacsha1"
        }
    ]
}

{
    "@context": "#$delta",
    "value": [
        {
            "@contentId": "2",
            "serialNumber": "86592371200",
            "manufacturer": "Token2",
            "model": "C202",
            "secretKey": "JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXPAA",
            "timeIntervalInSeconds": 30,
            "hashFunction": "hmacsha1"
        }
    ]
}

Are SHA-256 tokens more secure than SHA-1?

Yes, SHA-256 is theoretically more secure than SHA-1. SHA-256 is part of the SHA-2 family of cryptographic hash functions and offers a longer bit length (256 bits) compared to SHA-1 (160 bits), making it less susceptible to collision attacks. However, since TOTP uses SHA-256 in combination with HMAC (Hash-based Message Authentication Code), the security difference between SHA-1 and SHA-256 becomes less critical in this context. That being said, we recommend avoiding TOTP wherever possible. Instead, we prefer to suggest FIDO2 keys as they are phishing-resistant and provide a more robust, secure solution for authentication.