WebAuthn as a second factor
===========================

`Web Authentication <https://www.w3.org/TR/webauthn/>`__ , 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 :doc:`dedicated documentation<authwebauthn>`.

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
------------

It is possible to use WebAuthn credentials that have been externally
provisionned if you don't want to use LemonLDAP::NG-s self-registration.

In order to do this, you can manually modify the `_2fDevices` variable in the
user's persistent session, or use the :ref:`Manager API<managerapi>`.

The entry for each device must contain the following subkeys

* ``name``: Human-visible label for this device
* ``type``: ``WebAuthn``
* ``epoch``: UNIX timestamp of registration time
* ``resident``: optional, ``1`` if the key is resident
* ``_credentialId``: base64-encoded credential ID
* ``_credentialPublicKey``: base64-encoded public key
* ``_signCount``: *optional*, integer, signature counter
* ``_transports``: *optional*, comma-separated list of allowed transports (``nfc,usb``...)
* ``_aaguid``: *optional*, UUID-formatted authenticator AAGUID (``00000000-0000-0000-0000-000000000000``)

.. warning::

   The credential ID and public key are tied to the domain they were registered
   to. If you are performing WebAuthn registration in an external application,
   be sure to set the *Relying Party ID* of both LemonLDAP::NG and your
   registration system to a common registrable DNS suffix.  Registering on
   ``webauthn.example.com`` and authenticating on
   ``auth.example.com`` will work if the Relying Party ID is ``example.com``.
   But registering on ``webauthn.domain1.com`` and authenticating on
   ``auth.domain2.com`` will not work.


.. _migrateu2ftowebauthn:

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