Yubico Authentication

Christopher Dakin


LogonBox supports user authentication via a YubiKey fob from Yubico. A YubiKey is a small keyfob that plugs into a USB port, a user touches a conductive pad on the YubiKey after which the key types in a unique one time password into the attached computer. This article explains how to configure your LogonBox to use this method of authentication.


1. Configuring the Authentication Scheme

It is important to note that you can apply different authentication flows for six different types of logon: User Logon, Password Reset, Client, Account Unlock, SSO and Admin Logon.

Each of these can have their own default authentication flow configured, but for this article we shall alter Password Reset.

Navigate to Authentication->Schemes->Password Reset. Note that by default this is configured with a yellow Username module and a green Security Questions one.

First, note that Yubico is available both as a blue module and as a green one.


We can use a YubiKey as part of a multi-factor login with some other authentication, hence the option to use the green module. However, part of a YubiKey's unique one time code contains some static characters that you can link to a username. Hence, a YubiKey can be used to establish the identity of the user as well as present a password - so in this case we could opt to use the blue module and not have to even ask for a username.

Let’s use the blue module for this example. Remove the existing Username and Security Questions modules by clicking the trash icon inside the modules.


Noq add the Yubico module by clicking the plus icon next to blue Yubico to add it into the authentication flow and click Save at the bottom.


2. Yubico options

Now you must get a Yubico Client ID and Secret key. Click on the edit icon inside the Yubico module to see where you need to enter these values.

In this edit page you will see a link that will take you to Yubico's API key page here.


Click on the link to Yubico. Type in your email address as requested and agree to the terms and conditions.

Insert your YubiKey into a spare USB port.

Now click in the YubiKey OTP field and touch your YubiKey. The Key will type in a unique code and submit the page for you.


You will now be presented with your Client ID and Secret Key, make a note of these.


Now go back to your LogonBox's Authentication scheme again and Edit the Yubico module again.

Type in your Client ID and Secret Key and click Apply.


3. Linking YubiKeys with users

Your LogonBox is now ready to work with YubiKeys, but first you must link any YubiKeys with the people who will be using them, which can only be done as the admin account.

You must have access to the YubiKey that is to be linked and it must be plugged into a USB port.

Navigate to Access Control->Users and next to the user you want to link this key to, click the green gears icon, then select Allocate YubiKey.


Give the Yubikey a Name (this can be anything you wish, it is just for your reference). In this example we'll just use the user's username as the name.

Click in the YubiKey field and touch the YubiKey, which will type in its own one time password. Click Create to complete the process.


This user is now set up to authenticate with their YubiKey. A user can have more than one Key linked to their account, just continue allocating new keys as you require them (for example if a user has one key at work and another at home). 

Click on the green gears icon again and select Manage Yubikeys to see which keys a user has linked to their account. You can delete a key associated with this account by clicking the delete trash icon here.


Continue setting up the rest of your users with their keys.


4. Testing

As we have configured this scheme for Password Reset, to test this click on the Reset Password link on the main LogonBox portal.


The user is prompted for their YubiKey. They touch their YubiKey to activate it, which will type in the one time password for them and press enter to go to the next stage.


The authentication succeeds and the user is now prompted to change their password.