Written by Simon Moffat
Note
Instructions for configuring Yubikey OTP with Access Management are available in our Docs and Knowledge base for all versions of Access Management (relevant URLs are provided below for further reference).
This article includes screenshots reflecting legacy versions of Access Management UI but the same principles apply to setting up Yubikey OTP in later versions.
Yubico is a manufacturer of multi-factor authentication devices, that typically are just USB dongles. They can provide a range of different MFA options including traditional static password linking, one-time-password generation and integration using FIDO (Fast Identity Online) Universal 2nd Factor (U2F).
I want to quickly show the route of integrating your Yubico Yubikey with ForgeRock Access Management. ForgeRock and Yubico have had integrations for the last 6 years, but I thought it was good to have a simple update on integration using the OATH compliant OTP.
First of all you need a Yubikey. I’m using a Yubikey Nano, which couldn’t be any smaller if it tried. Just make sure you don’t lose it… The Yubikey needs configuring first of all to generate one time passwords. This is done using the Yubico personalisation tool. This is a simple util that works on Mac, Windows and Linux. Download the tool from Yubico and install. Setting up the Yubikey for OTP generation is a 3 min job. There’s even a nice Video on how to do it, if you can’t be bothered RTFM.
set up process, basically generates a secret, that is bound to the Yubikey along with some config. If you want to use your own secret, just fill in the field…but don’t forget it :-)
Next step is to setup ForgeRock AM (aka OpenAM), to use the Yubikey during login.
Access Management has shipped with an OATH compliant authentication module for years. Even since the Sun OpenSSO days. This module works with any Open Authentication compliant device.
Create a new module instance and add in the fields where you will store the secret and counter against the users profile. For quickness (and laziness) I just used employeeNumber and telephoneNumber as they are already shipped in the profile schema and weren’t being used. In the “real world” you would just add two specific attributes to the profile schema.
Make sure you then copy the secret that the Yubikey personalisation tool created, into the user record within the employeeNumber field…
Next, just add the module to a chain, that contains your data store module first – the data store isn’t essential, but you do need a way to identify the user first, in order to look up their OTP seed in the profile store, so user name and password authentication seems the quickest – albeit you could just use persistent cookie if the user had authenticated previously, or maybe even just a username module.
Done. Next, to use your new authentication service, just augment the authentication URL with the name of the service – in this case yubikeyOTPService. Eg:
…/openam/XUI/#login/&authIndexType=service&authIndexValue=yubikeyOTPService
This first asks me for my username and password…
…then my OTP.
At this point, I just add my Yubikey Nano into my USB drive, then touch it for 3 seconds, to auto generate the 6 digit OTP and log me in. Note the 3 seconds bit is important. Most Yubikeys have 2 configuration slots and the 1 slot is often configured for the Yubico Cloud Service, and is activated if you touch the key for only 1 second. To activate the second configuration and in our case the OTP, just hold a little longer…
Helpful Links
Yubico
ForgeRock Marketplace
AM Docs
Identity Cloud Docs
SDK Docs
Knowledge Base
https://backstage.forgerock.com/knowledge/kb/article/a86891970