Repository navigation
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.
- A script or an MCP client sends the token and drives every workspace.
- A gateway forwards a person's issuer token.
/mcpverifies it andworkspace://currentnames 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.
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.
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.
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.
AUTH-11. OidcVerifier accepts a JWT only when all of these hold, and refuses otherwise with
no detail to the caller:
- the signature is RS256 and verifies against a key from
oidc.jwks_uri; -
issisoidc.issuerandaudnamesoidc.audience; -
expis a number (a boolean is not) and has not passed; -
nbf, when present, is a number no more than 60 seconds ahead of now; - for
/mcponly: the roles in the token include one ofoidc.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.
AUTH-15. AdminDoor.admit decides, in this order:
- no
auth.token: admit, with no principal; - the presented credential equals the token: admit as
admin; - no
oidc.client_id(so no JWT verifier), or an empty credential: 401{"error": "unauthorized"}; - the verifier's checks, minus the
oidc.rolesrole check, refuse the JWT: 401; - the token's
azpis notoidc.client_id: 401; - none of its roles is in
oidc.admin_roles: 403{"error": "this sign-in does not hold an admin role"}; - 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.
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.
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.
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.
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.
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.
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.
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".
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network