- 1 Overview
- 2 Prerequisites
- 3 Configuring tokens
- 4 Administering Tokens
- 5 User Self Help for Synchronizing Tokens
- 6 Integrating with Tokens
- 7 Testing
- 8 Known Issues
- 9 Troubleshooting
Swivel supports the use of hardware tokens for authentication and can be used as "something you have" in Two Factor Authentication. The Swivel OATH HOTP Hardware Token and Swivel OATH TOTP Hardware Token provide a value that is a One Time Code (OTC) which can be used to authenticate a user, other compatible tokens may also be used. For other forms of authentication see Transports How To Guide.
- Each user can be assigned a single token.
- Each token can be assigned to a single user.
- A Swivel installation can use HOTP, TOTP and OCRA tokens
- The token can be a software token or a hardware token as in the picture below
Swivel 3.9.6 onwards
Swivel 3.10.1 onwards
OATH TOTP compatible Token such as the Swivel OATH TOTP Hardware Token
Swivel 3.10.2 onwards
OATH OCRA compatible Token such as the Swivel OATH OCRA Hardware Token
Each token has a serial number and an associated seed. The Serial number and seed are entered into the Swivel database and then associated with a single user. Hardware tokens usually have a serial number on the back of the token. The seed is usually sent separately from the token.
Tokens and PIN numbers
If the feature to allow a PIN to be is used with the Token is enabled, the OTC is entered first from the hardware token, then the PIN number.
For example for a token OTC of 111111 and a PIN of 0000, then enter 1111110000.
It is also possible to use a Token with an additional One Time Code ( PINless), if the PINless code is more than six digits to differentiate it from the Token code.
A new menu entry can be found on the left hand side of the Swivel Administration Console. This is where the tokens are added and then assigned to users.
On the Swivel Administration Console select OATH then OATH Tokens, enter the serial number and seed. Large numbers of tokens can be imported through a CSV (Comma Separated Values) file. The format for the CSV file is:
Serial,Seed Serial,Seed Serial,Seed
One per line, entries after the first two per line are ignored.
The seed format Swivel is expecting is in HEX, 40 Characters long is the standard. The OATH standard generates a numeric One Time Code.
Compatible tokens can be used with Swivel, for details on the Swivel token see Swivel OATH HOTP Hardware Token. Hardware tokens are supplied with a unique seed and serial number that is valid only for the specified hardware token.
Configuring users with tokens
Hardware and Software tokens can be used with Swivel using a compatible seed.
On the Swivel Administration Console select OATH then OATH Users, for the required user click on Assign token, then select the required token serial number. The user must be a member of a Swivel Group that contains the permission to allow tokens.
The following options may be configured for OATH.
Token Type: HOTP
OTP Length:, default 6, the Swivel OATH HOTP Hardware Token is a six digit token.
Error Window (Events):, default 5. If the difference between the number of button presses that the server has recorded and the actual number of button presses on the token is less than the error-windows, the authentication is allowed
Sync Windows (Events):, default 10. If the difference between the number of button presses that the server has recorded and the actual number of button presses on the token is greater than the error window but less than the Sync window, the authentication will fail but the server button-press count on the server is updated. This means if the user attempts to authenticate again, the next authentication will succeed.
Append PIN (if user has one) after OTP: , default No, Options Yes/No. If set to Yes the user must enter their PIN directly after the OTC generated by the token, without any decoration (i.e. “,”).
Tokens can be synchronized for use.
Either from the OATH Tokens or the OATH Users list click on Re-sync for the required token or user. Enter the value displayed by the token, and then enter the next value for that token (must be the next value).
User Self Help for Synchronizing Tokens
Users may synchronize tokens themselves through the User Portal.
Integrating with Tokens
Integration of login portals is usually straight forward with Tokens, although if TURing and Pinpad images are used, then these should not be automatically generated as a login will be expected using those methods.
Add a token and ensure that it can be used for authentication.
An Administrator or Helpdesk user can test a token by logging into the Swivel Administration console if they have OATH and Admin or Helpdesk permissions, and do not generate a TURing image, if a TURing image is generated, then it will expect that to be used for authentication for the length specified under Server/Jobs/Session Cleanup (default 2 minutes).
Swivel 3.9.6 and 3.9.7 Oath seeds are not moved when a Swivel database is migrated. Workaround: Upgrade to 3.10 or re-import seeds into new database
Swivel 3.9.6 using PIN and Token fails. Upgrade to Swivel 3.10 or later.
Check the Swivel logs.
Token is out of synchronization, re-synchronize as described above.
On the User Administration for the user click on Reset Password, and reset it, but leave the password fields blank.
Are you using PIN entry with the Token? When a PIN is used with the Token, the OTC is entered first from the hardware token, then the PIN number. For example for a token OTC of 111111 and a PIN of 0000, then enter 1111110000
Is the serial number correct for the token?, Was the seed entered automatically or manually? Try re-entering it
Unable to synchronize OATH Token
Note - This error appears on-screen if the OATH Token fails to synchronise. Namely, with Time based (TOTP) tokens, there may be a time drift on the Swivel Server. From the Command Line, run the command: date
Ensure that the time stamp is correct and it has not drifted over 5 minutes.
Servlet.service() for servlet SyncOathToken threw exception
Incorrect seed entered for token
Token autosynced for user gfield
This message is logged when the Sync Windows (Events) is matched and the token is resynced. The login fails but the next login will succeed.
AgentXML request failed, error: The XML request sent from the agent was malformed
This has been seen when using the User Portal with Swivel version 3.10. Upgrade the User Portal.
The seed used is incorrect or in the wrong format