Differences

This shows you the differences between two versions of the page.

Link to this comparison view

documentation:latest:yubikey2f [2019/06/09 11:51] (current)
Line 1: Line 1:
 +====== Yubikey Second Factor ======
  
 +A [[http://​www.yubico.com/​yubikey|Yubikey]] is a small material token manufactured by [[http://​www.yubico.com|Yubico]]. It sends an OTP, which is validated via Yubico server.
 +
 +===== Prerequisites and dependencies =====
 +
 +You must install [[http://​search.cpan.org/​~massyn/​Auth-Yubikey_WebClient/​|Auth::​Yubikey_WebClient]] package.
 +
 +You have to retrieve a client ID and a secret key from Yubico. See [[https://​upgrade.yubico.com/​getapikey/​|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
 +  * **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 to enrolled users**
 +  * **Client ID**: given by Yubico or another service
 +  * **API secret key**: given by Yubico or another service
 +  * **Nonce (optional)**:​ if any
 +  * **URL**: Url of service (leave blank to use Yubico cloud services)
 +  * **OTP public ID part size**: leave it to default (12) unless you know what you are doing
 +  * **Allow users to remove Yubikey**: If enabled, users can unregister Yubikey device.
 +  * **Lifetime**:​ 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.
 +
 +<note important>​If you want to use a custom rule for "​activation"​ and want to keep self-registration,​ you must include this in your rule: ''​$_2fDevices =~ /"​type":​\s*"​UBK"/​s'',​ else Yubikey will be required even if users are not registered. This is automatically done when "​activation"​ is simply set to "​on"​.</​note>​
 +
 +===== 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 [[exportedvars|exported variables]])//:​
 +<file json>
 +[{"​name"​ : "​MyYubikey"​ , "​type"​ : "​UBK"​ , "​_secret"​ : "########"​ , "​epoch":"​1524078936"​},​ ...]
 +</​file>​
 +
 +===== Enrollment =====
 +
 +If you have enabled self registration,​ users can register their U2F keys using https://​portal/​2fregisters