# Universal 2nd Factor Authentication (U2F)

Universal 2nd Factor (U2F) is an open authentication standard that strengthens and simplifies two-factor authentication using specialized USB or NFC devices.

LLNG can propose to users to register their keys. When done, 2F registered users can not login without using their key.

Note that it's a second factor, not an authentication module. Users are authenticated by both login form and U2F form.

## Prerequisites and dependencies

This feature uses Crypt::U2F::Server::Simple that is only available on CPAN repository for now. Before compiling it, you must install Yubico's C library headers (called libu2f-server-dev on Debian).

An HTTPS portal is required to use U2F

## 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 U2F 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
- Allow users to remove U2F key: If enabled, users can unregister enrolled U2F 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 2F device is removed.
- Logo (Optional): logo file (in static/<skin> directory)
- Label (Optional): label that should be displayed to the user on the choice screen

If you want to use a custom rule for "activation" and enable self-registration, you have to include this in your rule: `$_2fDevices =~ /"type":\s*"U2F"/s`, else U2F will be required even if users are not registered. This is automatically done when "activation" is set to "on".

## Browser compatibility

- Chrome/Chromium ≥ 38
- Firefox :
  - 38 to 56 with U2F Support Add-on
  - 57 to 59, with "security.webauth.u2f" set to "true" in "about:config" (see Yubico explanations)
  - probably enabled by default for versions ≥ 60
- Opera ≥ 40

## Enrollment

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

## Assistance

If a user loses its key, you can delete it from the manager Second Factor module. To enable manager Second Factor Administration Module, set `enabledModules` key in your `lemonldap-ng.ini` file :

    [portal]
    enabledModules = conf, sessions, notifications, 2ndFA

## Developer corner

If you have another U2F registration interface, you have to set these keys in Second Factor Devices array (JSON) in your user-database. Then map it to the _2fDevices attribute (see exported variables):

    $_2fDevices = [{"name" : "MyU2FKey" , "type" : "U2F" , "_userKey" : "########" , "_keyHandle":"########" , "epoch":"1524078936"}, ...]

`_userKey` must be base64 encoded

Note that both "origin" and "appId" are fixed to portal URL.