Docs

Guides

Blog

Tools

Using Token2 classic tokens with OKTA (Custom OTP Method)

Okta is a cloud-based identity and access management (IAM) platform that helps organizations securely manage user authentication and authorization for various applications and services. It provides tools for Single Sign-On (SSO), Multi-Factor Authentication (MFA), user lifecycle management, and API access control. Okta supports Token2 classic tokens as a Multi-Factor Authentication (MFA) method via the Custom TOTP factor. This allows you to use a custom time-based one-time passcode (TOTP) solution for user authentication. Your users select the Custom TOTP factor when they sign in and provide the TOTP from their token to access Okta or Okta-protected resources.
Note: Admins must enroll users via the Factors API (user self-service enrollment is not supported), and users can only be enrolled in one custom OTP method at a time.

Requirements:

• Access to the Okta Admin Dashboard.
• A Token2 Classic hardware token.
• A seed file requested from us.

Enable the 2FA Method – Custom OTP

1. In the Admin Console, go to Security → Authenticators.




2. Click "Add authenticator".




3. Click "Add" next to the "Custom OTP" method. Custom One-Time Password (OTP) allows admins to enroll users in a custom OTP authenticator by importing a seed into Okta and authenticating users with the imported hardware token.
4. Depending on the token algorithm you plan to use—SHA-1 or SHA-256—create the appropriate authenticator profile. In this guide, we use SHA-1, but SHA-256 is also supported.




• OTP length: 6
• HMAC Algorithm – select the algorithm that matches your implementation.
• Time step – see Clock drift interval.
• Clock drift interval – this setting defines the tolerance for differences between the token’s clock and the server’s clock.
For example: if you select a time step of 15 seconds and a drift interval of 3, Okta accepts passcodes 15 × 3 = 45 seconds before or after the user enters their passcode.
• Shared secret encoding: base32

5. Enter the values as shown in the screenshot and click "Add" to save the configuration.
6. To copy the Authenticator ID for enrolling users, click Actions → "Authenticator ID & Info" on the saved authenticator, then click the clipboard icon. You will need this ID when enrolling users through the Okta Factors API.




Create token

1. In the Admin Console, go to Security → API.
2. Open the Tokens tab and click "Create token".




3. Enter a name and click "Create token".



4. Then click the clipboard icon to copy the token value for the Okta Factors API call.



Okta Factors API

The Factors API provides operations to enroll, manage, and verify factors for Multi-Factor Authentication (MFA). Typically, authentication involves verifying a time-based one-time passcode (OTP). You can manage both administrative and end-user accounts or verify an individual factor at any time. Okta supports several types of factors, but for classic tokens we use **token:hotp**.




The most commonly used tool for executing Okta API calls is Postman. Okta uses a simple header: Authorization: SSWS




The endpoint used for provisioning this method is a POST request to:

https://okta_org_URL/api/v1/users/user_id/factors?activate=true

With the following body:
{
  "factorType": "token:hotp",
  "factorProfileId": authenticator_ID,
  "provider": "CUSTOM",
  "profile": {
    "credentialId": "[email protected]",
    "sharedSecret": "SN3OBMB5L7QXG5XF5WRGLFCH233655AF",
    "timeStep": 30,
    "keyLength": 6,
    "algorithm": "SHA1"
  }
}
Where:
okta_org_URL – your Okta tenant URL
authenticator_ID – ID of the previously created Custom OTP authenticator
user_id – ID of the user for whom MFA is being configured
A successful response should be:
[
    {
        "id": "chfxv715rtW9yBFaq697",
        "factorType": "token:hotp",
        "provider": "CUSTOM",
        "vendorName": "Token2 OTP Authenticator",
        "status": "ACTIVE",
        "created": "2025-11-28T09:01:10.000Z",
        "lastUpdated": "2025-11-28T09:01:10.000Z",
        "_links": {
            "self": {
                "href": "https://trial-6581012.okta.com/api/v1/users/00uxr55bg4x4AmelN697/factors/chfxv715rtW9yBFaq697",
                "hints": {
                    "allow": [
                        "GET",
                        "DELETE"
                    ]
                }
            },
            "verify": {
                "href": "https://trial-6581012.okta.com/api/v1/users/00uxr55bg4x4AmelN697/factors/chfxv715rtW9yBFaq697/verify",
                "hints": {
                    "allow": [
                        "POST"
                    ]
                }
            },
            "user": {
                "href": "https://trial-6581012.okta.com/api/v1/users/00uxr55bg4x4AmelN697",
                "hints": {
                    "allow": [
                        "GET"
                    ]
                }
            }
        }
    }
]
To delete the currently enrolled authenticator profile, send a DELETE request to the following endpoint:
https://okta_org_URL/api/v1/users/user_id/factors/enrolled_profile_id

Use a classic token to log in

After enrolling the authenticator using the Factors API, you can use the classic token as a multi-factor authentication (MFA) method.



Choose the authenticator used during enrollment and enter the OTP shown on the token display.

Introducing Automatic Token Activation

The Okta Token Manager is a GUI-based Python app that supports automatic activation of Token2 Classic OATH tokens during CSV upload. When tokens are assigned to users in the CSV, the app will:
✔ Load a CSV file containing OTP token data
✔ Look up users in Okta by email
✔ Add hardware/software token factors to Okta users

Additionally:
✔ View Okta users
✔ Test API connectivity
✔ Display detailed logs and token details

Okta Token Manager

Automate OATH Token Activation in Okta

Overview

The Okta Token Manager is a Python script with a GUI that simplifies the process of activating and managing OATH tokens in your Okta environment. This tool automates bulk token registration, saving time and reducing manual errors.





Key Features

  • Bulk Token Import - Load multiple tokens from CSV files
  • Automated User Matching - Automatically find users in Okta
  • One-Click Token Activation - Activate tokens for multiple users simultaneously
  • Real-time Progress Tracking - Monitor activation progress with detailed logs
  • Error Handling - Comprehensive error reporting and troubleshooting

Prerequisites

  • Okta administrator account
  • API token with appropriate permissions
  • OATH tokens available for activation
  • CSV file containing token information

Required CSV Format

Your CSV file must contain the following columns:

Column Name Description Example
upn User email address [email protected]
serial number Token serial number 245252413141
secret key Token secret key SN3OBMB5L7QXG5XF5WRGLFCH233655AF
timeinterval Token time interval (usually 30) 30
manufacturer Token manufacturer Token2
model Token model C202
CSVs for factory-set seeds will be provided by Token2 via the seed request procedure. Choose the format "CSV for Azure MFA...".
The CSV file sent by Token2 does not contain the UPN for your users, so you must add that information manually. Open the file in a text editor and add the missing information. Make sure you include the header row in your CSV file as shown above. Also, please do not edit the CSV file in Excel—use a text editor (Notepad) instead.

Step-by-Step Guide

Step 1: Configure Okta Connection

  1. Launch the Okta Token Manager application
  2. Enter your Okta portal URL (e.g., https://yourcompany.okta.com/api/v1/users/)
  3. Input your API token (generated from the Okta admin console)
  4. Enter the Authenticator ID for OATH tokens
  5. Click "Test Connection" to verify settings

Step 2: Import Token Data

  1. Click the "Load CSV File" button
  2. Select your prepared CSV file
  3. Verify that tokens appear in the table view
  4. Check that the file information shows the correct token count

Step 3: Match Users in Okta

  1. Click "Get User IDs from CSV Emails"
  2. The application will search for each user in Okta
  3. View results in the details panel
  4. Note any users not found for follow-up

Step 4: Activate Tokens

  1. Click "Add Factors to Users"
  2. The application will register tokens with matched users
  3. Monitor progress in real time
  4. Review the summary report upon completion

Step 5: Verify Activation

  1. Test token functionality with end users

Application Interface

Configuration Section

  • Portal URL - Your Okta instance API endpoint
  • API Token - Secure token for API access
  • Authenticator ID - OATH token authenticator configuration

Action Buttons

  • Load CSV File - Import token data
  • Get User IDs - Find Okta users by email
  • Get Users - Retrieve all users from Okta
  • Add Factors - Activate tokens for users
  • Clear Data - Reset application data
  • Clear Details - Clear operation logs

Data Display

  • Token Table - View all imported tokens
  • Details Panel - Operation logs and results
  • Status Bar - Current operation status

Dependencies

pip install requests

Running the Application

Run it with:
python oktaTokenManager.py
View on GitHub
updated: 29/11/2025 18:25