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
GET /auth/login?issuer=<id>&redirect=/pathstarts the authorization code flow with PKCE S256.state,nonceand thecode_verifiertravel in a signed, 10-minute cookie (__Host-dx_oidc).redirectmust be a relative path of this site; anything else becomes/.- The provider sends the browser back to
GET /auth/callback. The server checksstate, exchanges the code (with the verifier and the client secret) and validates theid_token: algorithmsRS256,ES256andEdDSAonly (noneandHS*are refused before any key is used), exactiss,aud= the client id,exp,nonce, 60 s of leeway fornbf/iat. Keys come from the provider's JWKS (cached 10 minutes, at most one refresh per minute for an unknownkid). A wrongstateornonceanswers 400 without creating a session; any other invalid token answers 401invalid-token. - 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 withxms_edov, sign-in links;"link_by_email": truefor another issuer): see self-service sign-up, which also covers Google, Microsoft Entra and sign-in links by email. - 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_ORGANIZATIONslug, 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
- App registrations → New registration; redirect URI (Web)
https://<host>/auth/callback. - Certificates & secrets: create a client secret.
- Token configuration: add the optional claim
email. - Issuer:
https://login.microsoftonline.com/<tenant-id>/v2.0(a single tenant; thecommonendpoint is not supported because itsissuerdoes 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
- Applications → Create App Integration → OIDC → Web Application, grant type
Authorization Code, PKCE required; sign-in redirect
https://<host>/auth/callback. - Issuer:
https://<org>.okta.com(org authorization server) orhttps://<org>.okta.com/oauth2/default. - Scopes
openid email profile; Okta sendsemail_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 DEFINERfunctions (auth_lookup_session,auth_lookup_invitation, …) with a fixedsearch_paththat return at most one row; the service role has no privilege on thesessionstable 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.