Skip to content

auth and roles

Dr K edited this page Nov 14, 2026 · 4 revisions

Auth and roles

Who may reach the server, and what each credential opens. The standing credential is the token (auth.token). The server can also accept a JWT from one OIDC issuer, on /mcp and in the admin UI. A signed link opens one file or one stream and carries no identity. Roles gate a door, and nothing past it.

Use cases

  • A script or an MCP client sends the token and drives every workspace.
  • A gateway forwards a person's issuer token. /mcp verifies it and workspace://current names the person.
  • A person holding an admin role signs in to the admin UI with the issuer, not the token.
  • A chat transcript shows a screenshot through a link that opens that one file for an hour.

Neighbours

AUTH-1. Which header names a workspace is in workspaces-and-sessions.md. The routes and the OpenAPI document are in surfaces.md. What a signed link points at is in workspace-files.md, the live view's use of one in live-view-and-control.md, and how the pages draw in admin-ui.md. Each setting's spelling is in config.md; this file holds the rules between the auth and oidc settings.

Credentials and doors

AUTH-2. A request presents a credential in the Authorization header. A value of Bearer <credential> (the scheme in any case) presents <credential>. Any other value presents itself whole, so a bare token works wherever a door reads the header. /mcp is the exception (AUTH-7). A missing header presents the empty string.

AUTH-3. With no auth.token (blank counts as unset) the server is open: /mcp has no auth provider, every door admits every request, no link is signed and the signed routes serve the plain path, and no caller has a principal.

AUTH-4. With a token, each route belongs to one door:

Door Routes Admits A refusal is
/mcp the MCP endpoint the token as a bearer, or a JWT (AUTH-8) 401 from FastMCP (AUTH-7)
Token every route that answers through answer.answer (browser actions, open and end, flows, files, site data) and GET /secrets the token 401 {"error": "unauthorized"}
Admin every /admin/* JSON route the token, or an admin-UI JWT (AUTH-15) 401, or 403 (AUTH-15)
Stream /admin/events and the capture tail a signed link, else the Admin door the Admin door's
Live the live view's mint, paste and socket the Admin door; the socket also a bound link see AUTH-32
Signed /files, /kept, /screenshots and /recordings the signature in the URL 403 (AUTH-26)
Open see AUTH-5 anything none

AUTH-5. These routes check nothing, with or without a token: /health, /started, /ready and /info (served at the root and under the mount prefix), /openapi.yaml, /openapi.json, the admin page at the mount root, its /live.js, and /admin, which redirects to ./ with a 301. A bearer sent to one changes nothing about the answer.

AUTH-6. The Token door runs before anything else in its route: a refused request has not had its body read, its workspace named or any browser touched. It never admits a JWT.

The token

AUTH-7. On /mcp the token is accepted only as Authorization: Bearer <token>. A request with no Authorization header, or one that is not Bearer, is answered 401 with WWW-Authenticate: Bearer and no body. A bearer that no verifier accepts is answered 401 with the JSON body {"error": "invalid_token", ...} and WWW-Authenticate: Bearer error="invalid_token". Both are FastMCP's answers, and a JWT refused for any reason gets the same one.

AUTH-8. /mcp tries the token first, then the JWT verifier, and the first to accept wins. With no oidc settings, only the token is tried.

AUTH-9. Every comparison of the token or of a signature is hmac.compare_digest over bytes and compares the whole value. A credential with characters outside ASCII is a refusal, never an exception.

AUTH-10. The token on /mcp is the admin principal (AUTH-17). Rotating it ends every link (AUTH-23) at once.

JWTs on /mcp

AUTH-11. OidcVerifier accepts a JWT only when all of these hold, and refuses otherwise with no detail to the caller:

  1. the signature is RS256 and verifies against a key from oidc.jwks_uri;
  2. iss is oidc.issuer and aud names oidc.audience;
  3. exp is a number (a boolean is not) and has not passed;
  4. nbf, when present, is a number no more than 60 seconds ahead of now;
  5. for /mcp only: the roles in the token include one of oidc.roles, when that list is not empty. An empty list checks no role.

AUTH-12. Roles and the principal are read from a token's claims only after AUTH-11's checks 1 to 4 pass. A token that never expires is never accepted.

AUTH-13. The roles a token holds are the list at oidc.roles_claim (roles by default). A dot in the claim walks into nested objects (realm_access.roles). A missing claim, a value that is not a list, or a walk through something that is not an object holds no roles. Non-string entries in the list are dropped. The role check and the principal read roles the same way.

AUTH-14. The verifier fetches oidc.jwks_uri when a token needs a key it has not cached. At most one fetch starts in 60 seconds:

  • A call that arrives while a fetch runs waits for it and uses its result.
  • A call within 60 seconds of the last fetch starting reuses that fetch's result when it succeeded, with no request, and is refused when it failed.
  • A caller's cancellation does not cancel the fetch.

FastMCP's own jwks_refresh_interval floor is passed as 0, so this is the only floor.

An unreachable issuer refuses the token and the server keeps running. A key published after a fetch is unknown for up to 60 seconds.

The admin door

AUTH-15. AdminDoor.admit decides, in this order:

  1. no auth.token: admit, with no principal;
  2. the presented credential equals the token: admit as admin;
  3. no oidc.client_id (so no JWT verifier), or an empty credential: 401 {"error": "unauthorized"};
  4. the verifier's checks, minus the oidc.roles role check, refuse the JWT: 401;
  5. the token's azp is not oidc.client_id: 401;
  6. none of its roles is in oidc.admin_roles: 403 {"error": "this sign-in does not hold an admin role"};
  7. admit, as the JWT's principal.

AUTH-16. The admin door and /mcp share one OidcVerifier: one JWKS cache, one refetch floor. oidc.roles does not apply on the admin door, nor oidc.admin_roles on /mcp. A JWT minted for another client of the issuer, even one holding an admin role, is a 401 on the admin door.

The principal

AUTH-17. A principal is admin (the token) or oidc (a verified JWT). An oidc principal holds subject (the string sub, else none), username (the string preferred_username, else none) and roles. A JWT is an oidc principal whatever its roles.

AUTH-18. The verifiers attach the principal to the access token they return. On /mcp, clients.caller() copies it onto the Caller. A stdio caller and a caller of an open server have none. A Token-door request has the admin principal when a token is set.

AUTH-19. workspace://current and GET /browser carry principal: {"kind": "admin"}, {"kind": "oidc", "subject": ..., "username": ...}, or null when the caller has none. Roles are never shown.

AUTH-20. open_session records who opened the browser as opened_by, {"kind", "username"} from the caller's principal or none. A silent reopen after a reap leaves it alone, and a stored value of any other shape reads as none. The admin API returns it per workspace, and the admin UI's meta line ends with by token, by <username> or by OIDC (an oidc principal with no username). It is shown and never consulted.

AUTH-21. A principal decides nothing past a door. No tool, route or resource differs by principal, any admitted caller may use every tool and name any workspace, and a workspace has no owner.

AUTH-22. A person watching the live view is named open with no principal, admin for the token, else by username, else subject, else oidc, with control characters replaced by ? and cut to 64 characters.

Signed links

AUTH-23. A signed link is the route's path (without the mount prefix) plus the query exp=<epoch seconds>&sig=<hex>, and by=<name> when bound to a viewer. sig is the first 32 hex characters of HMAC-SHA256, keyed by the token, over <path>:<exp>, with \0<by> appended when bound. Each path parameter is percent-encoded.

AUTH-24. exp is the current time plus the link's lifetime, rounded up to the next multiple of 600 seconds, so links to one file signed in one window are the same URL. A link bound to a viewer has an exact expiry. File links last link_ttl seconds (3600 by default, at least 60), and the event stream's and the capture tail's last 3600.

AUTH-25. A request is checked in this order: the signature, then the expiry (a link stops working once its exp has passed), then the route's own checks. A missing, malformed or wrong exp or sig is invalid. A link that is expired always had a correct signature, so only a link this server minted is ever called expired.

AUTH-26. A refused link is a 403. The body is {"error": "invalid link"} or {"error": "expired link"}. When the request's Accept includes text/html, the body is a page titled This link is not valid or This link has expired, which says when an expired link stopped working. The page is sent with Cache-Control: no-store, nosniff and a default-src 'none'; style-src 'unsafe-inline' content security policy.

AUTH-27. A link grants one path: a download's link does not open a kept file of the same name, and an unbound link's signature does not verify as a bound one.

AUTH-28. A signed route's failure after the signature passes carries no exception text, so that a shareable link leaks nothing. The detail goes to the log at INFO.

Cause Answer
A missing file, or a name the store would never write 404 {"error": "not found"}
Another 4xx that status, {"error": "this link cannot be served"}
A 5xx that status, {"error": "the file could not be read right now"}

AUTH-29. The event stream and the capture tail open on a link signed over their own path, which the admin API hands only to a request its door admitted (events_url in GET /admin/workspaces, tail_url in a capture view). A request with no valid link is asked of the Admin door, so a header client opens them too. An open stream is not cut when the JWT behind its link expires.

The live view's links

AUTH-30. The live mint (GET /admin/workspaces/{key}/live) and the paste route admit through the Admin door and name the viewer as AUTH-22 does.

AUTH-31. The mint returns a socket link signed with by=<viewer> that lasts exactly 60 seconds. The socket accepts a link only when it carries by, and then the viewer is by, cleaned as in AUTH-22. A link signed for one viewer opens nothing as another.

AUTH-32. A socket whose link is missing, invalid or expired is asked of the Admin door, which handles a client that can send a header. When that refuses, the socket closes with code 4401 and the reason this live view link has expired: open the tab again for an expired link, or unauthorized for any other, and the server logs at WARNING live: refused <name or someone> the live view of <workspace>: <reason>. The name is by only for an expired link, whose signature was correct; otherwise it is someone.

The admin UI's sign-in

AUTH-33. The page is served without a credential. It carries data-oidc: the JSON {"issuer": ..., "client_id": ...} when oidc.client_id is set, else an empty string. Nothing else about OIDC reaches the page. It is sent with Content-Security-Policy: frame-ancestors ('none' unless security.frame_ancestors lists origins), X-Content-Type-Options: nosniff and Referrer-Policy: same-origin.

AUTH-34. The sign-in card has a token field. A token is kept in sessionStorage['sf-token'], probed with GET /admin/workspaces before the page shows, and sent as a bearer on every call. A 401 on a token sign-in signs out.

AUTH-35. When data-oidc is set the card shows a Sign in with OIDC button below the token field. In a frame the button opens the page's URL in a new tab with noopener.

AUTH-36. The sign-in is Authorization Code with PKCE (S256), run by the page as a public client. It uses no server callback, no cookie and no client secret. The page fetches {issuer}/.well-known/openid-configuration and refuses the document unless its issuer is the configured one and both endpoints are https: URLs (http: too, when the configured issuer is http:). Any failure to get a usable document reads The issuer could not be reached.

AUTH-37. The authorization request carries response_type=code, client_id, redirect_uri, scope=openid, state, code_challenge and code_challenge_method=S256, and adds prompt=none on a silent attempt. The redirect_uri is the page's origin and path with one trailing /. The verifier is 32 random bytes and state 16, base64url; they wait with the hash route in sessionStorage['sf-oidc-pending'].

AUTH-38. A load whose address has code or error is a reply. The page deletes the pending entry and puts the address back to its path plus the stored hash route before anything else, so a code never stays in the address bar. Then it checks, in this order, and stops at the first failure:

Check The card says
no pending entry, or state differs That sign-in reply was not ours; try again.
iss present and not the issuer That sign-in reply came from another issuer.
error present The issuer said: <error_description or error>.
discovery fails The issuer could not be reached.
the token exchange fails The issuer would not complete the sign-in.

A silent attempt answered login_required, interaction_required, consent_required or account_selection_required shows the card with no message.

AUTH-39. The exchange posts a form (grant_type=authorization_code, code, redirect_uri, code_verifier, client_id) to the token endpoint. The tokens stay in memory. The page then probes GET /admin/workspaces with the access token.

AUTH-40. A probe that fails drops the tokens and signs out. A 403 says Signed in as <preferred_username>, who does not hold an admin role. (this account when the token has none; the page decodes it for display only), and anything else says The server refused this sign-in. A probe that succeeds sets sessionStorage['sf-signin'] to oidc.

AUTH-41. The page renews 30 seconds before the access token expires, and never sooner than 5 seconds from now, using the refresh token. A call made within 5 seconds of expiry waits for the renewal. A 401 on an OIDC sign-in renews once and retries; a second 401 signs out. Without a refresh token the sign-in ends when the access token does.

AUTH-42. The issuer refusing a renewal with a 4xx other than 408 or 429 ends the sign-in. Any other failure (offline, 5xx, 408, 429) is asked again after 2 seconds, doubling to 60 seconds, for as long as the page holds the sign-in. An ended sign-in says Your sign-in ended; sign in again.

AUTH-43. A reload loses the tokens. When no token is stored and sf-signin is set, the page deletes it and begins a silent sign-in, so a down issuer never loops.

AUTH-44. Sign out stops the live stream and the renewal timer, forgets the token, the OIDC tokens, sf-token and sf-signin, and shows the card. It does not end the issuer's session. Nothing is written to localStorage.

The settings rules

AUTH-45. oidc.issuer, oidc.audience and oidc.jwks_uri (the triple) turn OIDC on and are set together or not at all, else ConfigError oidc.issuer, oidc.audience and oidc.jwks_uri are set together or not at all. oidc.issuer and oidc.jwks_uri must start with https:// or http://.

AUTH-46. OIDC needs the token: with the triple set and no token, ConfigError oidc needs auth.token: the token stays the admin login. The rule runs after the file, the environment and the arguments merge, so a file may set oidc while the token comes from the environment.

AUTH-47. oidc.client_id and oidc.admin_roles are set together or not at all (oidc.client_id and oidc.admin_roles are set together or not at all), and oidc.client_id needs the triple (oidc.client_id needs oidc.issuer, oidc.audience and oidc.jwks_uri: the admin UI signs in with the issuer /mcp trusts).

AUTH-48. oidc.roles and oidc.admin_roles are lists, and an environment value is split on commas with each part trimmed and blanks dropped. oidc.roles_claim defaults to roles. The same checks run in auth.doors for a Settings built in code, as the same ConfigError.

What is logged

AUTH-49. A refusal the verifier makes is one INFO line, JWT refused for sub <sub>: <reason>, with the reason one of no numeric exp, nbf not numeric or in the future, no allowed role, not the admin UI's client or no admin role. A refusal FastMCP makes (signature, iss, aud, exp) is logged by FastMCP. None of this area's lines carries a token or a claim other than sub.

Proposed: ownership and roles

Not built. The reasoning, and the questions still open, are in the ownership design.

AUTH-50. (proposed) A workspace created by an OIDC caller takes that caller's roles. Which of its roles count, what counts as creating a workspace, and how long the workspace keeps them are open. Replaces, when built, AUTH-21's "a workspace has no owner".

AUTH-51. (proposed) A later caller that names a workspace holding roles must hold one of them. Replaces, when built, AUTH-21's "any admitted caller may ... name any workspace". What a refused caller is told is open.

AUTH-52. (proposed) The admin sees every workspace, whatever roles it holds.

AUTH-53. (proposed) Each surface, mcp, console and api, has its own roles, and a caller reaches a surface only while holding one of them. Which doors each name covers, and whether api admits a JWT at all (AUTH-6 says the Token door never does), are open.

AUTH-54. (proposed) A tool can have its own roles, and a caller may call it only while holding one of them. execute_script, delete_flow and binding a secret are the examples the brief names. tools/list leaves out what a caller may not call (SURF-47). Replaces, when built, AUTH-21's "No tool, route or resource differs by principal".

Clone this wiki locally