Keen documentation
Open Keen ↗

Developing Keen

Identity, MFA and security notifications

Chapter 2 of 6

Identity, sessions and authorisation

Three authorities sign people in: local passwords with optional MFA, identity providers through OIDC, and trusted-header authentication. All of them resolve to an application user whose permissions are decided on the server, every request.

Browser sessions are stored in Valkey and referenced by an HttpOnly cookie. Roles are admin, normal or inherit; inherited roles come from groups, and permissions combine direct and group grants. Sessions cache an authorisation snapshot and a version, so access-changing operations must bump the affected versions for later requests to recompute permissions. A cache miss must never become an allow decision.

A new route needs two checks. The middleware enforces namespace and write permissions, with an admin-only fallback for unrecognised writes; the domain operation enforces precise permissions and relationship rules. Hiding a button is insufficient.

OIDC and hosted mode

OIDC uses state, nonce and PKCE, a single-use login-state record, token exchange and signature, issuer, audience and expiry validation. Identity links use issuer and subject; general deployment settings control auto-link and provisioning, and an account is never authorised simply because a supplied e-mail looks familiar.

Going deeper: dedicated hosting and CSRF

The dedicated-hosting integration adds security/hosted.py and bootstrap_hosted.py. Hosted mode requires the configured issuer and owner subject, restricts existing sessions to the owner and disables alternative local and header sign-in paths; bootstrap creates or binds the owner deliberately, and tenant identity checks apply before normal OIDC user resolution even with an Auth0-side action.

Cookie-based writes use the CSRF cookie/header check, and hosted mode additionally checks the exact origin, including WebSocket origins. Webhooks use their own authentication and remain separately protected. Keep cookies host-only, so a parent domain shared by customers never receives them. Host-only Secure cookies, the CSRF cookie included, carry the __Host- prefix; the shared API helpers read the prefixed CSRF cookie first.

Local MFA authentication boundary

Password verification never produces a session on its own when MFA is enrolled or required. It produces a short-lived pending challenge, and only a verified second factor turns that into an application session.

The pending challenge lasts five minutes and is opaque: the browser receives an HttpOnly, SameSite=Strict cookie, and the database stores the token hash, user, purpose, stage, credential-version snapshot, password-hash digest and expiry. It never enters the application-session namespace and cannot authorise API access or WebSocket handshakes. Successful verification consumes it before a fresh local session is issued.

Sessions carry the user's MFA version and verification state; password and factor changes invalidate older local sessions at subsequent authentication checks, while SSO sessions are governed separately. Account and operator changes write MFA audit entries without storing submitted codes or secrets.

Going deeper: factor management, WebAuthn and tests

Factor management starts with fresh password verification and an existing factor when enrolled. All MFA POSTs enforce the configured exact Origin, verification rate limits fail closed when Valkey is unavailable, database row locks serialise factor changes and recovery-code consumption per user, and TOTP verification accepts a narrow clock window and rejects a previously accepted time step.

WebAuthn registration and authentication use the maintained Python webauthn verifier, checking challenge, RP ID, origin, user presence, signatures and counters, and rejecting cross-origin ceremonies and mismatched user handles. User verification is preferred: the local password supplies the first factor, and a security key without a biometric or PIN can supply the second. Attestation is not used to restrict hardware vendors.

The database stores user MFA state, encrypted TOTP secrets, WebAuthn credentials, recovery hashes and pending challenges. tests/test_local_mfa.py exercises PostgreSQL persistence, TOTP and recovery replay, origin and expiry handling, policy, session revocation and cryptographically signed WebAuthn ceremonies; hardware and browser interoperability belongs in deployment acceptance testing.

MFA presentation selects a registered key by default and remembers a successful normal factor per account and browser. Verification completion finishes a login automatically, management ceremonies stay on the security settings screen, enrolment requires explicit recovery-code acknowledgement, and recovery codes are never remembered as the preferred method.

Security email outbox

Security notifications use a unique user/IP history and a database outbox. Successful local and native SSO session issuance records the canonical client IP using an atomic INSERT ON CONFLICT, and account mutations enqueue their change alert in the same transaction. Celery beat schedules security_notifications_task; workers claim due rows using FOR UPDATE SKIP LOCKED, record delivery or bounded retry state, and avoid logging SMTP exception messages.