Skip to content
Dashboard
Theme
Theme

Dashboard security and recovery

Passkeys, recent second-factor checks, owner recovery and account SSO enforcement.

View Markdown

Dashboard authentication is separate from the enterprise SSO sessions your application manages.

Register a passkey using the WebAuthn registration options and completion operations. The browser must complete the real WebAuthn ceremony; a JSON credential alone is not a substitute. Passkey assertions and TOTP verification can establish a recent second factor.

Sensitive operations require recent verification within a ten-minute window. step_up_required means verify the second factor again, then retry the intended operation. Browser mutations require the session’s CSRF token as declared in the contract. Never expose the session cookie or CSRF token in logs.

Dashboard sessions use an opaque __Host-ohc_session cookie, a twelve-hour absolute lifetime and a two-hour idle timeout. These lifetimes do not apply to your application’s sessions.

Every owner must keep at least one backup passkey: a passkey that signs in to OhAuthCat directly, never through SSO. If you later require SSO for the dashboard and your company’s identity provider goes down or is misconfigured, the backup passkey still signs you in, so you can’t be locked out of your own account. Every use is written to the audit log and emailed to the other owners. In the API, a backup passkey is a credential with break_glass set to true.

An owner’s first passkey is a backup passkey. Normal enrollment allows up to two usable backup passkeys per owner. A recovery session can register a replacement beyond that limit because lost authenticators can remain recorded. Removing the last usable one is refused with last_break_glass_credential.

Generate recovery codes in the dashboard’s account security settings after a recent second factor. Generation replaces the previous set and returns ten single-use codes once. Store them offline in a secure place. Core stores keyed hashes, not the displayed codes. At two unused codes or fewer, the owner receives a warning.

A recovery code works even when account SSO is enforced. Recovery sign-in is audited and alerts the other owners. Its restricted session can only register a new backup passkey; it is not a full-access dashboard session. A used, invalid or ineligible code returns recovery_code_invalid.

Dashboard SSO connects your own team to the account’s internal SSO organization. It is separate from customer organizations in your application environments.

  1. In the dashboard’s account security settings, open the setup portal link for the account’s internal organization.
  2. Configure and activate its SSO connection. Domain verification and the regular connection test still apply.
  3. As an owner, register your backup passkey and generate recovery codes.
  4. Complete a recent second factor, then turn on Enforce SSO in the account security settings.

Enabling enforcement requires an active connection, the caller’s backup passkey and unused recovery codes. A missing prerequisite returns sso_not_ready. Enabling or disabling enforcement requires an owner and recent verification.

With enforcement enabled, ordinary non-SSO sign-in is refused with sso_required. Owners’ backup passkeys and recovery codes remain the recovery path. This does not claim that enabling enforcement terminates existing sessions or your application’s sessions.

The credential API lists and renames your passkeys and TOTP credentials. Removing a credential requires recent verification and preserves the last usable backup passkey of an owner. Session listing and revocation are separate operations: revoke a session to end it immediately, including a CLI credential family.

New-account sign-up requires the configured challenge and refuses disposable email domains. email_disposable asks for an address you keep; sign_up_paused means try later. Standby sign-ups are paused and primary sign-ups pause when the challenge is unavailable. Existing-account sign-in remains separate. See abuse controls and standby behavior.