Setting Up YubiKey Authentication

(Version 7+)

This is a quick guide to setting up YubiKey Authenticator with Pleasant Password Server.

For background information on YubiKey Authentication Services: start here.

Before you begin, make sure you:

  • have a YubiKey USB device plugged in and within reach; and
  • install any YubiKey software that came with the device.
Note: Remember which of your YubiKey's two configuration slots you are using with Password Server - using the
wrong slot will cause errors.

Supported YubiKey Devices

  • YubiKey NFC, Neo (OTP, TOTP)
  • YubiKey 5, 4, Nano (OTP)
  • YubiKey 5C, 4C, Nano (OTP)

More info: Compare YubiKeys


  1. (Optional) Create a Policy: to use Two-Factor Authentication (2FA):
    • Navigate to "Users & Roles > Manage Policies".
    • Create a new policy and set the applicable fields and flags.
        Note: Making 2FA Required will prevent users subject to this policy from logging in unless their

        accounts have been individually configured to use at least one 2FA provider (eg. YubiKey).

        If you're setting up two factor for the first time and you've made 2FA Required, follow these
        instructions to the end to avoid locking out users.
        If you're already locked out, please Contact us!

    • Click Create.
    • You'll be returned to the "Manage Policies" page, where you'll see the policy you just created.
  2. Set policy: to use two factor authentication (YubiKey):
    • Click the name of the policy you just created, or that of another policy you want to change.
    • In the "Two Factor Policy" section you'll see a "Configurations" table; click [Configure] in the "YubiKey" row:
    • Click the "Enabled" checkbox (the others are optional; read the explanations for details). Your setup should resemble the following:
    • Navigate to the Yubico website to obtain a Client ID and API Key. You'll need to provide:
      • an email address; and
      • a one time password (get one by using your YubiKey device).
    • Enter your Client ID and API Key.
    • (Optional) If you are running your own YubiKey Authentication Server, click + Add Server and enter its URL.
    • Click Save.
  3. Configure user for YubiKey:
    • Navigate to "Users & Roles -> Manage Users" and click Edit in an existing user's "Actions" dropdown.
    • Set the "Policy" field appropriately, then click Save.
    • You'll be taken to the user's "Details" page. In the "Policy Information" section you'll see a "Two Factor Authentication" table; click [Configure] in the YubiKey row.
    • You'll be taken to the YubiKey page, which has a single entry field:
    • Select the text box and press the button on your YubiKey; you'll see text appear.
    • Click Save.
  4. Authenticate with YubiKey:
    • Try to log in as the user you configured 2FA for.
    • After you click Sign In, you'll see the following:
    • Select the text box and press the button on your YubiKey; you'll see text appear.
    • Click Sign In.
Choosing Your Two Factor Authenticator

Users with more than one 2FA Provider configured (whether directly or via their roles) will be prompted to chose one during login:

Two Factor Choices.PNG 

Tag page
You must login to post a comment.