# Authentication & MFA

## Overview

Primebrick enforces modern authentication best practices. **Passkey support via
WebAuthn** means users authenticate with Windows Hello™, Face ID™, or Touch ID™ —
no passwords to phish, no OTP codes to intercept. **Multi-factor authentication**
is integrated at the identity layer (Casdoor™/OIDC), not added as an afterthought.

## Passkeys (WebAuthn / FIDO2)

Primebrick supports **FIDO2/WebAuthn passkey authentication** — the most
phishing-resistant authentication method available today. Passkeys replace
shared secrets with public-key cryptography:

- **No shared secrets**: The server stores only a public key. The private key
  never leaves the user's device.
- **Phishing-resistant**: Passkeys are bound to the origin (domain) they were
  created for. A fake login page on a different domain cannot capture a passkey.
- **No replay attacks**: Each authentication ceremony generates a unique
  cryptographic challenge. Previous responses cannot be replayed.
- **Platform authenticators**: Windows Hello™, Face ID™, Touch ID™, and Android
  biometrics all act as platform authenticators.

### How passkeys work in Primebrick

1. The user registers a passkey during enrollment via the Casdoor IDP
2. The browser/platform prompts for biometric or PIN verification
3. The authenticator signs the challenge with the private key
4. Casdoor verifies the signature against the stored public key
5. The user is authenticated — no password was ever transmitted

## Windows Hello™

Biometric and PIN authentication on **Windows 10/11** via Windows Hello™. When a
user authenticates with a passkey on Windows, the OS prompts for Windows Hello
(face, fingerprint, or PIN). No password is required.

## Face ID™ & Touch ID™

Biometric authentication on **macOS and iOS** via Face ID™ and Touch ID™. On
Apple platforms, passkey authentication triggers the native biometric prompt.
The authentication is seamless, secure, and native — no browser plugins or
third-party software needed.

## MFA everywhere

Multi-factor authentication is enforced at the **identity provider (Casdoor™/OIDC)**,
not at the application layer. This means:

- **TOTP**: Time-based one-time passwords (Google Authenticator, Authy, etc.)
- **Hardware keys**: FIDO2 security keys (YubiKey, Titan, etc.)
- **Passkeys**: WebAuthn platform authenticators

MFA is required for all admin accounts and can be enforced for all users via
Casdoor™'s organization policy. The application never sees the MFA factors — it
only receives an OAuth/OIDC token that proves the user completed MFA.

## Standards & references

| Standard | Relevance |
|----------|-----------|
| [FIDO2](https://fidoalliance.org/fido2/) | The open authentication standard behind passkeys |
| [WebAuthn (W3C)](https://www.w3.org/TR/webauthn-3/) | Web API for public-key authentication |
| [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414) | OAuth 2.0 Authorization Server Metadata |
| [OIDC (OpenID Connect)](https://openid.net/specs/openid-connect-core-1_0.html) | Identity layer on top of OAuth 2.0 |
| [NIST SP 800-63B](https://pages.nist.gov/800-63-3/sp800-63b.html) | Digital Identity Guidelines — Authenticator Assurance Levels |