Passkeys & FIDO2
WebAuthn second factor, built on Fido2NetLib
What Orion uses
| Package | Version | Role |
|---|---|---|
Fido2 | 3.0.1 | WebAuthn attestation and assertion verification |
Fido2.AspNet | 3.0.1 | services.AddFido2(...) and the IFido2 service injected into controllers |
Passkeys are a second factor here, not a primary credential: a user signs in with a
password, and the passkey satisfies the outstanding second-factor step. Registering one
automatically sets TwoFactorEnabled on the account.
Configuration
| Variable | Default | Notes |
|---|---|---|
ORION_FIDO2_DOMAIN | host of ORION_BASE_URL |
The WebAuthn Relying Party ID. Registered credentials are bound to it — change it and every existing passkey stops working. |
ORION_FIDO2_ORIGINS | derived from ORION_BASE_URL |
Absolute origins allowed to perform WebAuthn, space or comma separated. Each must be a full URI (https://login.example.com). Invalid entries, or an empty result, throw at startup. |
Registration
From Account → Security, while signed in. Two calls, following the WebAuthn ceremony:
◀── CredentialCreateOptions (challenge, RP, user handle)
Browser ──▶ navigator.credentials.create(…)
Browser ──▶ POST /Management/CompletePasskeyRegistration
◀── attestation verified ▶ Authenticator row, TwoFactorEnabled = true
The credential is stored as an Authenticator with
AuthenticatorType = Passkey. A user may hold several. Registration asks for a
discoverable credential (residentKey: "preferred"), which can sign in on its own.
Signing in without a password
Both login pages offer Sign in with a passkey, and the browser's autofill on the email field offers the passkeys it holds for the site. The challenge lists no credential: the passkey names the account by its user handle, so no address is looked up.
◀── { handle, options } (challenge, no allowCredentials)
Browser ──▶ navigator.credentials.get(…) (a button, or mediation: "conditional")
POST https://login.shanecraven.com/oauth/<org>/login/passkey (or /Federation/Login/Passkey) with the assertion
◀── verified ▶ session key,
amr pop hwk mfa
A user-verified passkey is two factors and phishing-resistant on its own, so rules asking for either are met without another prompt. Someone holding two passkeys, or one and recovery codes, can turn their password off on the account page, after confirming with a passkey that it signs in on its own.
Signing in with one
After a password login, the session key carries a mandatory second-factor action and is not yet a valid session. The assertion clears it:
◀── { handle, options } (challenge, allowCredentials)
Browser ──▶ navigator.credentials.get(…)
POST https://login.shanecraven.com/federation/twofactor/passkey/complete?handle=…
◀── verified ▶ factor recorded on the key, pending action deleted ▶ session usable
Both the OAuth second-factor page and the legacy federation page use these same endpoints, and
both offer a passkey first with an authenticator-app code as the alternative. Completing the
factor adds it to what the sign-in proved (the session key's AuthMethods, which
becomes the SSO session's and the ID token's amr: pwd pop hwk mfa)
and deletes the pending action — until then the session resolver rejects the key, so a password
alone is never enough.
OrionFederationKey cookie); the challenge is a
single-use database row bound to that key, so an answer can reach any instance and can never
be replayed; and both calls carry the page's antiforgery token. The signature counter is
checked and stored (a counter that goes backwards refuses the passkey and is audited), and
whether the credential is synced or bound to its device is recorded.
Approving one operation
Someone who holds a passkey or security key approves some operations with it: approving another organisation's application for everyone in their own (on App Approvals, and the consent screen's "Approve for …"), and answering a sovereign signing agent's question while signing in. The operation's page shows what is approved, and the passkey's challenge commits to exactly that:
◀── { required: false } or { handle, options, title, lines, reference }
Browser ──▶ the dialog shows title and lines ──▶ navigator.credentials.get(…)
POST https://login.shanecraven.com/auth/approve/complete?handle=…
◀── { approval } (single use, two minutes, this session)
POST the operation (its fields + approval) ▶ refused unless the approval is of exactly this
The challenge is a fresh salt followed by SHA-256(salt ‖ description), the description being the kind, title and lines the server built from what it holds, never from text the browser sent. The operation builds its description again from its own request and spends the approval only if the passkey signed that one: another scope, another answer, the same approval twice or another session's is refused. The touch also confirms the session, as the re-verification page does, so the operation's own "confirm it's you" needs nothing more. Each approval is audited with a reference the dialog showed. Someone who holds no passkey is asked nothing.
Implementation notes
- Fido2NetLib types are System.Text.Json. The MVC pipeline here uses Newtonsoft, so
passkey completion endpoints read the raw body and deserialise with
System.Text.Jsonmanually. Using[FromBody]silently produces an empty object and the ceremony fails with no useful error. - Cookies are HttpOnly. A page cannot read the session key from
document.cookieto post it back; the server resolves the caller itself. An earlier version of the device page tried exactly that and could never work. - TOTP is the alternative factor. Users with an authenticator app satisfy the same pending action via a code instead, on either portal. Each code is accepted once, and wrong codes count toward the account's lockout.
- Recovery codes are the way back in. Adding a first passkey or authenticator app creates ten single-use recovery codes, shown once on the account page (copy, download or print). Each answers a second-factor prompt once when the usual factor is lost, under the same lockout; using one emails the account. The account page shows how many are left and creates a new set. Codes are not an authenticator: they never turn two-factor on.
- Lost everything? An administrator starts recovery. "Start recovery" on the person's row
issues a temporary access code (shown once; one use within an hour). After their password or
directory sign-in, the person enters it where a recovery code goes; it opens adding one new passkey
or authenticator app, and they finish signing in with that. The last platform administrator can get
one on the server:
dotnet OrionRestAPI.dll issue-access-code <email>. - Changing sign-in methods needs a recent sign-in. Adding or removing a passkey or
authenticator app, turning two-factor off and linking a directory identity require a
sign-in or re-verification within
ORION_REVERIFY_MINUTES(15); otherwise the person confirms it's them at/auth/verifywith a factor they hold, or without one the way they signed in: their organisation's directory again, or their password.
If a passkey will not work
- Nothing happens on click — the browser requires a secure context. Use HTTPS
(
localhostis exempt). - "Not allowed" / origin errors — the page origin is not in
ORION_FIDO2_ORIGINS, or does not matchORION_FIDO2_DOMAIN. - Worked before, now fails for everyone — the RP ID changed. Existing credentials are bound to the old one and cannot be recovered; users must re-enrol.
- Server will not start, complaining about origins — an entry in
ORION_FIDO2_ORIGINSis not an absolute URI, or the list resolved to empty. - 2FA is on but no authenticator is active — that account cannot complete sign-in and there is no self-service recovery. An administrator must clear the flag directly.