Learn Authelia - WebAuthn / FIDO2

#Introduction

In episode 9, TOTP added a second layer that protects leaked passwords. But TOTP still has one classic gap: a 6-digit code can be typed into a phishing site that clones the Authelia login page. The attacker doesn't steal the secret — they just trick the victim into entering the code in the wrong place.

WebAuthn closes that gap at the root. In this episode you'll understand the W3C standard that FIDO2 is based on: why its credentials are bound to the real domain, how Authelia implements it, how to configure WebAuthn behavior, up to the YubiKey enrollment process and the considerations for choosing WebAuthn or TOTP.

#WebAuthn Basics: Credentials Bound to an Origin

WebAuthn is a W3C standard that enables authentication using an authenticator — a device that stores a private cryptographic key. There are two types of authenticators:

• Platform authenticators: already built into the device, like Touch ID, Face ID, Windows Hello, and Android biometrics.
• Roaming authenticators: separate hardware like a YubiKey or Titan Security Key.

At enrollment, the authenticator creates a key pair: a private key that never leaves the device, and a public key sent to Authelia. The private key can't be extracted — an attacker who steals Authelia's database only gets a useless public key without the physical device.

Its main advantage is origin binding. Every authentication includes a signature over the origin information (domain and scheme). A signature from the auth.example.com domain will never match a phishing domain like auth-example.net. This is where the fundamental difference lies: TOTP verifies "you know the same code", WebAuthn verifies "you hold a valid key for this domain".

#How Authelia Implements It

Authelia presents WebAuthn as one of the second methods at the portal. The enrollment flow:

1. Log in with a password (first factor), then select the Security Key method.
2. Click "register device" and complete the identity verification via email.
3. Touch the authenticator — for example a YubiKey — to sign the enrollment challenge.
4. The public key is stored in storage; from then on, logging in is just touching the authenticator again.

Thanks to SSO, one enrollment applies to all applications protected by Authelia — users don't need to register their YubiKey in every service. Authelia also supports enable_passkey_login, which allows logging in without a password at all using a passkey (passwordless), changing WebAuthn's role from just a second factor to a replacement for the first factor.

#WebAuthn Configuration

WebAuthn behavior is controlled through the webauthn section:

webauthn:
  display_name: "Authelia"
  attestation_conveyance_preference: "indirect"
  timeout: "60 seconds"
  selection_criteria:
    discoverability: "preferred"
    user_verification: "preferred"

• display_name: the name sent to the browser and displayed during the WebAuthn dialog.
• attestation_conveyance_preference: how much data about the authenticator is collected. none minimizes data, indirect obscures device identity, direct requests the attestation statement directly from the authenticator including the AAGUID (device model). The indirect default balances privacy and verification.
• timeout: the time limit for the WebAuthn interaction, written in a duration syntax like 60 seconds.
• selection_criteria: preferences for attachment, discoverability, and user verification at enrollment.

#YubiKey Enrollment: Practical Steps

The YubiKey is the most popular roaming authenticator. The enrollment process in Authelia:

1. Make sure the browser is modern and supports WebAuthn; plug the YubiKey into the computer.
2. Log in to the portal, select the Security Key method, then register a device.
3. Complete the identity verification via the email Authelia sends.
4. Touch the YubiKey button when prompted; the device lights up and signs the challenge.
5. Give the device a name so it's easy to recognize in the list, then finish.

Some YubiKeys support multiple slots, so you can register one key for several purposes. When an authenticator is lost or suspected compromised, remove it from the list via the portal or CLI:

authelia storage user webauthn list
authelia storage user webauthn delete john --identifier "yubikey-1"

#Backup and Recovery

The same principle from TOTP applies: never rely on a single authenticator. A healthy strategy:

• Register at least two devices: one YubiKey you always carry, another stored somewhere safe.
• Combine with TOTP as a backup method. If the YubiKey is lost while traveling, the user can still log in via an authenticator app.
• Keep public keys and device metadata in backed-up storage (episode 8), because losing the database means all devices must be re-registered.

#WebAuthn vs TOTP: Choosing the Right One

Both methods can coexist, but understanding their differences helps you decide which to make primary:

• Phishing resistance: WebAuthn is far superior because credentials are bound to the domain. TOTP is vulnerable to phishing that captures the code.
• Cost and availability: TOTP is free and available on every phone. WebAuthn needs hardware (YubiKey) or a device with biometrics.
• Ease of use: touching a key or biometric is faster than typing a 6-digit code. However, some platforms aren't yet consistent in supporting WebAuthn across all browsers.
• Recovery: TOTP is easier to recover with a secret backup. With WebAuthn, losing the device means losing access until re-registration.
• Privacy: direct attestation can reveal the device model; TOTP reveals nothing.

#Closing

Key points of this episode:

• WebAuthn (W3C/FIDO2) uses a private key stored in the authenticator; the public key at Authelia is useless without the physical device.
• Credentials are bound to the origin, making them phishing-resistant — the main advantage over TOTP.
• Core configuration: display_name, attestation_conveyance_preference, and timeout.
• YubiKey enrollment is simple after identity verification; manage devices via the portal or CLI.
• Combine WebAuthn as primary and TOTP as fallback for security plus resilience.

All the second methods so far run on your own devices: an authenticator app or a physical key. In episode 11, there's one more method that moves the decision to a third-party service — Duo Push. You'll integrate Authelia with Duo Security, install the API key, and understand when push notifications are better and when to fall back.