Nedo.AspNet.Authentication.Local.Passkeys 2.0.3

Nedo.AspNet.Authentication.Local.Passkeys

Passkeys / WebAuthn (FIDO2) sign-in for Nedo.AspNet.Authentication.Local. Passwordless or step-up sign-in via Touch ID, Windows Hello, YubiKey, or phone-as-key (hybrid transport / cross-device QR).

Built on Fido2NetLib.

Install

dotnet add package Nedo.AspNet.Authentication.Local.Passkeys

Requires that Nedo.AspNet.Authentication.Local is already wired up (AddLocalAuthentication + AddLocalAuthStore).

Quickstart

using Nedo.AspNet.Authentication.Local.Passkeys;

builder.Services.AddPasskeys(opts =>
{
    // Bare host — no scheme, no port. MUST match the SPA's host exactly,
    // or browsers will reject every assertion as "not for this origin".
    opts.ServerDomain = "app.example.com";        // dev: "localhost"
    opts.ServerName   = "Acme Corp";              // shown by the authenticator UI
    opts.Origins      = new() { "https://app.example.com" };  // dev: "https://localhost:5173"
});

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();
app.MapLocalAuth();
app.MapLocalAccount();
app.MapPasskeyEndpoints();    // /auth/passkey/* + /account/passkeys
app.Run();

The package registers IFido2, IMemoryCache (challenge state), and PasskeyService. The nedo_passkeys table is provisioned by AddLocalAuthStore itself — the entity + EF mapping ship in Local.

Endpoints

Frontend recipe (passwordless / discoverable)

// Sign-in
const opts = await fetch('/auth/passkey/assertion/begin', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({}),  // omit username for the discoverable flow
}).then(r => r.json());

const assertion = await navigator.credentials.get({ publicKey: decodeB64Url(opts) });

const tokens = await fetch('/auth/passkey/assertion/finish', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ assertionResponse: encodeB64Url(assertion), deviceInfo: navigator.userAgent }),
}).then(r => r.json());
// → same TokenResponse shape as /auth/login

decodeB64Url / encodeB64Url are the standard WebAuthn helpers — see the bundled React sample's webauthn.ts for a copy-pasteable pair.

Pipeline integration

FinishAssertionAsync runs the same gates as a password sign-in:

1. FIDO2 signature verification + counter regression check (cloned-authenticator detection).
2. ILockoutPolicy.IsLockedOutAsync — passkey users lock out under the same policy.
3. IMultiFactorChallenge.IsRequiredAsync — TOTP gating still applies.
4. Every IPostLoginCheck — TOS / tenant / trial gates apply uniformly.
5. SessionTokenIssuer.IssueNewSessionAsync — same TokenResponse shape, same refresh-token family bookkeeping.

So a passkey login is a true peer of password sign-in, not a side door.

Pitfalls

• ServerDomain must match the SPA's host exactly (no scheme, no port). Common mistake: registering with "localhost" and signing in from "127.0.0.1".
• Origins must include the scheme + port. https://app.example.com ✓ — app.example.com ✗.
• Resident keys are required by default so credentials work in the discoverable / passwordless flow.
• localhost works for same-device WebAuthn, but cross-device hybrid (iPhone scanning desktop QR) requires HTTPS + a hostname the iPhone can reach. Use ngrok https 5173 for dev and update ServerDomain + Origins to match.

Full guide: docs/providers/passkeys.md.

Related

License

MIT — see LICENSE.