Files
windmill/docs/auth-surface.md
T
45f256a5a1 feat: accept MCP access tokens from an external OIDC issuer (#12085)
* feat: accept MCP access tokens from an external OIDC issuer

With the mcp_external_idp instance setting, every MCP URL also accepts an
access token of an external OIDC issuer, told apart from Windmill's own
by its iss. The token's OAuth client is mapped to a workspace and a
selection of tools; the request acts as the existing Windmill user with
the token's email, under that selection. Runs record the client in
mcp_client and give it to steps as WM_MCP_CLIENT; tool calls and
refusals are audited with both identities.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: harden external MCP token verification

Refuse ID tokens, tokens before their nbf, and emails the issuer marks
unverified; let a cached signing key expire so a withdrawn key stops
verifying; fall back to the token's asymmetric alg for keys published
without one; reject clients configured without an issuer or with an id
longer than the column recording it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: refuse deactivated accounts and untyped tokens on external MCP auth

Read password.disabled, since instance deactivation has no Windmill
token to revoke on this path. Without a configured audience, take only
tokens typed as access tokens (at+jwt header or a Bearer typ claim), so
an ID token cannot stand in for one. Require https for the issuer except
on localhost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: refuse ID tokens with an audience set, parse the issuer host

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: take an external MCP token's groups for the request instead of storing them

When sso_groups_claim is set, the IdP-managed instance groups of an
external MCP request come from the token's claim alone, mapped through
their external_id with nested paths counting for their ancestors. Nothing
is written, and an absent claim means no IdP groups, so removing a user
from every group revokes at the next token. Entra's overage pointer is
refused rather than read as no groups.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* feat: give external MCP clients the token access levels, one card per client

A client takes the same access as a Windmill token: read, read and run,
build and run (the session toolset, bound to the client's workspace), or
scripts and flows as tools. The settings editor reuses McpAccessPicker,
one collapsible card per client. The caller's JWT carries mcp_client so
runs the session toolset starts record the client too. With token groups
in use, admin rights a managed group grants follow the token, and
workspace groups are kept by source rather than by name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep a client's tool selection across reopening its card

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: tidy the MCP external identity provider form

Show it under SSO only, shorten its description with details in a
tooltip, and give its fields form labels, hints and tooltips.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: leave default claim names empty, shorten auth setting descriptions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: report an external MCP token's groups in whoami

Requests and jobs started through an external MCP token act with the
token's groups; whoami returned the stored memberships instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep stored roles for external MCP requests

Only group memberships follow the token. Admin and superadmin roles stay
as stored, kept current by SCIM and SSO login: their source is not
recorded, so a group-derived demotion also stripped directly granted
admins and left operator restrictions unapplied.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: record the MCP client on on-behalf-of runs and AI agent tool steps

On-behalf-of runs now hand push the MCP caller, which push uses only to
record the client while it fetches the run's own permissions. AI agent
tool jobs read the client from job_perms, so their steps see
WM_MCP_CLIENT.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix: keep the MCP client off v2_job

The client is needed only while a job is queued, which job_perms covers; a
finished run's client is in its audit entry. This leaves the job history
table unaltered.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore: update ee-repo-ref to e9e94030cebd5afb0c8156ee46af2025bbe8778a

This commit updates the EE repository reference after PR #934 was merged in windmill-ee-private.

Previous ee-repo-ref: 7bdd6e8067a72e847ed0372ddc79a84f288946cf

New ee-repo-ref: e9e94030cebd5afb0c8156ee46af2025bbe8778a

Automated by sync-ee-ref workflow.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: windmill-internal-app[bot] <windmill-internal-app[bot]@users.noreply.github.com>
Co-authored-by: Ruben Fiszel <ruben@windmill.dev>
2026-10-30 20:09:09 +01:00

181 lines
16 KiB
Markdown

# Auth surface: facts that are easy to get wrong
Symbols, not line numbers, are cited: they drift less.
- **Credential precedence** (`windmill-api-auth/src/auth.rs` `extract_token`): `Authorization: Bearer`
→ `token` cookie → `?token=` query param. A URL with `?token=` is a credential on every route, but
an existing cookie silently wins over it.
- **`AUTH_CACHE`** caches a token's identity for 120 s. Deleting a token row does not purge it: the
DB trigger (`migrations/20260316000001_token_hash_pk_swap.up.sql`) notifies only for
`label = 'session'` rows, and `delete_token` never calls `invalidate_token_from_cache`.
- **Sessions** are `token` rows with `label='session'` plus the HttpOnly `token` cookie, minted only
by `create_session_token` (`windmill-api-users/src/users.rs`). `GET /api/users/refresh_token`
mints one for any non-job token but returns plain text, no redirect.
- **`tokens/impersonate`** (superadmin) returns a multi-use token and sets no cookie.
- **`max_token_expiration_days`** caps `POST /users/tokens/create` and `tokens/impersonate`, by
shortening the stored expiration (`cap_token_expiration`), never by refusing: the CLI
authorization page, `wmill user create-token` and the editor's language-server token all pick a
lifetime without reading the setting, and CLIs already installed never will. The CLI signs in
again on its own when its token expires, which is why the authorization page labels it
`cli-login:<username>`, reserved in `is_user_token` so its expiry does not email the user. A token
owned by a service account is exempt: one in the workspace the token names, or in any workspace
for a workspace-less token (for `tokens/impersonate`, the impersonated account). Any workspace
admin can therefore create and impersonate a service account to hold an uncapped token, so the
ceiling bounds personal tokens only. Only the stored expiration is capped: the auth lookup never
reads the setting, so tokens that exist when it is turned on or lowered keep theirs, including
none. Deliberately outside it: server-side mints (`create_token_internal` callers such as native
trigger webhook tokens, which never expire for GitHub and Nextcloud), and tokens with their own
fixed lifetime that outlive a short ceiling: sessions (`MAX_SESSION_VALIDITY_SECONDS`, 3 days, and
re-mintable through `GET /users/refresh_token`) and MCP OAuth access tokens (7 days, with a
rotating 30-day refresh token). Any logged-in user can read the setting through `GET
/settings/global/{key}`, which the token form uses to offer only expirations within it. The
settings API and config sync reject any value `parse_max_token_expiration_days` cannot read, since
the token routes would read it as no ceiling; `parseMaxTokenExpirationDays` in the frontend must
accept exactly the same values.
- **A token's label decides whether its expiry raises alerts.** When `delete_expired_items` removes
an expired `token` row, the monitor emails the owner and raises a critical alert (if enabled);
rows registered by `register_token_expiry_notification` also get an "expiring soon" warning first,
except a token whose whole lifetime fits in `TOKEN_EXPIRY_WARNING_DAYS` (7), which gets no row
since the warning would arrive minutes after it was created. Neither happens when `is_user_token`
(`windmill-common/src/auth.rs`) reserves the label, so a token the system mints for itself,
whether from the backend or from the frontend through `tokens/create`, needs a reserved label. An
`ephemeral-` prefix needs no other change (keep it clear of `is_server_minted_label` if minted
through `tokens/create`); a new prefix also goes into the SQL and Svelte mirrors that function's
doc lists.
- **Every superadmin route refuses a job token**: `require_super_admin`
(`windmill-api-auth/src/lib.rs`) errors on `authed.job_id.is_some()`. A script that needs
`users/create`, `tokens/impersonate`, `set_login_type`, … must use a dedicated superadmin user
token stored as a secret, never `$WM_TOKEN`. Token scopes cannot narrow superadmin routes.
- **Write access to a folder steers its readers' AI chat.** An `ai_instruction` resource's body is
delivered to the global chat of everyone who can read the resource, with no opt-in, whenever the
chat touches a path under its folder (`copilot/chat/folderInstructions.ts`); the chat then acts
with that reader's permissions, outside the folder too. `ai_skill` bodies are likewise in play
for every reader until turned off. An `ai_review_instruction` steers the AI review of every
deployment request touching its folder, for anyone who can read it in the parent workspace
(`deploymentRequest/aiReview.ts`); a fork's own copy is never read. The prompt tells the model to
keep reporting secrets and unintended deletions whatever they say, but that is a request to the
model, not enforcement: an instruction body can still talk it out of them. The resource ACL is the only
control, so granting write on a folder grants that influence.
- **Restricted job tokens** (`job_token_scopes` on scripts and flows): a job's effective scopes
are stored on its `job_perms` row at push and minted into its token
(`create_token_for_owner`); an empty set is minted as `NO_API_ACCESS_SCOPE`, since
`scopes: Some([])` reads as unscoped. Every `push` takes a `scope_ceiling`, and the job gets the
ceiling ∩ the target's own setting: flow steps take their flow job's, agent tools their agent's,
WAC children their parent's, retries the run they replace, and API pushes the calling job's
(`caller_scope_ceiling`) — a scoped user or webhook token caps nothing. The row is swept once a
job leaves the queue, so a restart of a completed flow takes the flow's current setting. Schedules,
triggers and error/success handlers start from the target's own setting. A restricted token
keeps only the runtime routes about its own job (`is_own_job_runtime_route`) and the reads of
its own flow run (`flow_run_read_route_job`, checked against its lineage: the orchestrator
evaluates a step's `results.x` with the token of the step that just finished). That lineage is
trusted, so a restricted job token, even an admin's, can only place a job it starts in its own
run (`unclaimable_run_lineage`); a route that
authenticates a token itself instead of through the route layer must call
`check_job_token_scope`. A restricted job never runs on a dedicated worker, which uses its own
unscoped token for every job. `$var:`/`$res:` args are resolved through the API with the job's
own token, so they need read scopes. A deploy that omits the setting keeps the deployed value
and `null` clears it, so an unaware client cannot drop a restriction; setting one is refused
until every worker supports it, since an older worker mints without it. The OIDC
`job_token_scopes` claim is the presented token's scopes, not the runnable's setting, so a
verifier sees what the job could reach and a token minted without the restriction shows as
unrestricted. The setting belongs to
the deployed version: an older script hash run by hash runs with that version's setting (a
restricted caller still caps it). Write scopes on scripts, flows, schedules or triggers let a
job escape its restriction.
- **A remote deploy token is a credential for another instance**, held per account and workspace
(`remote_deploy_token`, encrypted under the workspace key, re-keyed by `set_encryption_key`).
Its `email` references `password(email)` with `ON DELETE/UPDATE CASCADE`, so whatever deletes or
renames an account takes the token along and a recycled address cannot inherit it; removal from
a workspace deletes it explicitly (`delete_workspace_user_internal`, both `leave_workspace`). The
row records the target it was granted for, and
`remote_deploy::proxy` only sends it to a target still matching the workspace setting, so
re-pointing the setting cannot redirect anyone's token to a URL of the admin's choosing.
`require_own_credentials` refuses job, scoped and read-only tokens (on `set_target` too): the
stored token carries none of their restrictions. The proxy turns the local session into a remote
bearer credential, so every ambient-cookie vector becomes one on the remote: its URL carries the
row's random `proxy_key` (a link riding the `SameSite=Lax` cookie cannot know it; a header would
do, but the frontend's only per-call hook is the global `OpenAPI.HEADERS`, whose mere presence
switches every download to in-memory blobs). The key is served `no-store`, withheld from the
credentials `require_own_credentials` refuses, and masked in this instance's own request logs
(`RedactedUri`, used by the request span and the log context); a reverse proxy in front still
writes the full path to its access log. `connect` names the target the token was obtained for
and is refused, before the token is sent anywhere, if the workspace now points elsewhere; the
token only ever goes to that target. It takes no lock against what clears these rows (a removal
from the workspace, a target change, a key rotation): their writers take the account, membership,
key and settings rows in every order, so any lock held there could close a deadlock. A row can
therefore land after one of them ran, however long its remote call took, and every read
(`load_connection`) voids it instead, by identity rather than by comparing times: the connect
records, before its remote call, the target setting's version (`remote_deploy_target_changed_at`)
and the `created_at` of the owner's membership, and the row counts only while both are still
the same (or the owner is a superadmin) and it decrypts. So a target set A → B → A, or a
removal and re-add, voids it whatever the clocks say. A superadmin with no membership is bound
through the credential making the request instead: the insert requires its `token` row to
still exist, and `delete_user`, offboarding and SCIM removal delete an account's tokens, so an
address deleted that way and re-created during the call does not inherit the connection (a JWT,
having no row, cannot connect a workspace its owner is not a member of). `leave_instance`
deletes only the `password` row, leaving the tokens and the memberships, which is not covered.
Neither is a member's connect across an account re-creation: an address is not expected to pass
to another person. A disconnect empties and stamps the row
(inserting one if needed) rather than deleting it, `connected_at` is when a connect started,
and the connect's upsert leaves a row stamped after that alone, so an older connect cannot undo
a disconnect or a newer connect. Connecting by redirect: the remote's
`/user/remote_deploy_authorize` page
mints a token bound to the one remote workspace (`remote-deploy:<source host>`, a label
reserved in `is_user_token` so its expiry emails nobody) only on an
explicit Authorize, only for a callback whose path is `/remote_deploy/callback`, and refuses to
render inside a frame; the token travels in the fragment, and the callback checks a single-use
`state` the drawer stored, so no other page can plant a token as the user's. The proxy also refuses a path the URL parser would rewrite,
serves every response under `CSP: sandbox` + `nosniff`, forwards only the method, query, body,
content-type and accept — never this instance's cookie or token — and turns the target's 401
into a 502, because the browser logs the user out of *this* instance on an unhandled 401.
- **`login_type`** (`password` table) is a free-form `VARCHAR(50)`. Password login and password
reset require `login_type = 'password'`; `set_password` also accepts `pending_oauth` and turns
the account into a `password` one in the same statement (an account created ahead of its owner
gets its first credential that way, or through the OAuth claim below).
- **Login links** (`login_link` table, `POST /users/login_links` superadmin-only,
`GET /auth/login_link/{token}` unauthenticated): single-use, ≤15 min, a session cookie and a
302 to a same-origin `rd`. `require_login_type` on the mint refuses (409) an account whose
`login_type` has moved on — the way a caller re-entering an account it created stops being
able to once the owner has a password or a provider.
- **Pre-approved trial offer** (`cloud_trial_offer`, cloud-only routes under
`/users/cloud_trial_offer`): written by a superadmin at provisioning, consumed by
`{consumed: true}` or by the portal's refusal; `…/go` is the one Windmill→portal hop that
mints a portal login, over the same `CUSTOMER_SERVICE_TOKEN` trust the onboarding hook uses
(`users_ee.rs`, the portal's admin token). It never expires on its own.
- **OAuth login** (`oauth2_ee.rs` `login_externally`, decision in `existing_login_decision`)
matches an existing account by lowercased email only. Same provider → login; a
`pending_oauth` account (see `PENDING_OAUTH_LOGIN_TYPE`) is **claimed** by the first login
whose address the provider itself asserted and did not mark unverified — `login_type` becomes
the client key and the hash is nulled; otherwise `require_preexisting_user_for_oauth` decides:
on, *every* existing account is loggable-into by any provider; off, "exists but with a
different login type". A new account gets `login_type = <client key>`.
- **OAuth email trust**: `LoginUserInfo.email_verified` is read leniently (bool or
"true"/"false" strings) and is only consulted for the claim above; only GitHub is filtered to
`primary && verified`; a missing email is fabricated from `name` as `<name>@windmill.dev` and
reaches `login_externally` with `email_asserted = false`.
- **MCP access tokens from an external issuer** (`mcp_external_idp`, EE, `mcp/external_idp.rs`):
taken only for a JWT whose unverified `iss` is the configured issuer, then verified against its
discovery JWKS. With no audience configured, only a token typed as an access token (`at+jwt`
header, or a `Bearer` `typ` claim) is taken, so a client's ID token cannot stand in for one;
an instance-deactivated account (`password.disabled`) is refused, since this path has no
Windmill token for deactivation to revoke. The token's client claim (`azp` by default) must name a configured client, and
its email claim an existing, enabled member of that client's workspace: no account is created,
and a client-credentials token (no user) is refused with 403. When `sso_groups_claim` is set,
the instance groups with an `external_id` come from that claim of the token alone, for that
request only (nested paths counting for their ancestors): nothing is written, unlike an SSO
login, and an absent claim means no IdP groups, so removing a user from every group revokes at
the next token. Roles (admin, superadmin, operator) are not derived from the token: they stay as
stored, which SCIM and SSO login keep current. Entra's overage pointer (`_claim_names`) is refused rather than read as no
groups. The resolved identity is cached per token for at most a minute. Runs
record the client in `job_perms.mcp_client` (and the job-start audit entry), from the pushing identity
rather than `job_authed`, so a run on behalf of another identity still names it; the
session toolset reaches the API through a JWT minted for the caller, which carries the client
in its `mcp_client` claim for the same reason, and so does a job's `WM_TOKEN`.
- **`GET /api/oauth/login/{client}`** is an unauthenticated 302 to the provider — a plain link
from any page starts SSO.
- **`CLOUD_HOSTED`** is presence-tested (`windmill-common/src/worker.rs`): `CLOUD_HOSTED=false`
still enables cloud mode. Of the routes above only the cloud trial offer and onboarding
profile routes are cloud-gated; for the rest, cloud only adds quotas.
- **`CREATE_WORKSPACE_REQUIRE_SUPERADMIN`** defaults to `true` when unset; only the literal
`"true"` enables it when set.