WebAuthn as a second factor

Web Authentication , shortened as WebAuthn, is a standard method by which a web browser can authenticate to an application (Relying Party, in our case, this is LemonLDAP::NG) through the use of an Authenticator, which can be a hardware token (USB, NFC...) or provided by the user’s device itself (TPM).

Tip

If you want to use Webauthn as first factor (also called passwordless), see dedicated documentation.

Implementation status

Currently, we implement:

  • Device registration without attestation validation (attestation type: None)
  • Authentication as a second factor with the registered device

Requirements

You need to install the Authen::WebAuthn CPAN module for WebAuthn to work on your LemonLDAP::NG installation.

For Debian:

apt install libauthen-webauthn-perl

For RHEL (>=8):

dnf install perl-Authen-WebAuthn

If there is no package for it in your distribution, you can install it with:

cpanm Authen::WebAuthn

Configuration

  • Activation: Set it to “on”.
  • Self registration: set it to “on” if users are authorized to register their keys
  • Allow user to remove WebAuthn: if enabled, user can unregister their WebAuthn devices
  • User verification: Whether or not LemonLDAP::NG requires the user to authenticate to their second factor device. Usually by entering a PIN code. Warning: The Required option is not supported by older U2F security keys.
  • Use discoverable credential: a private key that is associated with a user handle is generated on the authenticator
  • Attestation: Type of attestation to request from the authenticator. After enabling this you need to specify a list of trusted certificates
  • Attestation trusted certificates: A concatenation of PEM certificates that you trust for attestation
  • Relying Party display name: how the LemonLDAP::NG server will appear in the web browser messages displayed to the user
  • Relying Party ID: The domain name on which WebAuthn devices can be registered and used. It must be a non-public suffix of the portal’s hostname.
  • Send U2F AppID: send the string that declares which facets that belong to this application
  • User Display Name attribute: session attribute containing user display name
  • Default transports: Comma-separated list of transport hints sent to the web browser, if none are provided during registration
  • Authentication level: you can overwrite here auth level for WebAuthn 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)

Attention

If you want to use a custom rule for “activation” and want to keep self-registration, you must add the following condition to the custom activation rule:

and has2f('WebAuthn')

Without this condition, WebAuthn device will be asked even for users who didn’t register one. 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" : "MyFIDO2" , "type" : "WebAuthn" , "epoch":"1524078936"}, ...]

Migrating existing U2F devices

WebAuthn is compatible with both FIDO and FIDO2 standards. Which means this module lets you use any U2F-compatible device you already own.

You can use the lemonldap-ng-sessions tool to migrate existing U2F devices to the WebAuthn plugin

# For one user
lemonldap-ng-sessions secondfactors migrateu2f dwho

# For all users
lemonldap-ng-sessions secondfactors migrateu2f --all

Once you are satisfied with WebAuthn, you can remove existing U2F devices and disable the U2F second factor module

# For one user
lemonldap-ng-sessions secondfactors delType dwho U2F

# For all users
lemonldap-ng-sessions secondfactors delType --all U2F