Hardware Tokens – Import and Manage OATH Authentication Tokens

Overview

The Hardware Tokens page manages OATH-compliant hardware tokens used for on-premises multi-factor authentication. Tokens are imported from PSKC (Portable Symmetric Key Container) files provided by token manufacturers, then assigned to individual users. The page supports the complete token lifecycle: import, assignment, verification, state management, resynchronization, and deletion.

MideyeServer supports both TOTP (Time-based, RFC 6238) and HOTP (Counter-based, RFC 4226) hardware tokens with SHA-1, SHA-256, and SHA-512 hash algorithms.

Access & Permissions

Required Role: ROOT, SUPER_ADMIN, or ADMIN (for all operations)

Navigation: Home → Users & Tokens → Hardware Tokens

Role	View	Import / Assign / Manage	Delete
ROOT	✅	✅	✅
SUPER_ADMIN	✅	✅	✅
ADMIN	✅	✅	✅
OPERATOR	❌	❌	❌

Features & Configuration

Data Grid Columns

Displays only hardware tokens (software tokens are filtered out). Default sort: assigned user ascending.

Column	Description	Hidden by Default
Assigned To	Username of the assigned user (clickable link to user edit page). Empty if unassigned	No
Serial Number	Unique hardware identifier (always visible, not hideable)	No
State	Token revocation state (translated label)	No
Token Type	TOTP or HOTP	No
Last Used	Timestamp of last successful authentication	No
Manufacturer	Token manufacturer name	Yes
Action	Operations menu (Verify, Change State, Resynchronize, Delete)	No

Token States

State	Description
VALID	Token is active and can be used for authentication
REVOKED_TOKEN_LOST	Token has been reported lost
REVOKED_TOKEN_BROKEN	Token is physically damaged
REVOKED_TOKEN_OTHER	Token revoked for another reason

Token Types

Type	Standard	Description
TOTP	RFC 6238	Time-based OTP; codes change every time period (default 30 seconds)
HOTP	RFC 4226	Counter-based OTP; codes change with each button press

---

Import PSKC

Import hardware tokens from manufacturer-provided PSKC (Portable Symmetric Key Container) files.

Steps:

1. Click Import in the actions menu.
2. Select the PSKC file using the file browser.
3. Optionally enter the Transport Secret (decryption passphrase) if the PSKC file is encrypted.
4. Click Import.

Results:

• Success: Displays the count of imported tokens.
• Failure: Displays the error message (e.g., invalid file format, wrong passphrase).

Field	Type	Required	Description
PSKC File	File upload	Yes	Token provisioning file from the manufacturer
Transport Secret	Text	No	Decryption passphrase for encrypted PSKC files

---

Token Operations

Verify OTP

Test whether a one-time password is valid for a specific token.

Field	Type	Required	Description
OTP	Text	Yes	The one-time password to verify
Resynchronize	Checkbox	No	When checked, allows extended look-ahead window for out-of-sync tokens

Results:

• ✅ Valid: OTP matches the expected value.
• ⚠️ Invalid: OTP does not match.

Change Token State

Change the revocation state of a token.

Steps:

1. Click the operations menu for the target token.
2. Select Change Token Status.
3. Select the new state from the radio button options (VALID, REVOKED_TOKEN_LOST, REVOKED_TOKEN_BROKEN, REVOKED_TOKEN_OTHER).
4. Click Save.

Note

Revoking a token prevents it from being used for authentication. Set the state back to VALID to reactivate a previously revoked token.

Resynchronize Token

Used when a hardware token’s internal counter has drifted out of sync with the server. This is particularly relevant for HOTP tokens where button presses without authentication cause counter drift.

Steps:

1. Click the operations menu and select Resynchronize.
2. Generate two consecutive OTPs from the hardware token.
3. Enter both OTPs in the OTP 1 and OTP 2 fields.
4. Verify the OATH Counter value (pre-filled from the token’s current state).
5. Click Resynchronize.

Field	Type	Required	Default	Description
OTP 1	Text	Yes	—	First consecutive OTP from the token
OTP 2	Text	Yes	—	Second consecutive OTP from the token
OATH Counter	Number	Yes	Current counter	Token’s expected counter position

Delete Token

Permanently removes the token from MideyeServer.

Steps:

1. Click the operations menu and select Delete.
2. Confirm the deletion in the dialog (shows the serial number).

Caution

Deleting a token also unassigns it from any user. This operation cannot be undone — the token must be re-imported from the PSKC file to restore it.

Common Use Cases

Deploying New Hardware Tokens

1. Obtain the PSKC file from the token manufacturer.
2. Click Import and select the PSKC file.
3. Enter the transport secret if the file is encrypted.
4. After import, navigate to each user on the Mideye Users page.
5. Go to the Tokens tab and click Assign to link tokens to users.

Handling a Lost Token

1. Find the token in the Hardware Tokens list.
2. Open the operations menu and select Change Token Status.
3. Set the state to REVOKED_TOKEN_LOST.
4. Issue a replacement token to the user.
5. Assign the new token to the user on the Mideye Users page.

Resynchronizing an Out-of-Sync HOTP Token

1. The user reports that their token codes are rejected.
2. Find the token and select Resynchronize.
3. Ask the user to press the token button twice and read both codes.
4. Enter the two OTPs and submit.
5. If successful, the token is resynchronized and can be used normally.

Verifying Token Configuration After Import

1. Find the imported token.
2. Select Verify OTP from the operations menu.
3. Generate an OTP from the physical token.
4. Enter it in the verification dialog.
5. A valid result confirms the import was successful.

Troubleshooting

Issue	Possible Cause	Resolution
PSKC import fails	Invalid file format or wrong passphrase	Verify the file is a valid PSKC XML and the transport secret is correct
OTP verification always fails	Token out of sync or wrong token type	Try resynchronization; verify the token type (TOTP vs HOTP) matches the import
Token not appearing after import	Filter showing wrong tokens	Ensure the list shows hardware tokens (software tokens are filtered out)
Cannot assign token to user	Token already assigned	Unassign the token from its current user first
HOTP token drifting frequently	User pressing button without authenticating	Educate users; consider switching to TOTP tokens for less drift

Related Pages

• Mideye Users — Assign tokens to individual users via the Tokens tab
• Mideye User Settings — Configure password policies (complementary to token-based auth)
• RADIUS Clients — Configure TOKEN auth type on RADIUS clients