Passkeys & FIDO2

WebAuthn second factor, built on Fido2NetLib

Back to Documentation

What Orion uses

PackageVersionRole
Fido23.0.1WebAuthn attestation and assertion verification
Fido2.AspNet3.0.1services.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

VariableDefaultNotes
ORION_FIDO2_DOMAINhost 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_ORIGINSderived 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.
The RP ID is effectively permanent. Credentials are scoped to it by the browser, so moving the server to a different domain invalidates every registered passkey and every user must re-enrol. Decide the hostname before enrolling anyone.

Registration

From Account → Security, while signed in. Two calls, following the WebAuthn ceremony:

Browser ──▶ POST /Management/BeginPasskeyRegistration?name=…
    ◀── 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.

POST https://login.shanecraven.com/auth/passkey/begin
    ◀── { 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:

POST https://login.shanecraven.com/federation/twofactor/passkey/begin  { actionId }
    ◀── { 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.

Everything is bound to the browser's sign-in. The pending action must be on the session key the browser holds (its 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:

POST …/begin  (the operation's own fields)
    ◀── { 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.Json manually. 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.cookie to 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/verify with 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 (localhost is exempt).
  • "Not allowed" / origin errors — the page origin is not in ORION_FIDO2_ORIGINS, or does not match ORION_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_ORIGINS is 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.
Authentication Configuration All Documentation