Skip to content

Security keys (FIDO2)

Users can protect their sign-in with a security key (YubiKey and similar), a passkey, Touch ID or Face ID as the second factor.

Before you start

  • Open Easy8 over HTTPS. Browsers allow security keys only on secure pages. localhost is the only exception that works over plain HTTP.
  • Two-factor authentication must not be Disabled in Administration › Settings › Authentication › Two-factor authentication. Choose optional, required for (partial) administrators or required.

Users choose their method in My profile. Easy8 offers Authenticator app and Security key or passkey. Each user has one method at a time, can register several security keys, and can generate backup codes.

Settings

Both settings are in Administration › Settings › Authentication.

Setting Default Use
Security key domain (relying party ID) Host name of Easy8, without port and path The domain a key is bound to.
Additional allowed origins Empty Comma-separated list of extra addresses that users open Easy8 from, for example https://alias.example.com.

Easy8 takes the host name from the Host name and path setting. It accepts sign-ins from https://host name and from every address in Additional allowed origins. Easy8 uses http instead when it runs outside production or when the FORCE_HTTP environment variable is set to true.

Change the defaults in these cases:

  • Users open Easy8 on several host names under one domain, for example a.example.com and b.example.com. Set Security key domain (relying party ID) to example.com and list the other addresses in Additional allowed origins.
  • A reverse proxy publishes Easy8 under a different host name than the one in Host name and path. Set the public host name as the relying party ID and add the public address to Additional allowed origins.
  • Easy8 runs in a sub-URI, for example example.com/easy. Easy8 ignores the path, so the defaults work.

The relying party ID must be the host name users see in the browser address bar, or a parent domain of it.

Changing the domain

Changing Security key domain (relying party ID) or the domain of your Easy8 invalidates every registered security key. Users with backup codes sign in with one and register their keys again. For users without backup codes, reset two-factor authentication for them: open Administration › Users, open the user and click Disable next to Two-factor authentication.

What users see

  • Easy8 does not ask for a PIN or biometrics. Windows can still ask for the PIN of a YubiKey when one is set on the key. Touch ID and Face ID always use their own gesture.
  • A browser without security key support shows the option as unavailable. Users enter a backup code instead if they have one. Otherwise reset two-factor authentication for them as described in Changing the domain.
  • Adding or removing a security key in My profile asks for the second factor again. Users confirm with a registered security key or a backup code.