Import hardware tokens
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:
Before you begin start by taking a full backup of the system
Prepare the system
Start by verifying that the two directories used for token import are present (otherwise create them):
- <phenixid_server_root>/tokensin
- <phenixid_server_root>/tokensout
Installing the import module
The first option is to run the OTP administration guide to configure PhenixID for different one-time password methods, including hardware tokens.
This will install the necessary modules.
Manually install the import module
The second option is to manually install the hardware token import module.
Open the store.json file with texteditor.
Locate the node id/hostname in the file onto witch you intend to install the module. Install the module by adding:
{
"module" : "com.phenixidentity~phenix-hwtoken-mgr~1.4.0(change according to version)",
"enabled" : true,
"config" : {
"tokens.assignable.file" : "<path_to_phenixid_server_root>/config/tokenlist.json",
"tokens.import.directory" : "<path_to_phenixid_server_root>/tokensin/",
"tokens.backup.directory" : "<path_to_phenixid_server_root>/tokensout/",
"encryption.key" : "<my_supersecret_ password>",
"otp_length" : "<otp_length>"
}
}
Example for Windows: "tokens.import.directory" : "C:\\Program Files\\PhenixID\\Server\\tokensin\\"
Save the file. If system is not running start it.
Note: "otp_length" : "<otp_length>" is used for Yubikey and HOTP CSV seed files where the otp length is not specified.
Self Service enrollment, OTP length other than 6
By default the system assumes an otp length of 6.
If tokens have another length than default, the parameter:
"otp_length" : "<length>"
must be configured on the Prism OTPEnrollment module (under NODES).
Example:
"userLookUpPipe" : "enrollmentuserLookUpPipe",
"userUpdatePipe" : "enrollmentuserUpdatePipe",
"userNameAttribute" : "sAMAccountName",
"otp_length" : "8",
"displayNameAttribute" : "cn",Importing tokens from PSKC file
Tokens are automatically imported. A token can only be imported once.
Place the import file in the <path_to_phenixid_server_root>/tokensin/ directory. Once processed it will be moved to <path_to_phenixid_server_root>/tokensout/.
Note: The file must have the extension .xml
After import, verify that the tokenlist.json/phenix-assignable-tokens.json contains the tokens.
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.
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.
Note: The file must have the extension .csv
The syntax then must match the following:
- For HOTP: HOTP;serial;key;counter ( or serial;key;counter )
- For TOTP: TOTP;serial;SHA;key;epoch;timeinterval;otplength
Importing Yubikey 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.