Table of Contents

Integrating YubiKey with PhenixID Authentication Services (PAS)

Overview

YubiKey, developed by Yubico, is a hardware token that enhances security by generating one-time passwords (OTPs) compliant with OATH standards, including TOTP and HOTP. PhenixID Multi-Factor Authentication (MFA) supports YubiKey integration, allowing users to authenticate by tapping their YubiKey device, which generates and submits an OTP validated by PAS.

Preparing YubiKey Tokens for PAS

To integrate YubiKey with PAS, the tokens must be configured in OATH-HOTP mode. This process involves reprogramming the YubiKeys using the YubiKey Personalization Tool:

  • Install the YubiKey Personalization Tool:

    • Download and install the tool from Yubico's official website.

  • Go to the Settings Tab:

    • Navigate to the Settings tab in the YubiKey Personalization Tool.
    • Ensure the setting Log configuration output has the value Traditional format for proper output handling.

  • Configure YubiKey in OATH-HOTP Mode:

    • Launch the YubiKey Personalization Tool.
    • Navigate to the 'OATH-HOTP' tab.
    • Select the desired configuration slot (e.g., Slot 1).
    • Click 'Generate MUI' and set the 'OMP' and 'TT' fields to 'ub' and 'nu,' respectively.
    • Click 'Write Configuration' to program the YubiKey.
    • Save the output file (e.g., 'my-tokens.csv') for the next step.

Importing YubiKey Tokens into PAS

After preparing the YubiKey tokens, import them into PAS:

  • Convert the Output File:

    • Use the 'Yubico Formatter' tool included in PAS to convert the CSV file:
      • Launch the Test Tool (bin\testtool.bat).
      • Go to the 'Yubico Formatter' tab.
      • Select the YubiKey log file (e.g., 'my-tokens.csv').
      • Click 'Write file' to generate a '.yubico' file (e.g., 'my-tokens.yubico').

  • Import the Tokens:

Configuring PAS for YubiKey Authentication

To enable YubiKey authentication in PAS:

  • Enable Hardware Tokens:

    • Access the Configuration Portal.
    • Navigate to the 'MFA Admin' or 'Self Service' application settings.
    • Enable hardware tokens in the application's configuration.
    • This is described here: configure pas for hardware tokens

  • Configure Authentication Scenarios:

    • Set up authentication scenarios such as 'Username, Password & Token generated OTP' or 'Username & Token generated OTP' based on your requirements.
    • Ensure these scenarios are configured to utilize the imported YubiKey tokens.

To check for yubikey on the TokenValidationValve enable check_yubikey:

{
        "name": "TokenValidationValve",
        "config": { 
              "otp_length":"6",
              "hotp_lookahead":"50",
              "totp_max_drift": "10",
              "provided_otp_param_name":"{{request.otp}}",
              "userid_param_name": "{{request.username}",
          "try_legacy_token": "false",
          "try_auto_enroll": "false",
          "check_yubikey": "true"
        }
}

Additional Features and Considerations

PhenixID MFA offers additional functionalities to enhance YubiKey integration:

  • Auto-Enrollment:

    • PAS can automatically enroll a YubiKey to a user upon first login if the device is unassigned.

  • Self-Service Enrollment:

    • Users can enroll their YubiKeys through the PhenixID Self Service portal.

  • Delegated Administration:

    • Administrators can manage YubiKey assignments using the PhenixID MFA Administration portal.

  • Reporting:

    • PhenixID Reporting provides statistics on YubiKey authentication attempts, aiding in monitoring and analysis.

By following this guide, you can effectively integrate YubiKey hardware tokens with PhenixID Authentication Services to enhance your organization's security posture.

One Time Password Hardware Tokens MFA Use Case: Integrate with external systems