Skip to content

Web identity: OIDC login, sessions, members and invitations

The server authenticates machines with API keys (Authorization: Bearer dx_…) and people with an OpenID Connect login against any provider the deployment trusts. A person gets a server-side session in an HttpOnly cookie; what it may do comes from its membership in an organization, with one of the six roles of the permission matrix (roles and permissions).

SAML, SCIM, per-organization issuers, domain verification and group → role mapping come later (T49). Passwords, MFA and account recovery are the provider's job.

How it works

  1. GET /auth/login?issuer=<id>&redirect=/path starts the authorization code flow with PKCE S256. state, nonce and the code_verifier travel in a signed, 10-minute cookie (__Host-dx_oidc). redirect must be a relative path of this site; anything else becomes /.
  2. The provider sends the browser back to GET /auth/callback. The server checks state, exchanges the code (with the verifier and the client secret) and validates the id_token: algorithms RS256, ES256 and EdDSA only (none and HS* are refused before any key is used), exact iss, aud = the client id, exp, nonce, 60 s of leeway for nbf/iat. Keys come from the provider's JWKS (cached 10 minutes, at most one refresh per minute for an unknown kid). A wrong state or nonce answers 400 without creating a session; any other invalid token answers 401 invalid-token.
  3. The user is identified by (issuer, subject). The same email at two providers is two users, unless both providers are trusted to join accounts by a verified email (Google, Microsoft with xms_edov, sign-in links; "link_by_email": true for another issuer): see self-service sign-up, which also covers Google, Microsoft Entra and sign-in links by email.
  4. The server creates a session and sets two cookies:
Cookie Attributes Content
__Host-dx_session HttpOnly; Secure; SameSite=Lax; Path=/, no Domain 32 random bytes; the database stores only their HMAC-SHA256
dx_csrf Secure; SameSite=Lax; Path=/ (readable by JavaScript) HMAC(csrf_secret, session id)

Any session the browser already had is destroyed (no session fixation). 5. Sessions expire after 8 hours of inactivity and 7 days in any case. last_seen_at is written at most once a minute. POST /auth/logout destroys the session.

CSRF

Every POST, PUT, PATCH and DELETE authenticated by the session cookie must send the value of dx_csrf in the X-DX-CSRF header (403 csrf-failed otherwise). When the request carries Origin, it must equal the origin of DX_PUBLIC_URL. Requests authenticated with an API key are exempt.

Organization and project in use

A session acts in one organization and one project. After login it is the user's oldest membership and its first project; POST /v1/session/context changes it. Roles restricted to some projects (project_ids) always act inside one of them, so resources of other projects answer 404.

A user without membership gets a session without organization: it may call only GET /v1/me, POST /v1/invitations/accept, POST /v1/session/context and POST /auth/logout; everything else answers 403 no-active-organization.

Members and roles

Endpoint Permission Notes
GET /v1/members member:manage keyset pages
GET /v1/members/{user_id} member:manage ETag
PATCH /v1/members/{user_id} member:manage If-Match required (428/412)
DELETE /v1/members/{user_id} member:manage sessions lose access within 5 s

Rules, each with its problem type:

  • nobody changes their own role — 403 self-role-change;
  • only an Owner grants, changes or removes an Owner or an Admin — 403 role-escalation;
  • an organization keeps at least one Owner — 409 last-owner (two Owners demoting each other at the same time: one of them gets 409);
  • only Builder, Reviewer, Viewer and Auditor can be restricted to project_ids.

Invitations

POST /v1/invitations {email, role, project_ids?, locale?} mails {DX_PUBLIC_URL}/invite?token=… (Spanish or English template). The token is 32 random bytes; the database keeps only its HMAC. Invitations last 7 days; inviting the same email again revokes the pending one; at most 50 may be pending per organization (409 invitation-limit-reached). DELETE /v1/invitations/{id} revokes one.

POST /v1/invitations/accept {token} needs a session whose email is verified by the provider and equal to the invited one (403 invitation-email-mismatch, 403 email-not-verified); an expired or revoked invitation answers 410 invitation-expired, a used one 409 invitation-already-used. If no mail can be sent, the invitation is not created (503).

The first Owner

Nobody can invite before an Owner exists:

  • DX_BOOTSTRAP_OWNER_EMAIL: the first login of that email, verified by the provider, becomes Owner of the bootstrap organization (DX_BOOTSTRAP_ORGANIZATION slug, or the only organization) while it has no Owner. An unverified email never becomes Owner.
  • python -m extractit.identity.admin grant-owner --email E [--organization SLUG] [--issuer URL]: makes an existing, verified user (it logged in once) Owner.

Organizations themselves are created with python -m extractit.store.admin provision-tenant.

Configuration

Variable Meaning
DX_OIDC_ISSUERS JSON list of {id, name, issuer, client_id, client_secret, scopes}
DX_PUBLIC_URL Browser-facing origin, e.g. https://dx.example.com (callback, invitation links, Origin check)
DX_SESSION_KEY ≥ 32 bytes; HMAC key of sessions, CSRF and the login cookie (required in production)
DX_COOKIE_SECURE true (default). false only for development over plain http: the cookie becomes dx_session
DX_SMTP_URL smtp://user:pass@host:587?starttls=true or smtps://…:465; without it mail is only logged (never the token)
DX_MAIL_FROM Sender of the invitation mail
DX_BOOTSTRAP_OWNER_EMAIL, DX_BOOTSTRAP_ORGANIZATION First Owner (see above)

DX_COOKIE_SECURE=false is for development only

A __Host- cookie needs Secure, and some browsers (Safari) refuse Secure cookies over http://localhost. The server refuses DX_COOKIE_SECURE=false when DX_ENV=production.

The redirect URI to register at the provider is {DX_PUBLIC_URL}/auth/callback.

Keycloak (self-hosted bundle)

The Compose profile idp starts Keycloak 26 with the realm dx (confidential client dx-web, PKCE S256 required, test users alice, bruno and mallory — the last one with an unverified email) and Mailpit to read the invitation mail:

docker compose -f deploy/compose/docker-compose.dev.yml -p dx-dev --profile idp up -d --wait
export DX_OIDC_ISSUERS='[{"id":"keycloak","name":"Keycloak","issuer":"http://localhost:58080/realms/dx","client_id":"dx-web","client_secret":"dx-web-dev-secret"}]'
export DX_PUBLIC_URL=http://localhost:8000 DX_COOKIE_SECURE=false

Mailpit's UI is on http://localhost:58025 (SMTP smtp://localhost:51025). The realm file and the secret are development values; a production Keycloak gets its own realm, secret and HTTPS.

Microsoft Entra ID

  1. App registrations → New registration; redirect URI (Web) https://<host>/auth/callback.
  2. Certificates & secrets: create a client secret.
  3. Token configuration: add the optional claim email.
  4. Issuer: https://login.microsoftonline.com/<tenant-id>/v2.0 (a single tenant; the common endpoint is not supported because its issuer does not match the discovery document).

Entra ID does not send email_verified by default: such users can log in but can neither accept invitations nor become Owner. Put Keycloak in front as a broker for the trusted Entra tenant (its identity-provider mapper can mark the brokered email as verified), or use a provider that sends email_verified.

Okta

  1. Applications → Create App Integration → OIDC → Web Application, grant type Authorization Code, PKCE required; sign-in redirect https://<host>/auth/callback.
  2. Issuer: https://<org>.okta.com (org authorization server) or https://<org>.okta.com/oauth2/default.
  3. Scopes openid email profile; Okta sends email_verified.

Security notes

  • Issuers are deployment configuration: the discovery URL never comes from a user, so there is no SSRF surface. Endpoints must use HTTPS (localhost excepted).
  • Sessions and invitations are looked up before the organization is known, through SECURITY DEFINER functions (auth_lookup_session, auth_lookup_invitation, …) with a fixed search_path that return at most one row; the service role has no privilege on the sessions table at all. Users are visible only through a membership in the current organization (RLS).
  • Logs never contain session ids, CSRF values, authorization codes, tokens or invitation tokens.