# 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](/foundation/0.19.0/guides/strong-authentication/) 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](/foundation/0.19.0/guides/mobile-authentication/) 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](/foundation/0.19.0/guides/bff-authentication/) 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](/foundation/0.19.0/guides/action-confirmation/) 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](/foundation/0.19.0/guides/oidc-login/), [BFF setup](/foundation/0.19.0/guides/bff-authentication/),
[API credentials](/foundation/0.19.0/guides/api-credentials/) or [troubleshooting](/foundation/0.19.0/guides/troubleshooting/).
