YubiKey Authenticator

    Note: YubiKey Authenticator is an Advanced Authenticator available as part of the Professional edition of ADSelfService Plus.

    ADSelfService Plus supports the YubiKey 5 series, YubiKey 5 FIPS series, and YubiKey 5 CSPN series, using the Yubico OTP protocol for authentication. When YubiKey Authenticator is enabled, users authenticate first with their AD domain credentials, then with the one-time passcode (OTP) generated by their YubiKey device.

    How it works

    When a user reaches the YubiKey authentication step, they are prompted to insert their YubiKey and tap it to generate an OTP. ADSelfService Plus sends the OTP to the Yubico validation servers for verification. If the OTP is valid, the user is authenticated and can proceed with their self-service operation.

    Multiple YubiKey Authenticator configurations can be maintained for different users based on their domain, group, or OU membership, or a single configuration can be applied to all users.

    Prerequisites

    1. Firewall configuration

    The following outbound connections must be permitted through the firewall for OTP validation to reach the Yubico servers:

    • https://api.yubico.com/wsapi/2.0/verify
    • https://api2.yubico.com/wsapi/2.0/verify
    • https://api3.yubico.com/wsapi/2.0/verify
    • https://api4.yubico.com/wsapi/2.0/verify
    • https://api5.yubico.com/wsapi/2.0/verify

    2. Obtaining the Client ID and Secret Key

    1. Go to https://upgrade.yubico.com/getapikey.
    2. Enter your email address.
    3. Connect a YubiKey to your workstation or server and tap it to enter the YubiKey OTP.
    4. Select I've read and accepted the Terms and Conditions and click Get API Key.
    5. Copy the Client ID and Secret Key displayed. You will need both during configuration.

    Configuration instructions

    1. Log in to the ADSelfService Plus portal with administrator credentials.
    2. Go to Configuration > Self-Service > Multi-factor Authentication > Authenticators Setup.
    3. From the Choose the Policy drop-down, select the policy you want to configure.
    4. Click the YubiKey Authenticator section to expand it.
    5. Enter the Client ID and Secret Key obtained in the prerequisites.

      YubiKey Authenticator section expanded in the Multi-factor Authentication Authenticators Setup page in ADSelfService Plus, showing the Client ID and Secret Key fields

    6. Click Save.

      Confirmation message displayed in ADSelfService Plus after successfully saving the YubiKey Authenticator configuration

    Tips

    • Before enabling YubiKey Authenticator for a policy, confirm that all five Yubico validation URLs are reachable from the ADSelfService Plus server. A blocked outbound connection will cause all YubiKey OTP validations to fail silently — users will receive an authentication error with no clear indication of the cause.
    • The Client ID and Secret Key are tied to the email address used during registration at upgrade.yubico.com. Keep a record of both values in a secure location — if lost, a new API key must be generated, which requires re-configuration in ADSelfService Plus.
    • Use per-policy configurations to apply YubiKey Authenticator only to user groups where physical hardware tokens are available. Applying it globally to users who have not been issued a YubiKey will lock them out of self-service operations.