WebAuthn

WebAuthn is a standard for passwordless authentication using hardware authenticators. ATHELOS supports it as a second factor alongside TOTP.

What WebAuthn is

WebAuthn uses public-key cryptography. When you register a device:

1. The device generates a key pair
2. The public key is stored by ATHELOS
3. The private key stays on the device — never leaves it
4. During login, the device signs a challenge with the private key
5. ATHELOS verifies the signature with the stored public key

The private key never leaves the hardware. Even if your server is compromised, an attacker can't authenticate without the physical device.

Supported devices

Any WebAuthn-compatible authenticator works:

• YubiKey — USB, NFC, or USB-C
• Touch ID — macOS, iOS
• Windows Hello — face, fingerprint, PIN
• Android biometric — fingerprint, face
• Feitian — hardware keys
• SoloKeys — open-source hardware keys
• Nitrokey — hardware keys

The browser handles the interaction. ATHELOS sees a signed challenge, not the biometric.

Why WebAuthn is better than TOTP

Both are second factors. WebAuthn is stronger for two reasons:

Phishing-resistant. The signature is bound to the origin (the domain). An attacker hosting a fake athelos.example.com on a different domain can't get a valid signature — the browser refuses. With TOTP, an attacker can proxy your session and steal the code.

Hardware-backed. The private key lives on the device. It can't be copied or exported. TOTP secrets are symmetric — if stolen, they can be used anywhere.

Use WebAuthn if you can. Use TOTP as a fallback.

Registering a device

Go to Settings → Security. Find the WebAuthn card.

Click Add device.

The browser prompts:

• YubiKey — insert it, tap the button when it blinks
• Touch ID — Touch ID prompt appears
• Windows Hello — face or PIN prompt
• Android — biometric prompt

Complete the prompt. The device is registered.

Give it a name (e.g. "YubiKey 5C", "MacBook Touch ID") for identification.

Using WebAuthn at login

If WebAuthn is enabled:

1. Enter email and password — normal
2. On the second factor prompt, choose Use security key
3. Complete the browser prompt
4. You're signed in

If TOTP is also enabled, both options are offered. Pick either.

Managing devices

The WebAuthn card lists every registered device:

• Name — what you called it
• Type — hardware key, platform authenticator, etc.
• Registered — when
• Last used — most recent authentication

Rename a device by clicking its name. Useful if you have multiple keys.

Removing a device

Click Remove next to a device. Confirm.

The device stops working immediately. If it was your only second factor, you'll need to log in with a recovery code or fall back to TOTP.

Before removing your last device, register a new one first. This prevents lockout.

Adding multiple devices

Register at least two:

• One for daily use (YubiKey on your keyring)
• One backup (a second YubiKey kept somewhere safe)

If one is lost or broken, the other still works.

YubiKey specifics

YubiKeys are the most common hardware authenticators. Setup notes:

USB-C — plug in, tap when it blinks USB-A — same, older port NFC — hold to the back of a phone YubiKey 5 series — supports FIDO2, WebAuthn, TOTP, PIV YubiKey Bio — fingerprint + FIDO

You don't need Yubico's software to use a YubiKey with WebAuthn. Just plug it in and use it.

Platform authenticators

Modern OSes have built-in WebAuthn support:

• macOS — Touch ID
• iOS — Face ID / Touch ID
• Windows — Windows Hello (face, fingerprint, PIN)
• Android — biometric

These are convenient but less secure than a hardware key. They're tied to the device — if the device is compromised, the authenticator is compromised.

For maximum security, use a hardware key. For daily convenience, a platform authenticator is fine.

Combining with TOTP

When both TOTP and WebAuthn are enabled:

• Users see a choice at login: use a security key or enter a TOTP code
• Either is accepted
• WebAuthn is offered first (it's the stronger factor)

Some deployments disable TOTP once WebAuthn is set up, for stronger security. That's a decision for you.

Recovery

If you lose your WebAuthn device:

1. Log in with TOTP (if enabled)
2. Log in with a recovery code (if not)
3. Both are unavailable? See Troubleshooting: common issues

Always have a second factor configured. Only-WebAuthn is a single point of failure.

Behind the scenes

WebAuthn uses the @simplewebauthn library — the standard implementation for Node.js.

Credentials are stored in webauthn_credentials:

• Credential ID
• Public key
• Sign counter
• Device name and type
• Registered timestamp

The sign counter increments on each authentication. If a signature comes in with a counter that isn't higher than the last, the credential is marked suspicious.

Security properties

WebAuthn provides:

• Phishing resistance — signatures bound to the origin
• Hardware backing — private key never leaves the device
• Replay resistance — each challenge is unique
• Cross-origin protection — browser enforces the origin

It does not provide:

• Protection against physical theft — if someone steals your YubiKey, they can use it (assuming they also have your password)
• Protection against a compromised browser — a browser extension with full access could theoretically interfere

For most threat models, WebAuthn is the strongest available second factor.

Common issues

Browser doesn't prompt

Check browser compatibility. Modern Chrome, Firefox, Safari, and Edge support WebAuthn. Older browsers may not.

"Security key not recognized"

• Try a different USB port
• If using a hub, plug directly into the machine
• Check the key is a FIDO2/WebAuthn key, not a legacy U2F-only key (though most U2F keys work)

Multiple keys prompt confusion

If you have multiple keys plugged in, the browser may not know which to use. Remove all but one.

Touch ID doesn't appear on macOS

Enable Touch ID for the browser in System Settings → Touch ID & Passwords.

Windows Hello not working

Check Windows Settings → Accounts → Sign-in options. Ensure Windows Hello is set up.

Disabling WebAuthn

To disable WebAuthn entirely, remove all registered devices. The WebAuthn option disappears from the login flow.

If TOTP is still enabled, it remains as the second factor.

Where to go next

• Two-factor — TOTP setup
• Security — threat model
• Account — sessions and recovery