Upload hardware OATH tokens in CSV format

Hardware OATH tokens typically come with a secret key, or seed, preprogrammed in the token. Before a user can sign in to their work or school account in Microsoft Entra ID by using a hardware OATH token, an administrator needs to add the token to the tenant. The recommended way to add the token is by using Microsoft Graph with a least privileged administrator role. For more information, see Hardware OATH tokens (preview).

As an alternative to using Microsoft Graph APIs, tenants with a Microsoft Entra ID Premium license can have a Global Administrator input these keys into Microsoft Entra ID. Secret keys are limited to 128 characters, which isn't compatible with some tokens. The secret key can only contain the characters a-z or A-Z and digits 2-7, and must be encoded in Base32.

Programmable OATH time-based one-time passcode (TOTP) hardware tokens that can be reseeded can also be set up with Microsoft Entra ID in the software token setup flow.

Once tokens are acquired, a Global Administrator must upload them in a comma-separated values (CSV) file format. The file should include the UPN, serial number, secret key, time interval, manufacturer, and model, as shown in the following example:

upn,serial number,secret key,time interval,manufacturer,model
Helga@contoso.com,1234567,2234567abcdef2234567abcdef,60,Contoso,HardwareKey

Note

Make sure you include the header row in your CSV file.

Once properly formatted as a CSV file, the Global Administrator can then sign in to the Microsoft Entra admin center, navigate to Protection > Multifactor authentication > OATH tokens, and upload the resulting CSV file.

Depending on the size of the CSV file, it can take a few minutes to process. Select the Refresh button to get the current status. If there are any errors in the file, you can download a CSV file that lists any errors for you to resolve. The field names in the downloaded CSV file are different than the uploaded version.

Once any errors are addressed, a Privileged Authentication Administrator or an end user can activate a key. Select Activate for the token and enter the OTP displayed on the token. You can activate a maximum of 200 OATH tokens every 5 minutes.

Users can have a combination of up to five OATH hardware tokens or authenticator applications, such as the Microsoft Authenticator app, configured for use at any time. Hardware OATH tokens can't be assigned to guest users in the resource tenant.

Important

Make sure to only assign each token to a single user. A single token can't be assigned to multiple users.

Troubleshooting a failure during upload processing

At times, there may be conflicts or issues that occur with the processing of an upload of the CSV file. If any conflict or issue occurs, you'll receive a notification similar to the following:

To determine the error message, be sure and select View Details. The Hardware token status blade opens and provides the summary of the status of the upload. It shows that there's been a failure, or multiple failures, as in the following example:

To determine the cause of the failure listed, make sure to click the checkbox next to the status you want to view, which activates the Download option. This downloads a CSV file that contains the error identified.

The downloaded file is named Failures_filename.csv where filename is the name of the file uploaded. It's saved to your default downloads directory for your browser.

This example shows the error identified as a user who doesn't currently exist in the tenant directory:

Once you've addressed the errors listed, upload the CSV again until it processes successfully. The status information for each attempt remains for 30 days. The CSV can be manually removed by clicking the checkbox next to the status, then selecting Delete status if so desired.

Related content

Learn more about how to manage OATH tokens. Learn about FIDO2 security key providers that are compatible with passwordless authentication.