Guide
Collapse MFA for Office 365

How to Add OATH Hardware Tokens to Microsoft Entra ID

Last updated: November 2, 2026

There are two ways to add OATH hardware tokens to Microsoft Entra ID. The Microsoft Graph method, which Microsoft now recommends, uploads tokens to a tenant-wide inventory, supports both SHA-1 and SHA-256, works with the Authentication Policy Administrator role instead of Global Administrator, and lets users assign and activate tokens on their own. The legacy CSV upload in the Entra admin center handles SHA-1 tokens only, requires a Global Administrator, and every token has to be activated by hand. Classic tokens with pre-installed seeds, such as Protectimus Two, need an Entra ID P1 or P2 license either way.
Microsoft Entra ID supports hardware OATH-TOTP tokens for multifactor authentication. Depending on the enrollment method, you can use SHA-1 or SHA-256 tokens with a 30- or 60-second time interval. Please note: you need a Microsoft Entra ID Premium P1 or P2 license to add classic OATH TOTP hardware tokens with pre-installed secret keys. If you don’t have a Microsoft Entra ID Premium P1 or P2 license, use programmable TOTP tokens such as Protectimus Slim NFC or Protectimus Flex, which you can add as if they were an authenticator app. There are currently two ways to add classic OATH hardware tokens to Microsoft Entra ID:
  1. Import tokens using a CSV file in the Microsoft Entra admin center. This is the legacy method inherited from Azure MFA. It supports SHA-1 tokens and requires an administrator to assign each token to a specific user in the CSV file and then activate each token manually.
  2. Add tokens using Microsoft Graph. This newer method is currently in preview and supports both SHA-1 and SHA-256 hardware tokens. You can add tokens to the tenant inventory without assigning them to users in advance, allowing users to self-assign and activate their tokens.
Microsoft currently recommends the Microsoft Graph approach for adding hardware OATH tokens, while CSV upload remains available as an alternative for existing deployments. The instructions below describe both methods.

Before You Start: Requirements

You need a Microsoft Entra ID Premium P1 or P2 license and compatible Protectimus OATH-TOTP hardware tokens, such as Protectimus Two with SHA-1 or Protectimus SHARK with SHA-256. Microsoft Entra supports tokens that generate 6-digit codes with a 30- or 60-second refresh interval. SHA-256 tokens such as SHARK can only be added through the Microsoft Graph method. Admin roles depend on the method. CSV upload is reserved for a Global Administrator. The Microsoft Graph method runs on least-privileged roles: an Authentication Policy Administrator enables the policy and adds tokens to the inventory, while assigning a token to a specific user takes an Authentication Administrator (or a Privileged Authentication Administrator if the target account is itself an admin). Some limits apply no matter which method you pick. A token can be assigned to one user only. Each user can have up to five OATH hardware tokens or authenticator apps registered at the same time. And hardware OATH tokens can’t be assigned to guest users in a resource tenant.

CSV Import vs Microsoft Graph: Which Method to Use

Criterion CSV import (legacy) Microsoft Graph (preview)
Where you work Entra admin center, OATH tokens page Graph Explorer or any Graph client
Hash algorithms SHA-1 SHA-1 and SHA-256
Minimum admin role Global Administrator Authentication Policy Administrator
Token-to-user assignment Fixed in the CSV at upload time Optional; tokens can sit unassigned in the inventory
Activation Admin activates each token manually Admin, or the user via Security info
Management after upload Entra admin center Microsoft Graph only
Compatible with new preview features No Yes
Practical fit A small batch of SHA-1 tokens for known users Bulk rollouts, SHA-256 tokens, delegated or self-service enrollment
For a new deployment, the Graph method is the one to plan around. CSV still has its place when a handful of SHA-1 tokens is going to named users and nobody wants to open Graph Explorer. What you shouldn’t do is upload the same token both ways: it ends up registered twice on the user’s account, and cleaning that up takes several Graph calls (see Troubleshooting below).

Method 1. Import OATH Hardware Tokens Using a CSV File

The CSV import method is the traditional way to add hardware OATH tokens to Microsoft Entra ID. It can be used with SHA-1 OATH-TOTP tokens, such as Protectimus Two. With this method, each token is assigned to a user during import and must then be activated manually by an administrator.

Step 1. Prepare the CSV File

Create a CSV file containing the following information for every token:
upn,serial number,secret key,time interval,manufacturer,model
JohnDoe@yourdomain.com,123456,SECRET_KEY,30,Protectimus,Two
JaneDoe@yourdomain.com,123457,SECRET_KEY,30,Protectimus,Two
The fields are:
  • upn: User Principal Name of the user who will use the token;
  • serial number: unique serial number of the hardware token;
  • secret key: Base32-encoded secret key (seed);
  • time interval: token refresh interval, either 30 or 60 seconds;
  • manufacturer: for example, Protectimus;
  • model: for example, Two.
Make sure that the CSV file includes the header row. Microsoft also specifies that the secret key must be Base32 encoded and is limited to 128 characters.  

Step 2. Open the OATH Tokens Page

Sign in to the Microsoft Entra admin center as a Global Administrator. If the Upload button is greyed out, the signed-in account isn’t a Global Administrator: helpdesk and Authentication Administrator roles can’t upload CSV files. Navigate to Entra ID → Multifactor authentication. Entra ID OATH hardware tokens – Entra ID and Multifactor authentication in the admin center menu Then select OATH tokens (Preview) and click Upload. Entra ID OATH hardware tokens – OATH tokens (Preview) page and Upload button

Step 3. Download the CSV Template

The Bulk Jobs Default panel will open. If necessary, click Download under Download csv template (optional) to download Microsoft’s CSV template, then add your users and OATH token information to the file as described above in Step 1. Entra ID OATH hardware tokens – downloading the CSV template in the Bulk Jobs Default panel

Step 4. Upload the CSV File

Under Upload your csv file, select your completed CSV file. Entra ID OATH hardware tokens – selecting the CSV file to upload After the file has been uploaded successfully, click Submit. Entra ID OATH hardware tokens – submitting the CSV file Depending on the number of tokens, processing may take a few minutes.

Step 5. Refresh the Token List

Click Refresh. After the import is processed successfully, the uploaded hardware tokens will appear in the list. If Microsoft Entra detects an error in the CSV file, the bulk operation will fail. To find out why, select View Details. The Hardware token status panel lists each failed upload; tick the checkbox next to it and select Download to get a file named Failures_filename.csv with the error for every rejected row. The most common one is a UPN that doesn’t exist in the tenant. Note that the column names in this error file differ from the ones you uploaded, so fix your original CSV rather than editing the error file. Upload status records are kept for 30 days. Entra ID OATH hardware tokens – refreshing the token list after CSV import

Step 6. Activate the Hardware Token

Each imported token must be activated individually. Find the required token and click Activate in the Activated column. Entra ID OATH hardware tokens – Activate link in the Activated column Enter the current 6-digit one-time password generated by that hardware token. Entra ID OATH hardware tokens – entering the verification code to activate a token Click OK. If the verification code is correct, Microsoft Entra will activate the token. A check mark will appear in the Activated column. Entra ID OATH hardware tokens – activated token with a check mark Repeat this process for each imported token. The hardware OATH token is now ready to be used for multifactor authentication.

Method 2. Add OATH Hardware Tokens Using Microsoft Graph API

Microsoft has introduced a newer hardware OATH token management system based on Microsoft Graph. The feature is currently in preview. Compared with legacy CSV import, this method provides several important improvements:
  • supports both SHA-1 and SHA-256 OATH-TOTP tokens;
  • does not require a Global Administrator for all token-management operations;
  • allows tokens to be added to the tenant inventory before they are assigned;
  • supports user self-service assignment and activation.
Microsoft Graph currently provides the management interface for tokens added through this new workflow. Such tokens can appear in the Entra admin center, but management of the new inventory is performed through Graph APIs.

Step 1. Enable Hardware OATH Tokens

Before adding tokens, enable the hardware OATH authentication method. Microsoft states that at least the Authentication Policy Administrator role is required to enable this policy. In the Microsoft Entra admin center, navigate to Entra ID → Authentication methods, then select Hardware OATH tokens (Preview). Entra ID OATH hardware tokens – Hardware OATH tokens (Preview) in Authentication methods Turn Enable on. You can make hardware OATH tokens available to All users or select specific groups. Click Save. Entra ID OATH hardware tokens – enabling the Hardware OATH tokens policy Give the change time to propagate. Microsoft notes a delay of up to 20 minutes and recommends allowing an hour before users try to sign in with a new token or look for it in Security info. One thing worth checking if your tenant still uses the legacy MFA policy: there, hardware and software OATH tokens can only be enabled together, so users see a Hardware OATH tokens option in Security info whether you planned for it or not. The Authentication methods policy manages the two separately, and Microsoft recommends migrating to it.

Step 2. Prepare the Token Data

For this method, the token information must be provided in JSON format. Protectimus supplies the token serial numbers and secret keys. Convert this information into the JSON structure required by Microsoft Graph. You can do this using this converter: https://2fasolution.com/entraid.html An example of the JSON structure required by Microsoft Graph:
{
  "@context": "#$delta",
  "value": [
    {
      "@contentId": "1",
      "serialNumber": "TOTP123456",
      "manufacturer": "Protectimus",
      "model": "Two",
      "secretKey": "ILGPXSA75PXK3V77VFZ5QNX25UVFPK2I",
      "timeIntervalInSeconds": 30,
      "hashFunction": "hmacsha1"
    }
  ]
}
For SHA-1 tokens, use: "hashFunction": "hmacsha1" For SHA-256 tokens, use: "hashFunction": "hmacsha256" For multiple tokens, add additional objects to the value array and give each one a unique @contentId:
{
  "@context": "#$delta",
  "value": [
    {
      "@contentId": "1",
      "serialNumber": "TOTP123456",
      "manufacturer": "Protectimus",
      "model": "Two",
      "secretKey": "SECRET_KEY_1",
      "timeIntervalInSeconds": 30,
      "hashFunction": "hmacsha1"
    },
    {
      "@contentId": "2",
      "serialNumber": "TOTP123457",
      "manufacturer": "Protectimus",
      "model": "Two",
      "secretKey": "SECRET_KEY_2",
      "timeIntervalInSeconds": 30,
      "hashFunction": "hmacsha1"
    }
  ]
}
The JSON file holds every token’s secret key in plain text, so treat it like a password vault export: keep it off shared drives and delete it once the upload succeeds. You won’t need it again. After import, Microsoft Graph never returns the secret key, and the secretKey field comes back as null in every response.

Step 3. Open Microsoft Graph Explorer

Open Microsoft Graph Explorer and sign in with an account that holds at least the Authentication Policy Administrator role in your Microsoft Entra tenant. Entra ID OATH hardware tokens – signing in to Microsoft Graph Explorer Select PATCH and enter the following endpoint:
https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
The API version will automatically switch to beta. Entra ID OATH hardware tokens – PATCH request to the hardwareOathDevices endpoint Because this functionality belongs to the Microsoft Graph beta API, Microsoft notes that the API is subject to change and isn’t supported for production applications in the same way as v1.0 APIs.

Step 4. Grant the Required Permission

Open the Modify Permissions tab and click Open the permissions panel. Entra ID OATH hardware tokens – Modify permissions tab in Graph Explorer Expand Policy, find Policy.ReadWrite.AuthenticationMethod and click Consent. Administrator consent is required for this permission. Entra ID OATH hardware tokens – consenting to Policy.ReadWrite.AuthenticationMethod

Step 5. Upload the Hardware Tokens

Return to Request Body and paste the JSON containing your hardware token information. Then click Run query. Entra ID OATH hardware tokens – JSON request body and Run query If the request succeeds, the tokens are added to your tenant’s hardware OATH token inventory and become available for assignment. You can view the current inventory using:
GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices
Entra ID OATH hardware tokens – hardware token inventory returned by a GET request Each token in the response carries a status: available, assigned, activated, or failedActivation. That makes this GET request the quickest way to see which tokens users have already claimed and which are still sitting in the inventory.

Important: Serial Numbers and Secret Keys Must Be Unique

In the Graph-based hardware token inventory, each token must have a unique serial number and secret key. If a token with the same serial number or secret key already exists, Microsoft Graph returns an error such as:
oathTokenNotUnique
Cannot add hardware oath token to inventory because serialNumber and/or secretKey is not unique.
Entra ID OATH hardware tokens – oathTokenNotUnique error in Graph Explorer This is consistent with Microsoft’s model of each hardware token as an individual device in the tenant inventory.

User Self-Service Enrollment

One of the main advantages of the Microsoft Graph method is that an administrator can add hardware tokens to the tenant inventory without assigning them to particular users beforehand. Users can then assign and activate their own hardware tokens. Microsoft explicitly supports self-service operations for hardware OATH token assignment. The user opens their Security info page and selects Add sign-in method → Hardware token. Entra ID OATH hardware tokens – Add sign-in method in Security info Entra ID OATH hardware tokens – Hardware token option in Add a sign-in method Entra ID OATH hardware tokens – Register a hardware token dialog Then they:
  1. Enter the serial number printed on the hardware token.Entra ID OATH hardware tokens – entering the token serial number
  2. Enter a name for the token.Entra ID OATH hardware tokens – naming the hardware token
  3. Enter the current 6-digit OTP generated by the token.Entra ID OATH hardware tokens – entering the code from the token The code has to be submitted quickly: within one minute for a token with a 30-second interval, or within two minutes for a 60-second token. If the window passes, press the token button again and enter a fresh code.
If the serial number and verification code match a token available in the organization’s inventory, Microsoft Entra assigns and activates it for that user. Entra ID OATH hardware tokens – Hardware token added confirmation Fully open self-assignment means anyone in the tenant who holds a token can claim it. If you need certainty that a particular token ends up on a particular account, assign it to that user through Microsoft Graph first (this takes the Authentication Administrator role) and then hand over the device. The user still activates it in Security info, but nobody else can claim it. After activation, the hardware token becomes available as an authentication method for the account.

Logging In

After the TOTP token is activated, the user can use it for authentication. When prompted for an Authenticator Code during sign-in, enter the one-time password generated by the hardware token. If the user has multiple authentication methods registered, such as both a hardware token and an authenticator app, they can choose any available method to complete the authentication. Entra ID OATH hardware tokens – signing in with a code from the hardware token Once the enrollment is complete, the registered hardware token will also appear in the Microsoft Entra admin center. Entra ID OATH hardware tokens – self-enrolled token in the Entra admin center

Troubleshooting and Common Gotchas

The Same Token Appears Twice on a User’s Account

This happens when a token was first uploaded via CSV and later added again through Microsoft Graph, without the legacy copy being removed from OATH tokens in the admin center. To clean it up, list the user’s hardware tokens and note both IDs:
GET https://graph.microsoft.com/beta/users/{user-upn-or-objectid}/authentication/hardwareOathMethods
Then query the inventory by serial number. This request returns only the token created through Graph:
GET https://graph.microsoft.com/beta/directory/authenticationMethodDevices/hardwareOathDevices?$filter=serialNumber eq '{serial}'
The other ID belongs to the legacy copy: remove its assignment with DELETE on the user’s hardwareOathMethods/{legacyId}, then delete it from the inventory with DELETE on hardwareOathDevices/{legacyId}.

Activation Keeps Failing with a Correct-Looking Code

Start with the time interval. If the upload says 60 but the token refreshes every 30 seconds (or the other way round), every code will be rejected, and the only fix is to delete the token and upload it again with the right value. Entra ID corrects normal clock drift on its own (within ±1 day at activation and ±1 minute at sign-in for 30-second tokens, double that for 60-second ones), so a token that has been sitting in a drawer for a few months should still activate. Also confirm that the code comes from the token whose serial number you entered; in a box of identical devices, that mix-up happens more often than you’d expect.

Graph Returns oathTokenNotUnique

The serial number or secret key is already in the inventory. See Important: Serial Numbers and Secret Keys Must Be Unique above.

The Token Doesn’t Show Up in Security Info

If you’ve just enabled the Hardware OATH tokens policy, wait: propagation can take up to an hour. If the token was assigned to a user through Graph, check that the user belongs to a group included in the policy.

FAQ

Do I need a Global Administrator to add OATH hardware tokens to Entra ID?

Only for CSV upload. The Microsoft Graph method works with the Authentication Policy Administrator role for enabling the policy and managing the token inventory, and with the Authentication Administrator role for assigning tokens to users.

Does Microsoft Entra ID support SHA-256 OATH hardware tokens?

Yes, but only through the Microsoft Graph method. Set "hashFunction": "hmacsha256" for each SHA-256 token, such as Protectimus SHARK, in the JSON. CSV upload works with SHA-1 tokens only.

Can users activate their own hardware tokens in Entra ID?

Yes, with tokens added through Microsoft Graph. The user goes to Security info, selects Add sign-in method → Hardware token, and enters the serial number, a display name, and the current code from the token. Tokens uploaded via CSV must be activated by an administrator.

Can I use a hardware token with Entra ID without a Premium P1 or P2 license?

Not a classic token with a pre-installed seed. A programmable token such as Protectimus Slim NFC or Flex can be enrolled through the software-token setup flow instead, the same way as an authenticator app, and that route doesn’t depend on the Premium license. The overview of hardware token options for Entra ID MFA compares both approaches.

Can one hardware OATH token be shared by several users?

No. Microsoft Entra ID allows a token to be assigned to one user only. For shared workstations, each employee needs a personal account and a personal token.

How many OATH tokens can one user register in Entra ID?

Up to five OATH hardware tokens or authenticator apps in total, in any combination.

Is the Microsoft Graph hardware OATH API ready for production?

It’s still a preview built on the Graph beta endpoint, and Microsoft states that beta APIs can change and aren’t supported for production applications. Microsoft nevertheless points admins to this method as the recommended way to add hardware tokens, and tokens uploaded via CSV can’t use the new preview features.

Related Reading

    Questo sito è registrato su wpml.org come sito di sviluppo. Passa a un sito di produzione con la chiave remove this banner.
    Table of Contents