Skip to content

depictio — authentication and access modes (audit for Spectio)

Source: depictio checkout scratchpad/dep, v1.19.2 (commit 0d1aa0a, 2026-10-23). Read on 2026-10-26.

Paths are relative to dep/depictio/ unless they start with docs/ or packages/. Short names:

  • routes.py is api/v1/endpoints/user_endpoints/routes.py;
  • core.py is api/v1/endpoints/user_endpoints/core_functions.py;
  • settings is api/v1/configs/settings_models.py.

[inf] marks an inference that was not tested by running the code.

1. Configuration surface (AuthConfig, settings:412–730, env prefix DEPICTIO_AUTH_)

Setting Default Effect
keys_dir, keys_algorithm (RS256/RS512/ES256/SHA256) generated keys JWT signing (§7)
internal_api_key_env auto-generated service-to-service key (§8)
provisioning_api_key_env unset → feature off pipeline provisioning gate (§5); never auto-generated (settings provisioning_api_key property)
magic_link_expiry_minutes 15 magic-link ticket TTL (settings:436)
single_user_mode false §2.1
public_mode (alias unauthenticated_mode) false §2.3
demo_mode false §2.4
registration_disabled false blocks /register and SSO auto-creation
password_login_disabled false blocks password login, only if Google or SAML is enabled (is_password_login_disabled, settings ~688)
public_access_code (SecretStr) none shared code gating public mode (§2.3)
anonymous_user_email anonymous@depict.io anonymous identity
temporary_user_expiry_hours/minutes 24 / 0 guest lifetime
google_oauth_* off §6.1
saml_* (entity IDs, SSO URL, cert, NameID format, attribute names for email/username/groups/title/display name/login, saml_login_label) off §6.2
  • Env parsing. The modes are re-read from raw env vars in __init__ (settings:596–640), because nested BaseSettings miss them otherwise.
  • Public discovery. GET /auth/me/optional (routes.py:619–742) tells the SPA everything in one call, without a token:
    • auth_mode (single_user | unauthenticated | standard);
    • the mode flags, the effective password_login_disabled, and public_access_code_required (never the code itself);
    • google_oauth_enabled, saml_enabled, saml_login_label, the temp-user expiry;
    • feature flags.

2. Instance modes

2.1 Single-user mode

  • Seeding. Bootstrap seeds a local admin (admin@example.com, random password never logged) when no admin exists (api/v1/db_init.py:785–800).
  • Login. /auth/login returns a token for that admin with no credentials checked (routes.py:185–195).
  • Data endpoints fall back to the anonymous user when no token is sent (get_user_or_anonymous, routes.py:124–157).
  • Anonymous session. GET /auth/public/get_anonymous_user_session is enabled only in this mode and is rate-limited (routes.py:985–1009).
  • Disabled here: /register (routes.py:1043), provisioning and magic links (_require_magic_link_enabled, routes.py:312–324).
  • CLI config generation is limited to the admin (routes.py:1435–1444).
  • UI: the SPA shows "Starting your session" (viewer/src/auth/AuthApp.tsx:139).

2.2 Standard mode (accounts)

  • Password login. POST /auth/login (OAuth2 password form):

    • per-IP rate limit (routes.py:181);
    • bcrypt check (core.py:750–778);
    • issues a short-lived session (routes.py:206–222).

  • Registration. POST /register (routes.py:1012–1087):

    • refused in single-user or public mode, when registration_disabled is set, and when password login is disabled;
    • rate-limited;
    • never honours a client-sent is_admin;
    • every failure returns the same generic error, so accounts cannot be enumerated (routes.py:1006–1010).

  • Admin-created accounts. POST /auth/admin/create_user with must_change_password (routes.py:1089–1140). The flag is returned by /me/optional and cleared on password change (core.py:686).

  • Password change: POST /auth/edit_password (routes.py:1191).

2.3 Public mode (guests)

  • Guest sessions. POST /auth/public/create_temporary_user (routes.py:948–983):

    • only in public mode (404 otherwise);
    • rate-limited before the access-code check, so the code cannot be brute-forced faster than other credentials;
    • verifies public_access_code in constant time (settings verify_public_access_code, ~667–675).

  • Temporary users. Each guest gets a fresh user temp_user_<8 hex>@depictio.temp with a random bcrypt password and is_temporary=True, expiring after 24 h by default (core.py:104–141).

  • Sliding expiry. Every refresh re-arms the expiry (_rearm_temporary_user_expiry, routes.py:261–278), so an active visitor never lapses. Abandoned sessions stop after the refresh token's 7-day lifetime.
  • Clean-up. Expired guests are deleted by a periodic task (api/v1/tasks/cleanup_tasks.py:53, core.py:195).

  • UI.

    • With a code: PublicAccessGate.tsx, "Enter the access code", field "Access code".
    • Without one: "Starting a guest session" (AuthApp.tsx:131,139).
    • Guests are flagged is_temporary so the SPA can offer a real sign-in.

  • Elsewhere. Monitoring and backups are hidden in public mode, and so is CLI config for non-admins (routes.py:1435).

2.4 Demo mode

  • demo_mode adds a guided tour on top of public mode (settings is_demo_mode).
  • The property returns demo_mode alone. [inf] Demo mode on its own does not imply is_public_mode; deployments set both. The e2e test tests/e2e-playwright/tests/public/demo-mode.spec.ts exists.
  • DEPICTIO_WALKTHROUGH_DISABLED and DEPICTIO_DEV_MODE suppress the tour (routes.py in /me/optional).

3. Sessions and tokens (JWT)

  • Model. TokenData is name, token_lifetime ∈ short-lived / long-lived / permanent, token_type ∈ bearer / custom, and sub = user ObjectId (models/models/users.py:12–53).
  • Signing. JWTs are signed with the configured private key (utils.py:119–142, get_private_key). The claims are the TokenData fields plus exp.
  • Verification. It pins algorithms=[ALGORITHM] and requires exp (core.py:416–440). The token must then also exist in TokenBeanie, which makes revocation possible (core.py:454).
  • Lifetimes (_add_token, core.py:697–745):
Kind Access token Refresh token Issued by
short-lived 1 h 7 days login, Google, magic-link exchange, single-user login
long-lived 1 year 1 year + 7 days CLI tokens POST /auth/me/tokens (routes.py:1260–1300), pipeline provisioning
permanent JWT exp 1 year, stored expiry datetime.max, no refresh — API only
  • Refresh. POST /auth/refresh (routes.py:392–443) is browser-safe: the refresh token is the only credential, and it returns a new 1-hour access token. No rotation and no reuse detection: an explicit TODO(PR2) says a leaked refresh token grants indefinite access (routes.py:413–420).
  • Browser storage. The session is kept in localStorage (persistSession, packages/depictio-react-core/src/api.ts:3953). A bearer header means there is no CSRF surface, but XSS can read the token.
  • Logout only removes the client copy; the code comment says "there is no server-side revocation" (api.ts:3962–3966). DELETE /auth/me/tokens/{id} revokes CLI tokens (routes.py:1304).
  • Storage. Tokens (access and refresh JWTs) are stored in clear in TokenBeanie for lookup [inf from find_one({"access_token": token})].

  • Model (models/models/users.py:153–183): MagicLinkTicket holds ticket (secrets.token_urlsafe(32)), user_id, expire_datetime, used, created_at.

    • The ticket has a unique index and a Mongo TTL index on expire_datetime, so used and expired tickets disappear without a clean-up job.
    • The ticket is stored in clear, not hashed.

  • Mint. POST /auth/me/magic_link (routes.py:360–383):

    • bearer-authenticated, so the caller is the user the link logs in;
    • TTL magic_link_expiry_minutes (15);
    • returns {ticket, expire_datetime, login_url} with login_url = <viewer>/auth/magic#ticket=….

  • Redeem. POST /auth/magic/exchange (routes.py:385–389, core.py:936–985):

    • rejects missing, used or expired tickets with 401;
    • sets used=True, then mints a short-lived session for the ticket's user;
    • the burn is find_one then save(), not an atomic find-and-update. [inf] Two concurrent redemptions can both succeed.
    • No rate limit on this endpoint. The 256-bit secret makes guessing impractical.

  • Delivery.

    • There is no email sending anywhere (no SMTP or mail settings; a grep for smtp/mail found only a sandbox blocklist).
    • The link is printed by the CLI at the end of depictio ingest --user (cli/cli/commands/run.py:2750–2761, utils/api_calls.py:129), with &next=/dashboard/<id> appended.
    • SAML reuses the same mechanism internally (§6.2).
    • There is no "email me a sign-in link" form in the UI.

  • Scope. The ticket logs in as the full user, with no resource or role restriction. The resulting session is a normal one.

  • Browser side (viewer/src/auth/components/MagicLinkCallback.tsx):

    • reads the ticket from the fragment, so it stays out of server logs and Referer;
    • strips it from history immediately;
    • POSTs the exchange;
    • restricts next to a same-origin path (safePostAuthTarget, postAuthTarget.ts).

  • Link scanners. Because the ticket sits in the fragment and needs a JS POST, email or chat link scanners doing GET prefetch cannot consume it [inf].

  • Off in single-user mode (routes.py:312–324).

5. Pipeline provisioning (passwordless accounts)

Documented in docs/pipeline-provisioning-magic-link.md.

  1. Configure. Set DEPICTIO_AUTH_PROVISIONING_API_KEY and DEPICTIO_VIEWER_PUBLIC_URL. TLS is required.
  2. Provision. POST /auth/provision_user with header api_key and body {email} (routes.py:327–357). It is off in single-user mode and returns 503 when no key is configured, 403 on a wrong key (routes.py:296–309).
  3. What it creates. _provision_user (core.py:872–912) creates or gets the user with an empty password (unusable), and reuses a long-lived token named pipeline_provision while it has more than one day left. It is idempotent.
  4. Run as the user. The CLI writes a temporary 0600 CLI config, runs the ingest as the user, then mints a magic link as the user at the end, so the 15-minute clock starts when the link is handed out.

  5. Security model (doc):

    • the key is an instance gate against bots, not isolation between users;
    • the link carries only the single-use ticket, and the session is minted at click time.

  6. Gaps.

    • The provisioning key is compared with != (routes.py:307), not in constant time, unlike internal_api_key (routes.py:89–99, hmac.compare_digest).
    • The endpoint is not rate-limited.
    • Anyone holding the key can mint a one-year token for any email, including an existing admin's [inf: _provision_user returns the existing user without checking is_admin].

6. Single sign-on

6.1 Google OAuth (api/v1/endpoints/auth_endpoints/google_oauth_routes.py)

  • Start. GET /auth/google/login returns {authorization_url, state} (:37–78). The state comes from a Redis-or-memory store with a 600 s TTL and atomic consume (state_store.py:23,61).

  • Callback. GET /auth/google/callback?code&state (:81–180):

    • validates the state (CSRF), exchanges the code, fetches userinfo;
    • creates or gets the user with allow_create = not registration_disabled;
    • syncs the avatar and returns a short-lived session as JSON. The SPA route GoogleOAuthCallback.tsx performs the call.
    • No PKCE parameter is visible in the login URL [inf from :62–75].

  • Tests: 17 in tests/api/v1/endpoints/auth_endpoints/test_google_oauth.py.

6.2 SAML 2.0 (saml_routes.py, saml_utils.py; extra depictio[saml] = python3-saml)

  • SP-initiated login. GET /auth/saml/login?next= (saml_routes.py:58–81):

    • next is constrained to a same-origin path (safe_relay_path, saml_utils.py:47–51, which rejects //);
    • the relay is stored server-side, keyed by the AuthnRequest ID, so the IdP-echoed RelayState is never trusted.

  • ACS. POST /auth/saml/callback (:84–146):

    • consumes the stored request ID, which rejects replays and unsolicited responses;
    • validates with strict: True and wantAssertionsSigned: True (saml_utils.py:61,83);
    • resolves the email from the configured attribute, falling back to the NameID, lower-cased (saml_utils.py:151–160);
    • creates or gets the user (respecting registration_disabled) and syncs groups and profile;
    • issues a 2-minute magic-link ticket and redirects 303 to /auth/magic#ticket=…&next=….

    The session is therefore never in a URL or form post.

  • Metadata: GET /auth/saml/metadata serves the SP metadata (:149).

  • Group sync (sso_sync.py:22–168):

    • groups named in the saml_attribute_groups attribute (e.g. memberOf) are created with sso_managed=True and the user is added;
    • the user is removed from every sso_managed group not asserted, including admin_ids, and pi_id is cleared;
    • manual groups are never touched;
    • title, display name and login are refreshed;
    • pending P.I. claims run on login (groups_endpoints/pending_pi.py);
    • a sync failure never blocks the login.

  • Tested against Keycloak in dev/dev_fastapi_saml/app.py. Unit tests: 22 in test_saml.py, 13 in test_sso_sync.py, 9 in test_auth_state_store.py. No Keycloak job runs in CI [inf: no keycloak match under .github/].

  • UI (viewer/src/auth/components/SignInProviders.tsx):
    • the SAML button comes first (saml_login_label, default "Sign in with SSO"), then "Sign in with Google";
    • when password login is disabled the form says "This instance signs in with Google." (LoginForm.tsx:224–245).

7. Keys

  • RSA (or EC) key pair in keys_dir, generated on first boot (api/v1/key_utils.py). Kubernetes takes them from a Secret (kubernetes/multiline-secrets.yaml: AUTH_PUBLIC_KEY, AUTH_PRIVATE_KEY).
  • The token comment notes that keys from a different deployment cause "Signature verification failed" (core.py:448–451).
  • keys_algorithm accepts SHA256, which is not a JWT signing algorithm [inf: probably unused].

8. Service-to-service and the CLI

  • internal_api_key.

    • Auto-generated and persisted with the keys unless set by env.
    • Compared in constant time (routes.py:89–99).
    • Used by deprecated server-side routes (/create_temporary_user, /refresh_token, temp-user clean-up).

  • CLI tokens. POST /auth/me/tokens creates a named long-lived token (routes.py:1260–1300). POST /auth/generate_agent_config returns a CLI config that includes the S3 root secret (routes.py:1422–1447), restricted to admins in single-user, public and demo modes.

  • Rate limiting (user_endpoints/rate_limit.py):
    • Redis fixed window of 10 calls per 60 s per (IP, endpoint);
    • fail-open when Redis is down;
    • the client IP is taken from X-Real-IP (trusted proxy header). If the API is reachable without the proxy, that header can be spoofed to dodge the limit [inf].
    • Applied to login, register, temp-user creation and the anonymous session. Not applied to magic exchange or provisioning.

9. Tests that exist

Area Unit / API tests Playwright e2e (tests/e2e-playwright/tests/)
Password login, register, edit password, logout, session expiry and refresh, token login user_endpoints/test_routes.py, test_user_management.py, test_admin_create_user.py auth/auth-ui-login, auth-ui-registration, edit-password, logout, session-expiry, session-refresh, token-login
Single-user — auth/single-user-mode.spec.ts
Public, demo — public/public-mode.spec.ts, public/demo-mode.spec.ts
CLI configs test_agent_config_utils.py auth/cli-configs.spec.ts
Provisioning + magic link test_provisioning.py (9: blocked in single-user, passwordless create, idempotent, ticket create, redeem burns, replay rejected, expired rejected, unknown rejected) none
Google OAuth test_google_oauth.py (17) none
SAML + SSO sync test_saml.py (22), test_sso_sync.py (13) none (manual Keycloak dev app)

10. Parity table for Spectio

Mode depictio behaviour Spectio equivalent (proposal) Gaps / risks to fix in Spectio
Single-user anonymous fallback maps to the seeded local admin; no login UI; provisioning and magic links off auth: single; local requests map to the one user; bind to 127.0.0.1 by default depictio admits anonymous requests from any host that can reach the port (its own risk note on shared login nodes): require localhost binding, or a token, when not on loopback
Standard (password) bcrypt, per-IP rate limit, generic register errors, registration_disabled, password_login_disabled only when SSO exists, admin-created users with must_change_password auth: local, same flags and semantics, same field names add an account lockout or back-off per account, not just per IP; Argon2id or bcrypt
Public / guests temporary users with sliding 24 h expiry, optional constant-time public_access_code, clean-up task auth: public for demo instances only (read-only by default; no launches for guests) guests should never launch runs or decide gates; cap guest count
Demo public + guided tour same flag, for the staging instance —
Magic link (sign-in) 256-bit ticket, 15 min, single use, fragment delivery, JS POST exchange, safe next; minted only by the user's own bearer (CLI, SAML); no email; full-user scope (a) email sign-in link ("send me a link") through the email notifier; (b) CLI or end-of-run link like depictio; (c) scoped share link (one run or gate, a role, an expiry) for reviewers and PR previews store only a hash of the ticket; atomic burn (UPDATE … WHERE used = false); rate-limit mint and exchange; add a "Continue" confirm step for email links in case scanners run JS; bind to the requesting browser optionally; a scope claim in the session
Pipeline provisioning shared provisioning_api_key → create-or-get passwordless user + 1-year token; CLI ingests as the user and prints a login link service account with scope principals:provision (no shared instance key); provisioned principals get run-scoped tokens (expire with the run); login link via magic link constant-time compare; rate limit; never provision or impersonate admins; audit every provision; shorter tokens
Google OAuth code flow, state store with TTL, allow_create respects registration_disabled, avatar sync generic OIDC plugin (Google, EMBL SSO, LS Login, Keycloak) with PKCE and nonce depictio has no generic OIDC and no PKCE visible
SAML SP-initiated, strict, signed assertions, server-side relay by request ID, 2-min ticket to fragment, memberOf group sync with sso_managed SAML plugin with the same keys and behaviour (api-and-data-model.md §13) also accept IdP-initiated only if explicitly enabled; add a CI job with Keycloak (depictio has none)
depictio trust — accept depictio JWTs (RS256 public key or /auth/me), principal link depictio:user/<id> key distribution and rotation
CLI and API tokens named long-lived (1 year) JWTs; agent config includes the S3 root secret named, scoped, expiring tokens; device-code login; no storage secrets in config refresh rotation with reuse detection (depictio TODO); hashed token storage; server-side logout
Sessions in the browser localStorage bearer + refresh (1 h / 7 d), no server-side logout HttpOnly SameSite=Lax session cookie for the UI with CSRF token on writes; bearer for API/CLI XSS token theft risk in depictio's model
Service-to-service internal_api_key (auto-generated) service accounts and runner tokens per environment no single shared instance key