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