Authentication Security¶
This page is the operating contract for browser sessions, API tokens, federation, WebAuthn, and authentication recovery.
Authentication classes¶
| Class | Transport | Lifetime | Server-side control |
|---|---|---|---|
| UI access | Host-only HttpOnly, Secure, SameSite=Lax cookie |
5 minutes | auth_sessions is checked on every request. |
| UI refresh | Host-only HttpOnly, Secure, SameSite=Lax cookie, /api/auth path |
12 hours idle, 7 days absolute | Single-use token families; replay revokes the entire family. |
| Direct S3 session | Same browser cookie contract | 30 minutes idle, 8 hours absolute | Revocation or expiry erases the stored S3 credentials. |
| API token | Authorization: Bearer |
30 days by default, 90 days maximum | Token hash, authentication version, expiration, revocation, and scopes are checked in the database. |
| Pre-authentication | Short HttpOnly cookie |
5 minutes | Only WebAuthn enrollment, WebAuthn authentication, or recovery-code completion is allowed. |
Browser requests must never send a Bearer token. A request containing both a UI cookie and a Bearer is rejected. Mutating cookie-authenticated requests require the exact configured Origin and a CSRF value bound to the session. Authentication responses use Cache-Control: no-store.
GET /api/auth/session is the browser identity source. Access and refresh tokens are never returned in UI login, LDAP, S3, OIDC, or refresh response bodies and must not be stored in localStorage or sessionStorage.
WebAuthn and recovery¶
Passkey enrollment is controlled by AppSettings.general: both require_passkey_for_admins and require_passkey_for_users default to false on a fresh installation. Direct S3 sessions are excluded. Any user who voluntarily enrolls a passkey is challenged on subsequent logins as well. Before production, an administrator should enroll a passkey from Profile > Security, then enable Require passkeys for administrators in Authentication settings; the Production readiness report remains Critical until that policy is enabled, but the backend remains available for remediation. Enabling a requirement takes effect at the next authentication and does not terminate existing sessions. Upgrades preserve an explicitly persisted historical Admin requirement, including the value canonicalized by migration 0130. The RP ID and origin must exactly match the configured WebAuthn origins and RP ID; user verification is required, attestation is none, and challenges are single-use for five minutes.
After enrollment, ten recovery codes are displayed once. Store them outside the browser. Each code is hashed in the database and can be consumed once. Admin revalidation follows a balanced action-based policy. Security inventories, link-request lists, authentication details, and API-token lists require an interactive Admin session but not recent WebAuthn. Defensive actions that only remove access—rejecting a link request, revoking a session, or revoking an API token—also use the active interactive session, while preserving authorization, confirmation, and audit controls.
When require_passkey_for_admins is enabled, access-creating or security-changing actions require WebAuthn verification from the last MFA_RECENT_MINUTES (15 minutes by default). These actions include approving an identity link, adding, revoking, or restoring an external identity, resetting MFA, setting a password, creating an API token or UI user, deleting a UI user, changing a user's identity, role, activation, privileges, Manager tools, or associations, changing authentication options or passkey requirements, and creating, updating, or deleting OIDC/LDAP providers. An unchanged normalized payload and a user full-name-only update do not require step-up. When the policy is disabled, these critical direct actions still require an authorized interactive Admin session but not recent WebAuthn. Personal security actions use a recent primary authentication when no passkey is enrolled or required; an enrolled or required passkey keeps the WebAuthn step-up. Revoking an external identity invalidates every UI session and API token owned by that user.
When that freshness window expires, a critical action offers an in-session
passkey verification without locking the surrounding page. The challenge is bound to the current
UI session; successful verification updates that session's mfa_verified_at
without issuing new access or refresh tokens, then retries the protected request
once. MFA_RECENT_MINUTES remains the backend source of truth, and recovery
codes do not satisfy this WebAuthn freshness requirement.
Emergency recovery is restricted to the sole active superadmin:
The command requires the exact typed confirmation, removes passkeys, recovery codes, and pending challenges, increments auth_version, revokes every session and API token, and writes a secret-free audit event. The next login follows the current role policy. The sole active superadmin can be recovered only with this operator command.
Prefer an explicitly issued one-time web bootstrap on an empty database:
The 256-bit token expires after 15 minutes, is stored only as a SHA-256 digest,
travels in the URL fragment and then in X-BucketReef-Bootstrap-Token, and is
consumed atomically with creation of the sole first super-administrator. On a
fresh installation the response creates the authenticated Admin session
directly. If the Admin passkey policy is already enabled, bootstrap instead
continues through the five-minute pre-authentication enrollment flow.
Use the interactive CLI as an independent fallback:
cd backend
python -m app.scripts.create_first_admin --email exact-admin@example.com --full-name "Platform Admin"
No automatic or default administrator exists in any environment. Initial setup closes permanently as soon as any user exists; recovery of an existing administrator is a separate operator action. The CLI reminds the operator to enroll a passkey and enable the Admin passkey policy before production.
Federation¶
- OIDC always uses PKCE S256 and nonce. Discovery, authorization, token, JWKS, issuer, and optional UserInfo endpoints must be HTTPS and use an allowed host. ID tokens require a
kid, an asymmetric signing key, an explicitly allowed algorithm (RS256by default), the configured issuer and audience, andemail_verified is truebefore an email is used. - OIDC discovery, token, JWKS, and UserInfo requests reject HTTP redirects. Configure the provider's final HTTPS endpoint directly; this prevents redirects from forwarding client credentials or access tokens to an untrusted destination.
- LDAP production providers require LDAPS or StartTLS, certificate verification, modern TLS, escaped filters, and bounded timeouts.
- Admin UI user creation can pre-provision an LDAP identity. Directory search results carry a short-lived selection token bound to the administrator, UI session, authentication version, provider, subject, and DN. The import action re-reads the selected DN before changing the database and requires the immutable
(provider_id, subject)identity to match. A directory email is profile data only: matching an existing BucketReef email requires an explicit link action, and a missing or invalid LDAP email can be replaced with a valid BucketReef profile email when creating the user. Linking or restoring an identity preserves the existing user's profile, role, privileges, active state, and local password, incrementsauth_version, and invalidates that user's UI sessions and API tokens. - New UI-managed OIDC and LDAP providers default to
linking_policy=reauthenticate. Environment-managed providers keep the conservativemanualdefault unlessLINKING_POLICYis set explicitly, and existing providers retain their configured policy. The incoming provider identity is validated first: OIDC completes its signed callback checks, while LDAP verifies the submitted directory credentials and immediately discards the password. If that identity collides with an existing BucketReef email,reauthenticatestarts a short-lived browser-bound transaction and requires proof of the existing account with its local password, an already-linked LDAP identity, or an already-linked OIDC identity. OIDC proof forces a fresh provider authentication (max_age=0) and validatesauth_time. Any applicable passkey requirement is enforced before the user explicitly confirms the link. Successful confirmation invalidates the user's previous UI sessions and API tokens, creates a replacement UI session, and posts an identity-change notification. If the user cannot complete account proof, the same transaction can be submitted for administrator approval. Withmanual, the validated incoming identity enters the same browser-bound transaction but proceeds directly to administrator review. - In
trusted_emailmode, BucketReef links only a verified email in an exact configured domain to one active standard local-password account that has no active or revoked external identity. Privileged, inactive, already federated, unverified, out-of-domain, or unsafe matches fall back to administrator approval. Unknown emails keep the existing JIT behavior and create aui_noneaccount. - Admins decide requests only for standard users; Superadmins can also decide requests for privileged accounts. OIDC identity is immutable by
(issuer, subject)and does not depend on the local provider configuration name; LDAP identity remains keyed by(provider_id, subject). Subjects are not written to audit metadata. A UserInfo response must carry the samesubas the validated ID token. - External identity link attempts expire after
EXTERNAL_IDENTITY_LINK_ATTEMPT_TTL_SECONDS(10 minutes by default), are bound to theHttpOnlycookie named byEXTERNAL_IDENTITY_BROWSER_COOKIE_NAME, and are one-time transactions. The issuer-binding cutover removes pre-cutover OIDC identity mappings because they do not contain a trustworthy issuer, invalidates affected sessions and API tokens, and lets the next OIDC login use the normal secure account-link collision workflow. LDAP identities are preserved. - Every new manual link request, and every request reopened after expiry, creates one warning in the notification center for each active administrator allowed to decide it. An unchanged pending request is not repeated; privileged targets notify Superadmins only.
The canonical administration routes are /api/admin/identity/link-requests, /api/admin/identity/sessions, and /api/admin/users/{id}/security. The former global routes under /api/auth are not aliases. Direct identity and critical security routes require a browser-backed UI session and reject Bearer tokens. No Bearer-token exception is exposed for direct identity or critical security mutations.
API-token scopes¶
Every token contains and persists one or more exact scopes. The UI/storage domains support read and write: profile, admin, manager, browser, portal, ceph-admin, and storage-ops. A read scope never authorizes a mutation. Routes without an explicit mapping reject API tokens by default.
Changing a user's password, email, role, activation, MFA, or external identity increments users.auth_version and immediately invalidates sessions and API tokens. Logout, global logout, refresh replay, explicit session revocation, and expiry are also database-enforced.
Upgrade history¶
The destructive authentication cutover performed by migrations 0107 through
0110, including its backup gate and rollback procedure, is documented in
Upgrade compatibility.
Key rotation¶
- JWT rings verify every listed key and sign with the first. Add a new first UI key, wait beyond the maximum five-minute access-token lifetime, then remove the old UI key. Removing an API key invalidates API tokens signed by it; coordinate recreation or retain the previous key until their planned retirement.
- Credential rings decrypt with every listed key and encrypt with the first. Re-encrypt persisted credentials before removing an old key.
- Refresh values and recovery codes are opaque and hashed; rotate them through session renewal or regeneration, not by changing JWT keys.