On this page
Choose an authentication path
Choose browser, native, provider, passkey and machine flows with explicit product ownership.
Start with the client and the identity source. Foundation supplies security primitives and transport adapters; your application supplies users, linking, current admission and the business effects of a successful login.
Pick the first proof
| Requirement | Foundation path | Product work |
|---|---|---|
| Username/password or magic link | Host verifies primary identity, then enters the strong-authentication/session flow | User records, hashing or mail proof, uniqueness, expiry and throttling |
| Google, Apple or Microsoft in a browser | Correlated OIDC code flow | Provider application, durable intent store, account resolution and consent |
| Provider SDK token on Capacitor | Native OIDC challenge and token exchange | Native SDK, approved audiences/nonce convention and original client binding |
| Touch ID, Face ID or a security key | WebAuthn/passkey verification | Native/browser bridge, relying-party associations and credential ownership |
| Authenticator second factor | TOTP enrollment and verification | User policy, management admission and recovery workflow |
| Machine integration | Personal API token or confidential machine client | Ownership, permitted scopes, networks and current admission |
A biometric gesture unlocks a device-held credential. Foundation verifies the
cryptographic response; it never receives a face or fingerprint. Provider login
and a mailbox's OAuth consent are different grants. Neither an email match nor
a provider amr claim silently links accounts or satisfies local MFA.
Plan the complete lifecycle
For a human client the path is: verify primary identity, apply the product MFA policy, complete a one-use proof, issue the selected local session profile, then validate authoritative session state on every protected request. Include refresh, logout, expiry, explicit revocation and recovery in the initial design.
Read strong-authentication responsibilities before registering its services. The mandatory authority/directory/store ports are security boundaries; an allow-all or process-local substitute is not production integration. Use the browser/native lifecycle for the transport contracts and persistent session mappings.
Put a BFF in front of browser clients
The browser calls its own BFF. The BFF owns public cookies, CSRF and the private API transport. It forwards the selected locale/timezone as presentation data, not as identity. Follow BFF and OIDC integration before configuring provider callback URLs; those URLs must describe the public BFF origin.
A native SDK token exchange is an additional path, not permission to disable nonce or use an embedded provider WebView. Capacitor can also use a system browser and verified app links. The exact native bridge and physical device still need their own acceptance test.
Decide sensitive-operation policy explicitly
An existing login may be too old for changing email, removing a factor or a privileged action. Fresh reauthentication can use the account's actual methods, including a linked OIDC identity, without forcing an OIDC-only user to create a local password.
Adding a factor or regenerating recovery codes does not automatically revoke all sessions. Choose a revocation policy explicitly; expose revoke-other-sessions when needed. Confirming a resource name is intent confirmation, not an identity factor. The generic action-confirmation workflow is still product work; do not infer an automatic endpoint/interceptor from its legacy error DTOs.
Validate the boundaries
Before launch, prove that linking cannot be established by matching email, disabled users fail current admission, refresh/revocation races cannot resurrect a session, and an MFA requirement survives the BFF continuation. Software fixtures do not certify a provider-console configuration or native biometric device.
Next: OIDC contract, BFF setup, API credentials or troubleshooting.