Import hardware tokens, version 4.1 and later

This article is written for PAS version 4.1 and later.
In version 4.1 import of hardware tokens have been moved from the tokensin to Test Tool.

When you purchase OATH tokens, they are delivered with a key file (also called a seed file) that contains all OATH keys for the tokens. This OATH key file must be imported to the OTP Server database used to be able to assign the OATH key to specific users.

The OATH key file format must be one of the following:

  • Semicolon separated file.
  • PSKC format (RFC 6030) 
    • 

NOTE: PSKC RFC 6030 version 1.0 is the official version. RFC 6030 versions 1.1 and 1.2 are drafts and are not supported. 
    • NOTE: Token encryption with Pre-Shared-Key is supported. Other encryption methods are not supported.

Note:

Before you begin start by taking a full backup of the system

Enable hardware tokens in MFA Admin/Self Service

Hardware tokens can be enabled on both MFA Admin and  Self Service.
In MFA Admin, administrators can view and Assign/Unassign tokens.
If hardware tokens are enabled in Self Service, users will have the possibility to register a hardware token themselves. As long as the token has been imported into the database.

Enabling hardware tokens can be done either when using the guide to activate the application for the first time, or from the edit view, see example for "MFA Admin" below:

Installing the import module

Importing hardware tokens

From PAS version 4.1, Test Tool is used for the import of hardware tokens.
This tool is found in the /bin folder.
Start it and click on the tab "OATH Token Import":

Set the "JDBC URL" according to database used. Information can be found on the MPL module in boot.json.
In the example above, internal database is used.

When doing the import, enter the PAS encryption key for the database and then point to the file containing the tokens that should be imported.

Example when using an encrypted PSKC file.

Using PSKC file for import

When using PSKC, the file must have the extension .xml

Information regarding encrypted tokens in PSKC file

Many token vendors will send the PSKC file with encrypted data.

This means that we need a corresponding key file to decrypt the data, when doing the import.

The key file must be placed in the same directory as the PSKC file.

Make sure that the key file name is matched in the PSKC file.

Key file must contain only the key itself, not any additional text.

Example extracted from PSKC file:

<EncryptionKey>
<ds:KeyName>Pre-shared-key</ds:KeyName>
</EncryptionKey>

In this example the key file name MUST be "Pre-shared-key".

If this file is not in place or if the name does not match, the  import will fail and a message will be written to log, indicating that  the file cannot be found.

NOTE:

Other encrytion methods than Pre-shared-key, such as PassPhrase are not supported.

Using CSV as import file

For scenarios where token file format not complies with the PSKC 1.0 format it is possible to create a import file using CSV format. The value of the key has to be HEX encoded.

Note: The file must have the extension .csv

The following syntax formats is supported:

  • For HOTP: 
    • HOTP;serial;key;counter 
    • serial;key;counter
    • serial;key;counter ;otplength
    • serial;key;counter ;assigned_username
    • serial;key;counter ;otplength ;assigned_username
  • For TOTP: 
    • TOTP;serial;SHA;key;epoch;timeinterval;otplength
    • TOTP;serial;SHA;key;epoch;timeinterval;otplength ;assigned_username

 Example:

HOTP;TA129298222;94CC4CD6CDDF074E71EBC1C2FBAFE0F73D9162CF;6566
129298222;94CC4CD6CDDF074E71EBC1C2FBAFE0F73D9162CF;0;6;janderson
TOTP;TA129298329;1;A3A18EB666CA79E98A34C509DF0A853FC4A0E125;0;30;6
Click to copy

Importing Yubikey OATH tokens

Note: The file must have the extension .yubikey

The syntax then must match:

id,serial,counter,key,password,timestamp,

where id, password and timestamp are not used.

Regarding OTP length

When importing hardware tokens, including yubikeys, where otp length is not set in the csv/yubikey file, an additional configuration parameter (otp_length) can be set on the hardware token import module. This value defaults to 6 but sometimes the hardware token has 8 as otp length. This can be changed under the ADVANCED tab, as seen below.

NOTE: If using yubikey with otp length set to 8, this also needs to be reflected in MFA Admin.
Set the parameter "token_digits", on the otpadmin module, to 8.
Like this example: