80 lines
3.0 KiB
ReStructuredText
80 lines
3.0 KiB
ReStructuredText
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 :doc:`FIDO2 <webauthn2f>`.
|
|
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 <http://search.cpan.org/~massyn/Auth-Yubikey_WebClient/>`__
|
|
package.
|
|
|
|
You have to retrieve a client ID and a secret key from Yubico. See
|
|
`Yubico API <https://upgrade.yubico.com/getapikey/>`__ 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
|
|
:doc:`exported variables<exportedvars>`):
|
|
|
|
.. code::
|
|
|
|
[{"name" : "MyYubikey" , "type" : "UBK" , "_secret" : "########" , "epoch":"1524078936"}, ...]
|
|
|
|
Enrollment
|
|
----------
|
|
|
|
If you have enabled self registration, users can register their U2F keys
|
|
using https://portal/2fregisters
|
|
|
|
.. |deprecated| image:: /documentation/deprecated.png
|