Skip to main content

WebAuthn / FIDO2 / Passkeys Authenticator setup stage

This stage configures an authenticator stage for using WebAuthn, FIDO2, Passkeys. This stage supports:

  • Security Keys: Physical devices like YubiKey, Google Titan, etc.
  • Platform Authenticators: Built-in authenticators like Windows Hello, Touch ID, Face ID
  • Mobile Devices: Using device biometrics or security keys via mobile browsers

Options​

User verification​

Configure if authentik should require, prefer or discourage user verification for the authenticator. For example when using a virtual authenticator like Windows Hello, this setting controls if a PIN is required.

Resident key requirement​

Configure if the created authenticator is stored in the encrypted memory on the device or in persistent memory. When configuring passwordless login, this should be set to either Preferred or Required, otherwise the authenticator cannot be used for passwordless authentication.

Authenticator Attachment​

Controls the authenticatorAttachment parameter sent to the browser during WebAuthn registration. The available options are:

  • No preference is sent: The browser may offer any available authenticator (default).
  • Platform: A non-removable authenticator built into the device, such as Touch ID, Face ID, or Windows Hello.
  • Cross-platform: A "roaming" authenticator, such as a YubiKey or Google Titan.

If WebAuthn Hints are configured and this option is left unset, authentik infers a value from the selected hints for backward compatibility with older browsers.

WebAuthn Hints​

Browser behavior

Hints are advisory and browsers may ignore them based on available authenticators or platform capabilities.

Optional hints can be used to guide the browser in prioritizing the preferred authenticator type during registration. The available hints are:

  • Security key: Suggests that the user register a credential with a portable FIDO2 device such as a YubiKey.
  • Client device: Suggests that the user register a credential with a built-in platform authenticator such as Touch ID or Windows Hello.
  • Hybrid: Suggests that the user register a credential using a platform authenticator on a nearby mobile device, typically via a QR code.

The order of selected hints matters: the first hint has the highest priority. For example, selecting "Security key" first and "Hybrid" second asks the browser to prefer security keys before hybrid registration.

For backward compatibility with older browsers that do not support hints, authentik automatically infers the authenticatorAttachment parameter from the selected hints when it is not explicitly set:

  • Only security key and/or hybrid hints: cross-platform
  • Only client device hint: platform
  • If both client-device and cross-platform hints are selected, no value is inferred

Prevent duplicate devices​

When enabled, any unique authenticator can only be registered once. This check can only be enforced if the authenticator stores a unique attestsion certificate.

Device type restrictions​

Optionally restrict the types of devices allowed to be enrolled. This option can be used to ensure users are only able to enroll FIPS-compliant devices for example.

When no restrictions are selected, all device types are allowed.

As authentik does not know of all possible device types, it is possible to select the special option authentik: Unknown devices to allow unknown devices.