Description
This article describes how to configure and import YubiKeys to FortiAuthenticator, for two-factor authentication.
Note:
This process applies exclusively to importing YubiKey models that support the OATH-HOTP function (HMAC-based OTP token code generator, analogous to FortiToken 200 series and FortiToken mobile), to be used for this purpose.
For FIDO2 functionality, this article is not applicable. FIDO2 keys are not pre-imported, they are assigned at the moment of self-registration by user, or when an administrator manually assigns one to a user.
Useful links:
External
YubiKey Personalization tool (required to configure YubiKeys): https://www.yubico.com/products/services-software/download/yubikey-personalization-tools/
Solution
- Reprogram the YubiKey to generate HOTP codes Open the YubiKey Personalization Tool.
In the Settings tab, ensure that Logging has enabled output and “traditional” format is set.
In the OATH-HOTP tab, choose the advanced configuration version. Select which slot to configure. The slots differ in how they are triggered:
Slot 1 - triggered after a short press of the button
Slot 2 - triggered after a three-second press of the button
Configure these options to ensure compatibility with FortiAuthenticator:
- OATH Token Identifier: 'OMP + TT Modhex, rest numeric' Set the first two fields to 'ub', 'nu', then select 'Generate MUI' to generate a random identifier for the token
- HOTP Length: Both options are compatible with FortiAuthenticator (controls the length of the token codes being generated)
- Moving Factor Seed: Any of the three options is fine (Fixed zero | Fixed | Randomize, sets the initial counter value for generating token codes) for FortiAuthenticator
- Secret Key: select the 'generate' button to get a new key.
Once configuration is done, click "Write Configuration". It will be required to choose a location for the log file, unless this was already done before. Continue with configuring other YubiKeys in the same manner (make sure they have unique Identifier and secret keys). The resulting csv file with configurations for all reprogrammed YubiKeys will be used for importing them into the FortiAuthenticator.
- Enable YubiKey support in FortiAuthenticator. Log into the FortiAuthenticator GUI as usual, then open the following address: https://<fac-fqdn-or-ip>/debug/thirdparty and Toggle the switch button on and save with 'OK'.
- Import the YubiKey CSV file
Go to Authentication -> User Management -> FortiTokens -> Import
Select file type "Yubikey file" and then choose the CSV file from step 1.
Note 1: If the error "Invalid Yubikey file, header is missing" is shown, verify that correct file is selected.
Note 2: If yes, also make sure that the first line of the file says "LOGGING START" (this is the expected header).
Once done, a message that the tokens were successfully imported will be shown.
On this screen it's possible to edit the tokens and synchronize them.
- Assigning YubiKey tokens to users
Go to Authentication -> User Management -> Local Users | Remote Users
Edit a user object. As with regular FortiTokens, first enable Token-based authentication, then select “FortiToken” as delivery. Choose one of the available YubiKey tokens from the drop-down menu on the right hand side. Save the change with 'OK'.
- (OPTIONAL) HOTP token settings configuration. Consider tweaking the HOTP token windows when using YubiKeys. Go to Authentication -> User Account Policies -> Tokens
The relevant options are:
- HOTP authentication window size - Sets how many tokens are acceptable for a successful authentication, including the next expected token.
A reasonable value should be set.
Example: If authentication window is only "1", a single accidental press of the YubiKey button when not logging in will get the token out of sync with FortiAuthenticator and will prevent authentication until synchronized. - HOTP sync window size - Similar to authentication window size, but in this case this controls how many of the next expected token codes are acceptable when attempting to login to the self-service portal to synchronize the token.
The resulting behavior is as follows:
- User enters a token code within the authentication window: authentication accepted
- User enters a token code outside of the authentication window, but still within the sync window: Authentication (for example RADIUS) will fail, but if the user attempts to log directly into the self-service portal on FortiAuthenticator, they will be allowed to synchronize the Yubikey.
- User enters a token code outside the sync window: Both authentication and self-service synchronization will fail. Administrator intervention and manual synchronization required.
(Go to Authentication -> User Management -> FortiTokens. Edit the affected YubiKey. Click 'Synchronize')
Verification:
If self-service portal is configured, log out and then attempt to log back in as the user with YubiKey assigned.
It's also possible to attempt to authenticate over RADIUS with this user account. If the RADIUS client profile is set to request two factor token codes, log in with a code generated by the YubiKey.
Example token code generated:
ubnu4949510814552744
This code consists of two parts: The YubiKey identifier (“ubnu49495108”) + the actual code that changes for every use (“14552744”; six or eight digits, depending on the configuration from step 1.
How to match a YubiKey to its serial number in FortiAuthenticator?:
If it is not sure which serial number matches to a certain YubiKey, use the following procedure to identify it:
- Press the YubiKey button to generate a code. Take the YubiKey identifier part (described above) of the code and remove the initial “ubnu”. The remainder is the hexadecimal representation of its unique ID (eight digits).
- Convert this hex number to modhex. Use the YubiKey Personalization Tool for this (Go to Tools tab -> Number Converter).
- Append this modhex number to “ub:ubnu”. The result is the serial number of the YubiKey as shown in FortiAuthenticator.
