• PhenixID Server installed.
• Yubikey hardware tokens, key import file for the tokens and "YubiKey Personalization Tool" (if reprogramming of the keys is neccessary).
• Prepare the system for hardware token import, using MFA Admin or Self Service scenarios.
• Run the scenario for "Username, Password & Token generated OTP" or "Username & Token generated OTP" depending on your authentication needs.

This document will describe the steps to import Yubikey hardware tokens into PhenixID Server and then add configuration to use those tokens as the second factor for the login.

We will make changes to the configuration file phenix-store.json, so please make sure to have a backup  of this file.

The hardware token import module will automatically be installed and activated when hardware tokens are enabled. There are two ways to enable  hardware tokens:

1. Enable hardware tokens from the application "MFA Admin"
2. Enable hardware tokens from the application "Self Service"

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

When the import module is enabled, we can go to the next step below and import the tokens.

Yubikey tokens can be programmed in different ways, PhenixID Server supports tokens with OATH mode.

Normally there will be an import file delivered from the vendor, containing the data for the tokens (also called a seed file).

If no such file has been delivered, tokens can be programmed using "YubiKey Personalization Tool" from Yubico.

Note: The identifier must start with "ubnu" (ubnu12345678) for enrollment to work.

The  import file format must be one of the following:

• 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. 
• Semicolon separated file

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

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.

Importing Yubikey tokens using CSV

For scenarios where token file format does not comply with the PSKC 1.0  format, it is possible to create a import file using CSV format.

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 .yubikey

The syntax must match the following:

id,serial,counter,key,password,timestamp

where id, password and timestamp are not used.

Example:

ubnu12345678,ubnu12345678,0,05492f4e3555b180890eabbd061a54938016024f,0,0
ubnu87654321,ubnu87654321,0,05492f4e3555b180890eabbd061a54938016024f,0,0

After successful import the tokens will be visible in both the Configuration portal, on the Reports tab and MFA Admin, on the Hardware Token Admin tab:

We will now add support for Yubikey to the configured Scenarios used for tokens (Username, Password & Token generated OTP or Username & Token generated OTP).

In the Configuration portal, go to the tab Scenarios and then RADIUS. Click on the scenario that should use Yubikey tokens.
Go to the tab "Execution flow" and click on "Verify token otp"/"Find user, verify token otp". On the TokenValidationValve, click on Other and enable "Try Yubikey". Also, set the otp length and then save the configuration.

Note: otp_length must match the length of the provided otp from the yubikey tokens, so PhenixID Server will know the number of characters that will represent the actual otp (the other characters being the identity).

Configuration should now look similar to this:

Enrollment of the Yubikey tokens can be done using MFA Admin or Self Service. So at least one of these applications needs to be configured. More information about this can be found on PhenixID documentation page:
http://document.phenixid.net/