Skip to main content

Trusted browsers

"Remember this device" — skip the MFA challenge on a remembered device.

How it works​

After a successful MFA challenge, the client may call POST /v1/auth/trusted-browsers. The SDK:

  1. Mints a 32-byte random token.
  2. Stores SHA-256(token + ":" + User-Agent) in trusted_browsers.
  3. Sets an identsphere_trust cookie with the raw token, scoped to route_prefix, HttpOnly, 30-day TTL.

On the NEXT password login from the same browser, the login handler:

  1. Extracts the identsphere_trust cookie value.
  2. Computes the same hash with the request's User-Agent.
  3. If a matching, unrevoked, unexpired row exists → skip the MFA challenge.
  4. The session is issued at AAL2 (auth_method: "password_with_mfa").
  5. last_seen_at on the trusted-browser row is updated.

Why bind to User-Agent​

A leaked cookie alone shouldn't bypass MFA. The User-Agent binding makes the cookie useless in any browser that doesn't match the original — best-effort "different device" detection without requiring full client attestation.

Management​

EndpointPurpose
POST /v1/auth/trusted-browsersMark current browser trusted
GET /v1/auth/trusted-browsersList my trusted browsers
DELETE /v1/auth/trusted-browsers/:idRevoke a specific entry

A user with stolen cookies can revoke all entries via the list UI to re-impose the MFA requirement on every device.

TTL​

30 days, hardcoded in v0.1. The cookie's lifetime and the database row's expires_at match.

Audit​

  • auth.trusted_browser.added on creation.
  • auth.trusted_browser.revoked on revocation.
  • auth.login metadata includes trusted_browser_id when the short-circuit fires.

What this is NOT​

This is NOT "remember me" for password-only logins. The identsphere_trust cookie only matters when the user has MFA enrolled. For non-MFA accounts the cookie is silently ignored.

This is also NOT a DPoP or hardware-attestation flow. The cookie is a bearer token bound only by HTTP context (User-Agent + path scope).

Disabling​

Trusted browsers can't be disabled per-deployment in v0.1; it's an opt-in flow client-side. If you don't call POST /v1/auth/trusted-browsers, the feature is invisible to the user.