# Integrate strong authentication

Understand passkey, TOTP, recovery and host assurance responsibilities.

Status: backend integration supplied in **0.7.0**. Version **0.7.1** adds
the policy/metadata corrections below; they are not in 0.7.0.
Products own their directory, trusted actor resolution, policy, deployment and
client integration; foundation supplies the reusable backend lifecycle.

## Methods and assurance

Passkeys use WebAuthn/FIDO2 and the native ASP.NET Core 10 verifier. Platform
biometrics or a device PIN can unlock the authenticator. The server receives
cryptographic proof and user-verification evidence, never biometric data.
Compatible roaming FIDO2 security keys use the same protocol. TOTP supports
standards-based Authenticator applications. Recovery codes are one-use emergency
credentials; they do not automatically establish MFA or phishing resistance.
Proprietary push approvals and YubiOTP remain separate integrations.

No method is enabled by default. Mandatory MFA must complete before ordinary
session issuance. CompletePrimaryLoginAsync accepts only a trusted, fresh host
actor and current policy; password/OIDC/magic-link verification remains with the
host. Never trust a client biometric-success flag or arbitrary OIDC amr/acr.

## Register and protect the lifecycle

Compose AddStrongAuthentication, AddNativePasskeys,
AddStrongAuthenticationStore<TContext>, AddInteractiveSessions and
AddFoundationSessionHttp. Supply IStrongAuthenticationAuthority and
ISessionPrincipalSource with current enabled status, roles and policy. Apply the
four authentication mappings and both interactive-session mappings. Own the EF
migration and persist/protect shared Data Protection keys across replicas.

UseRouting, UseCors, UseAuthentication and UseAuthorization precede
MapFoundationSessions. Select the FoundationSession authentication scheme for
product endpoints. Browser/PWA uses Secure/HttpOnly host-only access/refresh
cookies and a binding-specific X-Session-CSRF token. Capacitor uses opaque bearer
access, rotating refresh and X-Session-Binding in native secure storage. Native
requests reject cookies; profile mixing and unrelated origins are rejected.
The adapter provides no frontend or Capacitor secure-storage plugin.

A one-use completion proof becomes a session in the same transaction as proof
consumption, credentials and audit. Rotation atomically consumes and replaces the
refresh token. Same-operation retries return the encrypted short-lived original
result; conflicting or superseded requests receive 409. Late replay revokes only
the affected family. Every protected request checks authoritative state, both
epochs and current roles/policy. Refresh preserves original assurance, method,
authentication time and the absolute expiry. In 0.7.1, ordinary factor
maintenance preserves sessions while a separate credential revision fences
pending challenges/proofs. Global revocation is explicit host policy. In published
0.7.0 every factor mutation still invalidates all sessions.

Version 0.7.1 adds revoke-others, retaining the authenticated caller's family
and credentials, plus explicit management assurance/freshness/permission policy.
Optional login metadata is disabled by default and encrypted when enabled. IP and
user agent are server-observed descriptions; consent-declared GPS/device labels
remain unverified client information. See [session policy and metadata](/foundation/0.19.0/guides/mobile-authentication/).

The legacy IUserSessionStore/IAccessTokenIssuer stack is separate and has no
automatic migration to this opaque-token adapter. Trusted directory/security
events use idempotent InvalidateSubjectAsync; products schedule bounded pruning
without deleting unexpired replay evidence or security-event audit IDs too soon.

## Native identity and acceptance

Configure exact HTTPS browser origins, Apple team/bundle IDs, Android package
IDs and release signing-certificate fingerprints. Association endpoints serve
approved metadata on the RP host. Android native origins must match the bound
client's approved signing hash; iOS uses the approved HTTPS origin. WebView
origins are transport configuration, not implicitly trusted WebAuthn origins.

HTTP software passkey fixtures, real SQLite/PostgreSQL concurrency, rollback,
revocation and populated-schema upgrade tests establish backend behavior. Physical
Touch ID, Face ID, Windows Hello, YubiKey and actual Capacitor builds still need
product acceptance. A local biometric unlock of a stored refresh credential does
not renew authentication freshness or raise server assurance.

See [browser and Capacitor sessions](/foundation/0.19.0/guides/mobile-authentication/) for exact routes, configuration,
retry semantics, migration and deployment requirements. Next: [request security](/foundation/0.19.0/guides/request-security/)
and [documentation contract](/foundation/0.19.0/guides/documentation/).

## New-session admission in 0.11.0

SessionPolicy.LoginRequiredAssurance adds a requirement at fresh proof exchange,
while RequiredAssurance continues to govern existing sessions and refresh. Raising
the login requirement alone preserves established sessions; changing ongoing policy
or explicit revocation remains a separate product action. Factor changes still fence
pending proofs atomically. AllowRecoverySessions explicitly admits degraded recovery
proofs; products must deny credential issuance/linking and other sensitive actions
until appropriate reauthentication. Recovery is never silently promoted to MFA.

## Related integration guides

Start with [choose an authentication path](/foundation/0.19.0/guides/authentication-paths/) for the client/identity decision, then [the BFF guide](/foundation/0.19.0/guides/bff-authentication/) for provider login.
