Hardware Tokens
HMAC-based One-Time Password (HOTP) tokens are hardware devices that generate single-use passcodes based on a shared secret and an incrementing counter.
Overview
Unlike TOTP, HOTP codes are not time-bound - they remain valid until the next code is generated, making them well-suited for offline environments or systems where clock synchronization is unreliable.
Enabling Hardware Tokens
Before using hardware tokens, enable them under Authentication > Multi-Factor Authentication > Login with One-Time Codes:
Check Use passcodes from hardware tokens
Enter a domain and URL in the Token Configuration section
The Hardware Tokens dashboard is accessible from Authentication > Hardware Tokens.
Managing Tokens
Community Administrators with the appropriate permissions can provision, assign, modify, and export tokens from the Hardware Tokens dashboard.
Provisioning Tokens
Tokens are imported via CSV. Click Import Tokens on the dashboard, then upload a file or paste token data directly in this format:
<serial number>,<HOTP secret key>,<HOTP counter>The counter field is optional - if omitted, it defaults to 0. Imported tokens start with an inactive status and become active on first use.
CSV rules:
Maximum 25,000 records per upload; file size must not exceed 25MB
Counter must be a non-negative integer (no decimals, negatives, or special characters)
No blank rows between records
Assigning Tokens to Users
Click a token's serial number to open its details, then click Add User and enter a username. A single token can be assigned to multiple users, and a single user can hold multiple tokens.
Removing a User from a Token
Open the token details, locate the user under the Users section, click the Delete icon, and confirm with Delete User.
Viewing Tokens and Users
The dashboard has two tabs:
Tokens — lists all provisioned tokens with status, assigned user count, and edit/delete options
Users — lists users who have tokens assigned, with last active date and the option to remove a user from all tokens
Modifying a Token
Click Edit next to a token to update its counter or seed value. Click Update Token to save.
Resynchronizing Tokens
Tokens can fall out of sync when the hardware counter is ahead of the server's counter. The server can correct drift of up to 50 counter steps. If drift exceeds this, manually reset the counter in AdminX before retrying.
To resync, click Edit on the token, click Re-sync Token, generate three sequential passcodes from the device, enter them in the Re-sync Token window, and click Update.
First-Time Token Sync
For tokens that have never been used, 1Kosmos prompts users to complete a one-time sync during their first login. On the Enter your verification code screen, the user clicks First login with token? Continue to sync token, enters three consecutive passcodes, and clicks Sync Token & Login.
Configure the sync window range (1–500,000) under Authentication > Multi-Factor Authentication > Hardware Token Sync Window.
Event Logs — E_TOKEN_MODIFIED (activity: authentication) and E_OTP_VERIFIED (contains hash of the third OTP) share the same requestId during a sync.
Authenticating with a Hardware Token
On the login screen, select Password & OTP, enter the password, then select Hardware Token, generate a passcode from the device, and enter it.
Exporting Token Data
Click Export Data on either the Tokens or Users tab, enter an email address, and click Generate. The report is delivered by email when ready.
Event Logs
The following events are triggered by hardware token activity:
E_OTP_VERIFIEDE_LOGIN_SUCCEEDEDE_LOGIN_FAILEDE_TOKEN_LIST_EXPORTEDE_TOKEN_ASSIGNMENT_EXPORTEDE_TOKEN_ADDEDE_TOKEN_MODIFIEDE_TOKEN_ASSIGNEDE_TOKEN_UNASSIGNEDE_TOKEN_DELETED
Last updated
Was this helpful?