TOTP Token Inventory: Automate Token2 Classic OATH Token Activation in Microsoft Entra ID

1. Overview

The TOTP Token Inventory app is a powerful, open-source PHP tool designed to automate the management and activation of Token2 Classic OATH hardware tokens in Microsoft Entra ID ( Azure AD (Microsoft Entra ID)). Unlike Microsoft’s official tools, this app offers a user-friendly web interface, bulk operations, and—most importantly—automatic token activation during CSV import, removing the need for manual or separate activation processes.

2. Key Feature: Automatic Token Activation

When uploading a CSV file with tokens pre-assigned to users, the TOTP Token Inventory app will:

• Read the secret key and serial number from the CSV.
• Calculate the current OTP code using the secret key (supports both SHA-1 and SHA-256).
• Send the OTP code to Microsoft Graph API to activate the token for the assigned user.

This feature eliminates the need for our previous bulk activation tools, making the entire process seamless and efficient.

3. Comparison: TOTP Token Inventory vs. Microsoft’s Official Tools

A. Microsoft’s CSV-Based OATH Tokens Blade (Admin Center)

• How it works: Admins upload a CSV file via the Entra Admin Center to import and assign tokens.
• Limitations:
  • Manual process: No automation or self-service for end users.
  • No bulk assignment: Admins must manually assign tokens to users after import.
  • No automatic activation: Requires separate steps for token activation.
  • No SHA-256 support: Limited to basic token configurations.
  • No logging: Lacks detailed operation logs for auditing.
• Best for: Small-scale deployments with minimal automation needs.

B. Microsoft Graph API (Preview)

• How it works: Admins use Graph API endpoints to upload, assign, activate, and delete tokens programmatically.
• Advantages:
  • Supports bulk operations via API calls.
  • Enables self-service activation for end users.
  • Supports SHA-256 and advanced token configurations.
• Limitations:
  • Requires scripting: Admins must write and maintain PowerShell, Python, or other scripts.
  • No UI: API-only; not accessible to non-technical users.
  • No automatic activation: Requires manual or scripted activation steps.
• Best for: Organizations with technical resources for scripting and automation.

C. TOTP Token Inventory (PHP App)

• How it works: A web-based PHP app that uses Microsoft Graph API under the hood, providing a user-friendly interface for bulk import, assignment, automatic activation, and deletion of tokens.
• Advantages:
  • Automatic token activation: When tokens are assigned to users in the CSV, the app automatically activates them by calculating the OTP code and sending it to Graph API (supports SHA-1 and SHA-256).
  • Bulk CSV/JSON import: Upload hundreds of tokens at once.
    • CSV format: Used for pre-assignment (admins can assign tokens to users in the CSV).
    • JSON format: Used for self-service (tokens are uploaded to a shared repository; users activate them via their Security Info page).
    • Automatic conversion: The app converts CSV to JSON for Graph API, simplifying the process.
  • Self-service activation: Users activate tokens via a web form or their Security Info page.
  • SHA-256 support: Auto-detects and handles both SHA-1 and SHA-256 tokens, including their automatic automation.
  • Detailed logging: Tracks all operations (import, assign, activate, delete) for auditing.
  • No scripting required: Accessible to non-technical admins via a web UI.
  • Open-source: Free to use, modify, and deploy.
  • Bundled app: Available as a PHPDesktop-based Windows app—no server required.
• Best for: Organizations needing a scalable, user-friendly, and automated solution for Token2 Classic OATH tokens.
  
  
  

• Server: Works on any server with PHP 7.4+ (Linux/Windows).
• Bundled App: We also provide a PHPDesktop-based Windows app, so you can download and run it directly on a Windows machine without a server.
• Microsoft Entra ID:
  • Tenant ID, Client ID, and Client Secret (from an App Registration with Graph API permissions).
  • Required permissions (API permissions → Add a permission → Microsoft Graph → Application permissions):
    • Policy.ReadWrite.AuthenticationMethod
    • UserAuthenticationMethod.ReadWrite.All
    • User.Read.All
    • Directory.Read.All
  • Do not forget to grant admin consent for the above permissions.
• Token2 Classic Tokens: CSV file with token details (serial number, secret key, UPN, etc.). CSVs for factory-set seeds will be provided by Token2 via the seed request procedure.

---

Creating the App Registration for TOTP Tokens Inventory

To use the TOTP Tokens Inventory portal, you need to create an app registration in Azure AD (Microsoft Entra ID) with the correct Microsoft Graph API permissions. This can be done in two ways:

Main Method: Using the Azure Portal (Web UI)

1. Sign in to the Azure portal with a Global Administrator account.
2. Navigate to Azure Active Directory > App registrations, then click New registration.
3. Enter a name, e.g. TOTP Tokens Inventory, and leave the other defaults unless your scenario requires otherwise. Click Register.
4. Open the new app and go to API permissions.
5. Click Add a permission > Microsoft Graph > Application permissions.
6. Select the following permissions:
   • Policy.ReadWrite.AuthenticationMethod
   • UserAuthenticationMethod.ReadWrite.All
   • User.Read.All
   • Directory.Read.All
7. Click Add permissions and then click Grant admin consent.
8. Go to Certificates & secrets, create a new client secret, and copy the generated value. This secret is only displayed once.
9. Note down the Application (client) ID and the client secret — these will be used to configure the portal.

Alternative Method: Using PowerShell/Azure CLI

As an alternative to creating the app registration manually, you can automate the process with a single PowerShell/Azure CLI one-liner. This script creates the app registration, assigns the required Microsoft Graph API permissions, generates a client secret, and automatically grants tenant-wide admin consent (if run by a Global Administrator). The command will output the app’s Client ID and Client Secret, as well as the Tenant ID, which can then be used to configure the portal.

 
$app=(az ad app create --display-name "TOTP Tokens Inventory" --query "{appId:appId,id:id}" -o json | ConvertFrom-Json); `
az ad app permission add --id $app.id --api 00000003-0000-0000-c000-000000000000 --api-permissions 246dd0c9-77e5-441e-b7b4-91a49b036bad=Role 9f06204d-73c1-4d4c-880a-6edb90606fd8=Role df021288-bdef-4463-88db-98f22de89214=Role 5778995a-e1bf-45b8-affa-663a9f3f4d04=Role; `
$secret=(az ad app credential reset --id $app.appId --query "{clientSecret:password}" -o json | ConvertFrom-Json); `
az ad app permission grant --id $app.appId --api 00000003-0000-0000-c000-000000000000 --scope Policy.ReadWrite.AuthenticationMethod UserAuthenticationMethod.ReadWrite.All User.Read.All Directory.Read.All; `
az ad app permission admin-consent --id $app.appId; `
$tenantId = az account show --query tenantId -o tsv; 
Write-Output "Tenant ID: $tenantId"; Write-Output "Client ID: $($app.appId)"; Write-Output "Client Secret: $($secret.clientSecret)"

 

Notes:

• You must run this with an account that has Global Administrator rights for admin consent to succeed.
• The client secret is only displayed once — make sure to copy and store it securely.

---

5. Supported Formats

Format	Use Case	Description
CSV	Bulk import with pre-assignment and automatic activation	Admins can pre-assign tokens to users in the CSV. The app will automatically activate these tokens by calculating the OTP code and sending it to Graph API. CSVs for factory-set seeds are provided by Token2.
JSON	Self-service repository	Tokens are uploaded to a shared repository. Users activate them via Security Info.

6. Step-by-Step: Using TOTP Token Inventory

A. Initial Setup

1. Download and install:
   • Deploy on a PHP server or use the bundled Windows app.
2. Enter credentials:
   • Provide your Tenant ID, Client ID, and Client Secret. 
     
     
     Decide whether you want to view logs for every API call by enabling the 'Show operation logs' checkbox. An example of such a log output is shown in the screenshot below.
     
     

B. Importing Tokens

1. Prepare your CSV:
   • Include columns: upn, serial number, secret key, timeinterval, manufacturer, model.
   • Optionally, pre-assign tokens by including user UPNs. The app will automatically activate these tokens.
   • CSVs for factory-set seeds are provided by Token2 via the seed request procedure.
2. Upload CSV/JSON:
   • Use the web interface to upload your file.
   • The app automatically converts CSV to JSON for Graph API and activates pre-assigned tokens.
     
     

C. Assigning Tokens

1. Search for users:
   • Use the web UI to find and assign tokens to users.
     
2. Bulk assignment:
   • Assign multiple tokens at once using the CSV pre-assignment feature.

D. Activating Tokens

1. Automatic activation:
   • When tokens are pre-assigned in the CSV, the app automatically activates them by calculating the OTP code and sending it to Graph API.
     
2. User self-service:
   • Users activate tokens via the web form or their Security Info page. For this use case, import the JSON file using TOTP Tokens inventory app.
3. Manual Activation:
   • You have the option to manually activate each TOTP token assigned to a user, as it is done in the legacy OATH Portal. This requires having the physical token in your possession.
     
     
     However, if you don’t have the token but have its seed, the app can automatically generate TOTP codes from the secret key for activation.
     
     
     
     

E. Managing Tokens

• Unassign/Delete: Remove tokens from users or delete them permanently.
• Logs: View detailed logs for all operations.

7. Advantages of TOTP Token Inventory

• Automatic Token Activation:
  • When uploading a CSV with pre-assigned tokens, the app automatically activates them by calculating the OTP code and sending it to Graph API.
  • Supports both SHA-1 and SHA-256 tokens.
  • Eliminates the need for separate bulk activation tools.
• User-Friendly & Accessible:
  • No scripting: Admins and users interact via a web UI, reducing errors and training needs.
  • Self-service: Users activate tokens without admin intervention.
• Bulk Operations & Automation:
  • CSV/JSON import: Upload and assign hundreds of tokens at once.
  • Auto-conversion: CSV files are automatically converted to JSON for Graph API.
• Advanced Features:
  • SHA-256 support: Handles both SHA-1 and SHA-256 tokens.
  • Time drift adjustment: Automatically adjusts for token time drift.
  • Detailed logging: Tracks every action for compliance and troubleshooting.
• Open-Source & Flexible:
  • Free to use and modify: Customize the app to fit your workflows.
  • Bundled app: Run on Windows without a server using PHPDesktop.
• Role-Based Access:
  • Uses least-privilege roles (e.g., Authentication Policy Administrator).

8. Best Practices

• Backup credentials: Store your Client Secret securely.
• Test with a small batch: Validate the workflow before bulk importing.
• Monitor logs: Use logs to audit operations and troubleshoot issues.
• Keep permissions updated: Ensure Graph API permissions are current.

Say goodbye to manual activation processes—TOTP Token Inventory automates everything.

Note: Please note that the desktop app is quite large (166 MB) because it includes a bundled PHP server and CEF browser. This is only necessary if you don’t have a web server with PHP installed.

---

Known Issues & FAQ

After deleting the tokens or assignments, I’m unable to import new tokens
After performing certain operations, such as deleting a token or assignment, you may need to wait more than 15 minutes before retrying. This delay is reportedly a DoS protection measure by Microsoft. If logging is enabled, you might see an entry like:

"message": "There was an issue adding the token to the inventory. Try again in 15 minutes."

Can I use the same CSV file for both Entra ID OATH Blade and the TOTP Tokens Inventory app?

Yes, you can use the same file for both systems if you only have SHA-1 tokens. The Entra ID OATH Blade does not support SHA-256, so CSV files containing SHA-256 tokens can only be used with our tool (which will convert them from CSV to JSON).