Yubico OTP Second Factor

Yubico OTP is a type of One-Time-Password authentication based on a keyboard-emulating hardware device (Yubikey). OTPs are validated against an external server, either on the cloud or on premices.

deprecated Almost all Yubikeys sold by Yubico now support FIDO2. You are encouraged to use this type of second factor instead, since it is compatible with a much broader range of devices, and also more secure.

Prerequisites and dependencies

You must install Auth::Yubikey_WebClient package.

You have to retrieve a client ID and a secret key from Yubico. See Yubico API page.

Configuration

In the manager (second factors), you just have to enable it:

  • Activation: set it to “on”

  • Self registration: set it to “on” if users are authorized to register their keys

  • Allow users to remove Yubikey: If enabled, users can unregister Yubikey device.

  • API client ID: given by Yubico or another service

  • API secret key: given by Yubico or another service

  • Nonce (optional): if any

  • Service URL: service URL (leave it blank to use Yubico cloud services)

  • OTP public ID part size: leave it to default (12) unless you know what you are doing

  • Get Yubikey ID from session attribute: if non-empty, the Yubikey ID will be read from this session attribute. This allows external provisionning of Yubikeys.

  • Authentication level: you can overwrite here auth level for Yubikey registered users. Leave it blank keeps auth level provided by first authentication module (default: 2 for user/password based modules). It is recommended to set an higher value here if you want to give access to some apps only for enrolled users

  • Label (Optional): label that should be displayed to the user on the choice screen

  • Logo (Optional): logo file (in static/<skin> directory)

  • Lifetime (Optional): Unlimited by default. Set a Time To Live in seconds. TTL is checked at each login process if set. If TTL is expired, relative Yubikey is removed.

Attention

If you want to use a custom rule for “activation” and want to keep self-registration, you must include this in your rule: has2f('UBK'), else Yubico OTP will be required even if users are not registered. This is automatically done when “activation” is simply set to “on”.

Provisioning

If you don’t want to use self-registration, set public part of user’s yubikey in Second Factor Devices array (JSON) in your user-database. Then map it to the _2fDevices attribute (see exported variables):

[{"name" : "MyYubikey" , "type" : "UBK" , "_secret" : "########" , "epoch":"1524078936"}, ...]

Enrollment

If you have enabled self registration, users can register their U2F keys using https://portal/2fregisters