Access control¶
FastMock checks every admin API call against a permission. The three roles viewer, editor and admin are
built-in sets of permissions; custom roles, spaces and bindings come from an optional access file. Spaces let
several teams share one FastMock instance: a team bound to a space sees and changes only the stubs, journal
entries, state, files, callbacks and contract tests of that space, and can be limited to its own part of the
data-plane URL space.
- Without an access file
- Permissions
- Built-in roles
- The access file
- Custom roles
- Bindings
- Managed tokens
- OIDC sign-in and bearer JWTs
- Spaces
- Selecting a space in the API
- Ownership of the data plane
- What is scoped and what is global
- Inspecting your permissions
- Viewing the access configuration
- In the web UI
- Errors
- Examples
- Upgrade notes
- Migrating an existing installation
Without an access file¶
Nothing changes: every entry of FASTMOCK_ADMIN_TOKENS / FASTMOCK_ADMIN_TOKENS_FILE (name:role:sha256hex) is a
global binding of a built-in role, and every endpoint needs the same role as before
(Admin API: roles per endpoint). Existing stubs, journal entries and
state belong to the global area.
Permissions¶
A permission is resource:action. Space permissions can be granted in single spaces; global permissions only
everywhere.
| Permission | Endpoints | Scope |
|---|---|---|
stubs:read |
GET /stubs, /stubs/{id}, /stubs/unused, /export; POST /stubs/find-by-metadata, /stubs/validate |
space |
stubs:write |
POST /stubs, PUT/PATCH/DELETE /stubs/{id}, DELETE /stubs?tag=, POST /stubs/remove-by-metadata |
space |
stubs:purge |
DELETE /stubs without tag |
global |
imports:run |
POST /stubs/import, /import, /import/* |
space (the target space of the imported stubs) |
journal:read |
GET /requests, /requests/{id}, /requests/count; POST /requests/count, /requests/near-misses, /requests/find, /verify, /verify/sequence |
space |
journal:delete |
DELETE /requests, POST /requests/remove |
space |
files:read, files:write |
GET /files*; PUT/DELETE /files/{name} |
space |
recordings:read, recordings:write |
GET /recordings; POST /recordings/start, /stop, /snapshot |
global |
callbacks:read, callbacks:delete |
GET /callbacks; DELETE /callbacks |
space |
state:read, state:write |
GET /scenarios, /kv/{key}, /stubs/counters; PUT /scenarios/{name}, DELETE /scenarios, PUT/DELETE /kv/{key}, DELETE /stubs/counters |
space |
chaos:read, chaos:write |
/chaos, /settings |
global |
grpc:read, grpc:write |
/grpc/descriptors* |
global |
contracts:read |
GET /contract-tests, /contract-tests/{id} (verdicts) |
space |
contracts:details |
request and response excerpts and error texts of contract test results | space |
contracts:write |
POST /contract-tests, DELETE /contract-tests/{id} |
space |
contracts:secrets |
secretHeaders in POST /contract-tests |
global (the secrets of FASTMOCK_CONTRACT_SECRETS are server-wide); a custom role that lists it by name cannot be bound in spaces, see Bindings |
info:read |
GET /info, /version, /plugins, /spaces |
global, implied by any binding |
audit:read |
GET /audit |
global |
access:read |
GET /access (the access configuration: spaces, roles and bindings) |
global |
system:reset |
POST /reset |
global |
tokens:read, tokens:write |
GET /tokens, /tokens/{id}; POST /tokens, DELETE /tokens/{id} (managed tokens) |
space (the scopes of the token) |
Endpoints without a space of their own need the permission globally:
| Endpoints | Permission (global) |
|---|---|
GET /requests/unmatched |
journal:read (unmatched requests belong to no space) |
GET /services*, GET /async-mocks* |
stubs:read |
DELETE /services/{id}, PUT/DELETE /async-mocks/{id}, POST /async-mocks/{id}/trigger |
stubs:write |
POST /import/asyncapi, /import/graphql, /import/soapui, /import/wsdl, /import/microcks (and POST /import detecting one of these formats) |
imports:run |
plugin admin routes /plugins/{name}/... |
stubs:read for GET, stubs:write otherwise |
Credentials inside stubs are shown only to principals with stubs:write in the stub's space; others get them
masked (Security: redaction).
Built-in roles¶
| Role | Permissions |
|---|---|
viewer |
every *:read permission except audit:read, tokens:read and access:read |
editor |
viewer plus stubs:write, imports:run, journal:delete, files:write, recordings:write, callbacks:delete, state:write, chaos:write, grpc:write, contracts:details, contracts:write |
admin |
every permission |
The built-in roles cannot be redefined.
The access file¶
FASTMOCK_ACCESS_FILE names a YAML file with custom roles, spaces and bindings. It is read once at start-up,
like the token file; change it and restart (with Helm, helm upgrade rolls the pods). A file with an error stops
the server with a one-line message that names the file and the entry, for example
access file /etc/fastmock/access/access.yaml: roles[0] (stub-author): unknown permission `stubs:wrte` or
access file /etc/fastmock/access/access.yaml: bindings[3] (token:nosuch): no token named nosuch in FASTMOCK_ADMIN_TOKENS or FASTMOCK_ADMIN_TOKENS_FILE
for a binding of an unknown token.
roles:
- name: stub-author
permissions: [stubs:read, stubs:write, imports:run, journal:read, state:read]
spaces:
- name: payments
description: Payment provider mocks
pathPrefixes: [/payments/, /psp/]
hosts: [psp.example.com]
- name: billing
bindings:
- subject: group:payments-dev
role: editor
spaces: [payments]
- subject: group:platform
role: admin
global: true
- subject: token:ci-billing
role: stub-author
spaces: [billing]
All three lists are optional. Unknown fields are errors.
Spaces, custom roles and bindings are defined only in the access file: the file named by FASTMOCK_ACCESS_FILE,
the access values of the Helm chart, or the ConfigMap named by
spec.access.configMapRef with the operator. There is no API that creates or changes
them. To add a space, add it to the file and restart (with Helm and the operator the pods roll on their own). The
UI's Access page and GET /__admin/access show the configuration read-only
(Viewing the access configuration).
Custom roles¶
| Field | Meaning |
|---|---|
name |
[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?, not viewer, editor or admin. |
permissions |
Permission names; resource:* grants every permission of a resource (stubs:*, contracts:*), and "*" (quoted) every permission. Unknown names are start-up errors. |
description |
Optional text. |
A custom role can be used in a binding and as the role of a token entry: ci-billing:stub-author:<sha256> in
FASTMOCK_ADMIN_TOKENS is a global binding of stub-author.
Bindings¶
A binding gives a role to a subject, either everywhere (global: true), in a list of spaces (spaces) or in every
space (spaces: ["*"], see All spaces); exactly one of global and spaces.
| Subject | Matches |
|---|---|
token:<name> |
the static token entry with that name in FASTMOCK_ADMIN_TOKENS or FASTMOCK_ADMIN_TOKENS_FILE (a binding for an unknown token name is a start-up error) |
user:<username> |
an OIDC user by the value of the username claim (use a stable claim such as sub, see choosing the username claim) |
group:<group> |
an OIDC user who has this group in the groups claim |
A token entry with a role is a global binding of that role, as before. To give a token only space bindings,
leave its role empty: ci-billing::<sha256>. Such an entry needs at least one token:ci-billing binding.
A principal is allowed a permission in a space when one of its bindings grants it globally, or grants it in that
space and the permission is a space permission. A binding of admin in a space therefore grants every space
permission there but none of the global ones (stubs:purge, system:reset, audit:read, contracts:secrets
and so on).
info:read comes with any binding.
contracts:secrets is granted only by global bindings. A space binding of admin, or of a custom role that gets
the permission through a wildcard (contracts:*), is accepted and simply does not grant it; GET /__admin/info
shows the permissions the caller actually holds. A space binding of a custom role that lists contracts:secrets
by name stops the start:
access file /etc/fastmock/access/access.yaml: bindings[1] (group:qa): role `secret-runner` lists contracts:secrets, a global permission that a binding limited to spaces cannot grant (contract secrets are server-wide); bind the role with global: true or remove contracts:secrets from it
Bind such a role with global: true, or remove contracts:secrets from it.
All spaces¶
spaces: ["*"] binds the role in every space of the access file, including spaces added to the file later: once
the server restarts with a new space, the binding covers it without a change of its own. Quote the *; a bare
* is not valid YAML there.
In each space the binding grants what a binding naming that space would grant, and nothing more:
- it does not grant global data: stubs, journal entries, files, scenario states and key-value entries of the global area, and requests that no stub matched, still need a global binding;
- it does not grant global permissions (
stubs:purge,system:reset,audit:read,access:read,contracts:secrets,recordings:*,chaos:*,grpc:*, see Permissions); - a principal with such a binding counts as bound to several spaces, so writes without
spaceanswer400(Selecting a space), unless the file defines exactly one space.
* must be the only entry, and the file must define at least one space; otherwise the server does not start:
access file /etc/fastmock/access/access.yaml: bindings[2] (group:qa): "*" must be the only entry in spaces
access file /etc/fastmock/access/access.yaml: bindings[2] (group:qa): spaces: ["*"] needs at least one space in the file
A custom role that lists contracts:secrets by name is refused with spaces: ["*"] exactly as in any other space
binding (see above).
A developer who works in several spaces¶
There are three ways to give one person or team access to several spaces:
- List the spaces in the binding:
spaces: [payments, billing]. The binding covers exactly these spaces; a new space needs a change of the file. - Use groups. Bind each team's group in its space and add the person to the groups at the identity provider. Group changes take effect at the next sign-in, without a change of the file.
- Bind all spaces with
spaces: ["*"], for someone who works with every team, such as a QA lead or an engineer on support duty, and should keep working in spaces added later.
Use global: true instead when the person also needs global data (global stubs, unmatched requests, global files
and state) or global permissions such as recordings, chaos rules, gRPC descriptors, the audit log or the access
configuration. Bindings combine: a global viewer binding together with an editor binding in ["*"] lets a
person read everything and change the stubs and test data of every space, but nothing in the global area.
spaces:
- name: payments
- name: billing
- name: orders
bindings:
- subject: group:payments-dev
role: editor
spaces: [payments, billing]
- subject: group:qa
role: editor
spaces: ["*"]
- subject: group:qa
role: viewer
global: true
- subject: group:platform
role: admin
global: true
Managed tokens¶
Besides the static entries of FASTMOCK_ADMIN_TOKENS, tokens can be created and revoked through the admin API
without a restart. A managed token has a name, one role (built-in or custom) and a scope: global or a list of
spaces. Its expiry is mandatory. Managed tokens need authentication: while FASTMOCK_AUTH_DISABLED=true, they
cannot be created or revoked, and POST /__admin/tokens answers
409 {"error":"managed tokens cannot be created while authentication is disabled (FASTMOCK_AUTH_DISABLED=true)","details":[]}
(revoked for DELETE /__admin/tokens/{id}).
curl -s -X POST localhost:9090/__admin/tokens -H "Authorization: Bearer $ADMIN_TOKEN" \
-H 'content-type: application/json' \
-d '{"name": "ci-billing-nightly", "role": "editor", "spaces": ["billing"], "expiresInDays": 30, "description": "CI of the billing team"}'
{"token": "fm_3f9c...", "id": "019a8f1e-...", "name": "ci-billing-nightly", "role": "editor", "spaces": ["billing"],
"global": false, "description": "CI of the billing team", "createdBy": "ops", "createdAt": "2026-11-20T09:00:00Z",
"expiresAt": "2026-12-20T09:00:00Z", "lastUsedAt": null, "revokedAt": null, "status": "active"}
The value (fm_ and 64 hex digits, the same format as fastmock hash-token --generate) is returned only in this
response; FastMock stores its SHA-256 hash. Store it in your secret manager right away.
| Field | Meaning |
|---|---|
name |
[A-Za-z0-9._@-], at most 128 characters. Unique among active tokens and different from every static token name (409 otherwise); a name becomes free again when its token is revoked or expired. It appears as the principal name in /info, logs and the audit log. |
role |
viewer, editor, admin or a custom role of the access file. |
spaces or global: true |
Exactly one of them. A token in spaces gets the role's space permissions in each of them (like a space binding). spaces: ["*"] gives them in every space of the access file, including spaces added later, like a binding in all spaces; * must be the only entry (400 with "*" must be the only entry in spaces otherwise), and the access file must define at least one space (400 with spaces: ["*"] needs at least one space in the access file otherwise). The token keeps ["*"] as stored, and the spaces are resolved on every request. |
expiresInDays |
1 to FASTMOCK_TOKENS_MAX_DAYS (default 365). When omitted: 90 days, or FASTMOCK_TOKENS_MAX_DAYS when lower. A token created by a managed token never outlives it (see below). |
description |
Optional, at most 1024 bytes. |
| Endpoint | Permission |
|---|---|
POST /tokens |
the escalation rule below |
GET /tokens |
tokens:read; lists the tokens for which the caller holds tokens:read in every scope (global tokens need it globally). Filters: ?space= (a token in all spaces belongs to every space), ?status=active\|expired\|revoked. |
GET /tokens/{id} |
tokens:read in every scope of the token; others answer 404 |
DELETE /tokens/{id} |
tokens:write in every scope of the token, or the token itself (self-revocation) |
GET /tokens/self |
the managed token itself (any static token gets 404) |
GET /tokens/options |
tokens:write somewhere; the roles with the scopes where the caller may grant them under the escalation rule (global, spaces, and allSpaces when the caller may create tokens in all spaces with the role), and maxDays/defaultDays (used by the UI's create form) |
Escalation rule. The caller can create a token only if, in each requested scope, it holds tokens:write and
every permission the role grants there: for a global token, globally; for a token in space s, the space
permissions of the role in s; for a token in all spaces (spaces: ["*"]), each of these either globally or
through the caller's own binding or token in all spaces. Being bound to every current space one by one is not
enough, because a token in all spaces also covers spaces added later. A token therefore never holds more than its
creator, and a caller bound only to spaces cannot create a global token. A denial names the first missing
permission:
403 {"error":"forbidden","details":["requires permission files:write in space billing to grant role editor there"],"required":"files:write"}.
The built-in editor role lacks tokens:write; to let a team manage its own tokens, bind a custom role with
tokens:read and tokens:write in its space:
roles:
- name: team-lead
permissions: [stubs:*, imports:run, journal:*, files:*, callbacks:*, state:*, contracts:read,
contracts:details, contracts:write, tokens:read, tokens:write]
bindings:
- subject: token:billing-lead
role: team-lead
spaces: [billing]
Lifecycle.
- Use: static tokens are checked first, in constant time; a value in the managed format is then looked up by
its hash. Each replica caches the result of a lookup (including "unknown") for at most 10 seconds. While the
store holds no managed token at all, a replica remembers that for up to 10 seconds and answers unknown values
without a lookup; so the first token created on one replica may be rejected (
401) on the others for up to 10 seconds. Later tokens are found at once. - Revocation (
DELETE /tokens/{id}) takes effect at once on the replica that handled it and within 10 seconds on every other replica of the same storage. Revoking again answers200and changes nothing. - Expiry is checked on every request against the stored time, so an expired token stops working at once
everywhere (
401 {"error":"unauthorized","details":["token expired"]}). lastUsedAtis written in the background at most once per minute per token; it never delays a request.- A token created by another managed token cannot outlive its creator: its
expiresAtis capped at the creator's, and the metadata of the new token carries the creator's id asparentId. Revoking a token also revokes the tokens it created, and a managed token whose own creator token is no longer active cannot create tokens (401). - Tokens created by an SSO user keep working after the user loses its groups at the provider or leaves. The token
list shows the creator (
createdBy); revoke a person's tokens as part of off-boarding. - Revoked and expired tokens stay listed with
statusrevokedorexpiredfor 90 days, then they are deleted. - If the role of a token disappears from the access file, the token is rejected until the role is back.
- A token in all spaces grants nothing in spaces while the access file defines none; requests are not refused for that reason, and the token covers the spaces as soon as the file defines them.
- A token in all spaces may create tokens in all spaces or in any list of spaces, within the escalation rule; the expiry cap and the revocation of the tokens it created apply as for any managed token.
- In memory mode (
FASTMOCK_STORAGE=memory) managed tokens live in the process and are lost on restart. With PostgreSQL they are stored infm_api_tokensand shared by all replicas.
The token's own principal has kind apiToken (GET /__admin/info), and the audit log records token.create and
token.revoke with the token's id, name, kind, role, scopes and expiry; the value never appears in logs, the audit
log or later responses.
OIDC sign-in and bearer JWTs¶
FastMock can sign users in through an OpenID Connect provider (Keycloak, Microsoft Entra ID, Okta, Auth0, ADFS, Dex, Authentik and others) and accept the provider's JWTs as bearer tokens on the admin API. FastMock implements only OIDC: LDAP, Active Directory and SAML users come through the provider (for Keycloak: user federation and identity brokering, see below). Static and managed tokens keep working next to it, and the UI's token login stays available.
How it works¶
The UI signs in through the admin port (backend for frontend): the browser never sees an OIDC token.
GET /__admin/auth/login?return=/ui/stubsanswers302to the provider's authorization endpoint withresponse_type=code,state,nonceand a PKCEcode_challenge(S256). The pending login (nonce, PKCE verifier, return path) is kept for 10 minutes in the hot store (Valkey, or process memory in memory mode) under the hash ofstate. A short-lived cookie__Host-fastmock_loginties the callback to the browser that started the login, so a callback URL sent to someone else does not sign them in.- The provider redirects to
GET /__admin/auth/callback?code=...&state=.... FastMock takes the pending login (eachstateworks once), checks the login cookie, exchanges the code (with the client secret and the PKCE verifier) and validates the ID token: signature against the provider's JWKS,iss,aud,azpwhen present,exp,nbf,iat(60 seconds of clock skew) andnonce. Accepted algorithms: RS256, PS256, ES256 and EdDSA (Ed25519);noneand HMAC algorithms are always rejected. A token signed with an unknown key id makes FastMock fetch the JWKS again, at most once a minute. - The username and groups come from the ID token (
FASTMOCK_OIDC_USERNAME_CLAIM, defaultpreferred_username;FASTMOCK_OIDC_GROUPS_CLAIM, defaultgroups). When the ID token has no groups claim (or no username claim), FastMock asks the userinfo endpoint. The groups claim may be a name or a dotted path (realm_access.roles); a claim whose name itself contains dots (https://example.com/groups) is found by its full name first. - FastMock computes the user's bindings (
user:<username>andgroup:<group>subjects). Without any binding no session is created: the browser goes to/ui/?loginError=no_accessand the login is audited as failed. Otherwise FastMock creates a session and redirects to thereturnpath with the session cookie.
return must be a relative path under /ui/. Values starting with //, containing a backslash, a scheme,
.. segments, control characters or the same tricks percent-encoded answer 400.
loginError |
Meaning |
|---|---|
no_access |
the user signed in at the provider but no binding matches the user or its groups |
invalid_state |
unknown, expired (10 minutes) or already used state, or the login cookie is missing or different |
idp_error |
the provider answered with an error (for example the user cancelled) |
failed |
code exchange or ID token validation failed, or the username claim is missing; the log says why |
unavailable |
the provider has not been discovered yet or the session store is unavailable |
Choosing the username claim¶
user: bindings match the value of FASTMOCK_OIDC_USERNAME_CLAIM. Bind users by a claim that is unique per
user, never reassigned and not editable by the user: sub, or oid with Microsoft Entra ID. Display names,
preferred_username and email can change or be reused at many providers, so use them only where your provider
guarantees otherwise. When the username claim is email, sign-in requires email_verified: true in the token.
The claim value is also the principal name in /__admin/info, logs and the audit log. Binding by
group avoids per-user entries altogether.
Sessions¶
| Property | Value |
|---|---|
| Cookie | __Host-fastmock_session, Secure, HttpOnly, SameSite=Lax, Path=/, Max-Age = FASTMOCK_OIDC_SESSION_TTL |
| Value | 256 random bits (43 base64url characters) |
| Server side | in the hot store under the SHA-256 of the value: user name, group names, creation and last-seen time, and the ID token of the sign-in (for the logout hint) |
| Lifetime | absolute FASTMOCK_OIDC_SESSION_TTL (default 8h) and idle FASTMOCK_OIDC_SESSION_IDLE (default 1h); the groups captured at sign-in are kept until one of them expires |
| Replicas | every replica and every cluster sharing the Valkey sees the same sessions; in memory mode they live in the process |
The last-seen time is written back at most once a minute (and at least four times per idle period), so the idle
timeout can be exceeded by up to a quarter of it. The bindings are computed from the access file on every request,
so a changed access file applies to existing sessions after the restart. The groups are captured at sign-in and
kept until the idle or absolute expiry of the session; set FASTMOCK_OIDC_SESSION_IDLE and
FASTMOCK_OIDC_SESSION_TTL to how quickly group changes at the provider must take effect.
An expired or unknown session answers 401 {"error":"unauthorized","details":["session expired or unknown: sign in again"]}
and clears the cookie.
POST /__admin/auth/logout deletes the session and clears the cookie. When the provider publishes an
end_session_endpoint, the response carries logoutUrl so the UI can end the provider session too. The URL has
client_id, post_logout_redirect_uri set to the admin URL's /ui/ (which shows the sign-in page once the
session is gone) and id_token_hint with the ID token of the sign-in, so the provider ends its session without
asking the user to confirm:
{"loggedOut": true, "logoutUrl": "https://sso.example.com/realms/mocks/protocol/openid-connect/logout?client_id=fastmock&post_logout_redirect_uri=https%3A%2F%2Fmock-admin.example.com%2Fui%2F&id_token_hint=eyJhbGciOi..."}
The ID token is kept only in the session record in the hot store and leaves the server only in this URL, which goes to the browser that signed in. It is never put in a cookie or logged. ID tokens up to 64 KiB are accepted at sign-in, so users with many groups can sign in; ID tokens larger than 16 KiB are not kept in the session, and the logout then goes without the hint and the provider may ask for confirmation. Sessions created by an earlier version have no ID token either.
GET /__admin/auth/config (no authentication) tells the login page what is available:
{"oidc": true, "tokenLogin": true}.
Local development over http. Browsers keep Secure cookies only on https, except on localhost where most
browsers accept them over plain http too. For other local setups set FASTMOCK_OIDC_INSECURE_COOKIE=true: the
cookies are then called fastmock_session and fastmock_login and lose Secure (the __Host- prefix requires
it). The switch is accepted only when FASTMOCK_OIDC_REDIRECT_URL points to localhost, 127.0.0.1 or ::1.
CSRF protection¶
Requests authenticated by the session cookie that are not GET or HEAD must carry the header
X-FastMock-Request: 1; otherwise they answer 403 {"error":"forbidden","details":["missing X-FastMock-Request: 1 header"]}.
A cross-origin page cannot add the header without a CORS preflight, which the admin API never grants. The header
comes on top of the Origin check that applies to every admin request. POST /__admin/auth/logout needs it too.
Requests with an Authorization header are not affected.
Bearer JWTs on the admin API¶
With FASTMOCK_OIDC_API_AUDIENCE set, a bearer value that is not a static token and has three dot-separated
parts (whatever their content and length) is treated as a JWT and validated like the ID token, but against that audience, without nonce and without azp (the token may have been issued to
another client, for example a CI pipeline using client credentials or a CLI using the device flow). iat is
optional. The username claim falls back to sub when absent; the groups claim is read from the token (userinfo is
not called). Tokens that carry a nonce claim (ID tokens) are rejected, and so are tokens larger than 64 KiB. The
audience must differ from the client id: FASTMOCK_OIDC_API_AUDIENCE set to an empty value, or to the value of
FASTMOCK_OIDC_CLIENT_ID, stops the start. An empty value stops it with
FASTMOCK_OIDC_API_AUDIENCE is set but empty: set the audience of the API tokens, or remove the variable to turn bearer JWTs off.
When the variable is not set at all, bearer JWTs are off.
Precedence: a request with an Authorization header is decided by that header alone, in this order: static
tokens, managed fm_ tokens, JWTs. The session cookie is used only when there is no Authorization header. A
JWT for a user without bindings answers 403 with
"details":["user alice has no access: the access file binds neither user:alice nor any of the user's groups"].
An invalid JWT answers 401 {"error":"unauthorized","details":["invalid bearer token"]} with
WWW-Authenticate: Bearer error="invalid_token".
Configuration¶
| Variable | Default | Meaning |
|---|---|---|
FASTMOCK_OIDC_ISSUER |
none | Issuer URL; OIDC is off without it. https (plain http only for localhost, 127.0.0.1 and ::1, for tests). Must equal the issuer of the discovery document exactly. |
FASTMOCK_OIDC_CLIENT_ID |
none | Client id (required). |
FASTMOCK_OIDC_CLIENT_SECRET / _SECRET_FILE |
none | Client secret, one of the two (required). |
FASTMOCK_OIDC_REDIRECT_URL |
none | Public admin URL followed by /__admin/auth/callback (required, https except on localhost). Register it at the provider. |
FASTMOCK_OIDC_SCOPES |
openid profile email |
Space- or comma-separated; must include openid. |
FASTMOCK_OIDC_USERNAME_CLAIM |
preferred_username |
Claim (or dotted path) with the user name for user: bindings; sub (or oid with Entra ID) is recommended (choosing the username claim). With email, sign-in requires email_verified: true. |
FASTMOCK_OIDC_GROUPS_CLAIM |
groups |
Claim (or dotted path such as realm_access.roles) with the groups for group: bindings: an array of strings or one string. |
FASTMOCK_OIDC_API_AUDIENCE |
none | Enables bearer JWTs on the admin API for this audience; unset, bearer JWTs are off. Set but empty, or equal to the client id, stops the start. |
FASTMOCK_OIDC_CA_FILE |
none | PEM bundle added to the trusted roots for the provider connections. |
FASTMOCK_OIDC_SESSION_TTL |
8h |
Absolute session lifetime. |
FASTMOCK_OIDC_SESSION_IDLE |
1h |
Idle timeout. |
FASTMOCK_OIDC_ALLOWED_HOSTS |
none | Hosts besides the issuer's that discovery endpoints may use (comma-separated). |
FASTMOCK_OIDC_INSECURE_COOKIE |
false |
Cookies without Secure and __Host- for local http development (localhost redirect URL only). |
Everything is checked at start-up; errors name the variable. With OIDC configured, FASTMOCK_ADMIN_TOKENS may be
empty (sign-in only), and FASTMOCK_AUTH_DISABLED=true is refused.
Discovery and egress. At start-up FastMock reads <issuer>/.well-known/openid-configuration and the JWKS. If
the provider cannot be reached within 5 seconds the server starts anyway (the data plane and token
authentication work) and retries in the background with backoff up to one minute; until then
/__admin/auth/login answers 503 and the gauge fastmock_oidc_ready is 0. A discovery document that FastMock
must not use stops the start with a clear error: a different issuer, an endpoint on a host other than the
issuer's and not in FASTMOCK_OIDC_ALLOWED_HOSTS, plain http outside loopback, or no PKCE S256 support. All
provider calls (discovery, JWKS, token, userinfo) use a dedicated HTTP client: only to the issuer host and the
allowed hosts, redirects only to those hosts (at most three; the call to the token endpoint follows no redirects,
so the discovered token_endpoint must answer directly), 5 seconds to connect, 10 seconds per request,
responses up to 1 MiB, the system roots plus FASTMOCK_OIDC_CA_FILE. The client honours HTTPS_PROXY and
NO_PROXY. These calls are not subject to the egress policy for stub callbacks, so
the provider may live on a private network. The client authenticates at the token endpoint with
client_secret_basic, or client_secret_post when the provider supports only that. The JWKS is refreshed every
hour and on an unknown key id.
Starting logins is limited to a burst of 100 and 10 per second per replica (429 above), so anonymous callers
cannot fill the hot store with pending logins.
Keycloak¶
- Clients → Create client: type OpenID Connect, client id
fastmock. Client authentication on (a confidential client), Standard flow on, Direct access grants off. PKCE: in Advanced set Proof Key for Code Exchange Code Challenge Method toS256. - Valid redirect URIs:
https://mock-admin.example.com/__admin/auth/callback. Valid post logout redirect URIs:https://mock-admin.example.com/ui/. Web origins: leave empty (the browser never calls Keycloak with JavaScript). - Credentials: copy the client secret into a Secret (
FASTMOCK_OIDC_CLIENT_SECRET_FILE). - Groups: Client scopes →
fastmock-dedicated→ Add mapper → By configuration → Group Membership, token claim namegroups, Full group path off (otherwise the values are/payments-dev), added to the ID token, the access token and userinfo. To bind realm roles instead, setFASTMOCK_OIDC_GROUPS_CLAIM=realm_access.roles. - For API JWTs, add an Audience mapper with Included custom audience
fastmock-apito the client scope that CI clients request, and setFASTMOCK_OIDC_API_AUDIENCE=fastmock-api. A CI pipeline then uses a separate confidential client with Service accounts on (client credentials). Add its service account user to a group (for exampleci-payments) and bindgroup:ci-payments; withFASTMOCK_OIDC_USERNAME_CLAIM=subyou can instead binduser:<id of the service account user>. FASTMOCK_OIDC_ISSUER=https://sso.example.com/realms/mocks.
LDAP and Active Directory users. Configure User federation → LDAP in the realm (vendor Active Directory
or Other), and add a group-ldap-mapper (mode READ_ONLY) that imports the LDAP groups. The users sign in
through Keycloak with their directory password; their directory groups arrive in the groups claim and match
group: bindings by name. FastMock never talks to LDAP.
SAML. Add the SAML identity provider under Identity providers (identity brokering) and map its group or role attribute to Keycloak groups with an Advanced attribute to group or Attribute importer mapper. Users choose the SAML provider on the Keycloak login page; FastMock still sees an OIDC sign-in.
Microsoft Entra ID¶
- App registrations → New registration; Redirect URI type Web:
https://mock-admin.example.com/__admin/auth/callback. Addhttps://mock-admin.example.com/ui/as a second Web redirect URI, so that the provider returns the browser to the UI after logout (post_logout_redirect_uri). - Certificates & secrets → New client secret; store it in a Secret.
- Token configuration → Add groups claim: Security groups (or Groups assigned to the application, which
avoids the 200-group limit of the token). The values are group object ids, so bindings look like
group:5f1c3f6e-0000-4000-8000-000000000001. For groups synchronised from Active Directory you can emitsAMAccountNameinstead and bind by name. - Settings:
FASTMOCK_OIDC_ISSUER=https://login.microsoftonline.com/<tenant id>/v2.0,FASTMOCK_OIDC_CLIENT_ID=<application id>,FASTMOCK_OIDC_USERNAME_CLAIM=oid(the user's object id, which never changes or moves to another user), souser:bindings look likeuser:3d0f6c1e-0000-4000-8000-000000000002. Microsoft advises against authorizing bypreferred_username(the UPN) oremail; prefer group bindings for teams. - For API JWTs, Expose an API with an application id URI such as
api://fastmockand setFASTMOCK_OIDC_API_AUDIENCEto theaudvalue of the access tokens (the application id for v2 tokens). App roles assigned to service principals arrive in therolesclaim; setFASTMOCK_OIDC_GROUPS_CLAIM=rolesif you bind by app role.
Users with more groups than fit in the token (more than 200) get an overage claim instead of groups; FastMock
then sees no groups. Use Groups assigned to the application to avoid it.
Other providers¶
Any provider with OIDC discovery, the authorization code flow with PKCE S256, a confidential client and RS256, PS256, ES256 or EdDSA signatures works:
- Create a confidential web client with the redirect URI
https://<admin host>/__admin/auth/callback. - Make the provider put the user's groups into the ID token (or userinfo) as an array of strings, and note the
claim name (
groups,roles, a namespaced claim such ashttps://example.com/groups, or a nested path). - Check the issuer:
curl https://<issuer>/.well-known/openid-configuration | jq .issuermust print exactly the value ofFASTMOCK_OIDC_ISSUER, including a trailing slash if there is one. - If the token or JWKS endpoint lives on another host than the issuer, list it in
FASTMOCK_OIDC_ALLOWED_HOSTS. - The
token_endpointof the discovery document must answer the code exchange itself: FastMock follows no redirects on that call. Behind a proxy or load balancer that redirects, publish the final URL in discovery.
ADFS works as an OIDC provider (Server application plus Web API in an application group); its groups come from a claim issuance rule.
Example¶
spaces:
- name: payments
pathPrefixes: [/payments/]
bindings:
- subject: group:payments-dev
role: editor
spaces: [payments]
- subject: group:platform
role: admin
global: true
- subject: group:ci-payments
role: editor
spaces: [payments]
FASTMOCK_OIDC_ISSUER=https://sso.example.com/realms/mocks
FASTMOCK_OIDC_CLIENT_ID=fastmock
FASTMOCK_OIDC_CLIENT_SECRET_FILE=/etc/fastmock/oidc/client-secret
FASTMOCK_OIDC_REDIRECT_URL=https://mock-admin.example.com/__admin/auth/callback
FASTMOCK_OIDC_API_AUDIENCE=fastmock-api
# a CI job with a client-credentials token from the provider
TOKEN=$(curl -s -d grant_type=client_credentials -u "ci-payments:$CI_SECRET" \
https://sso.example.com/realms/mocks/protocol/openid-connect/token | jq -r .access_token)
curl -s https://mock-admin.example.com/__admin/stubs?space=payments -H "Authorization: Bearer $TOKEN"
Login, failed login and logout are audit events (auth.login with the group names, auth.login_failed with the
reason, auth.logout); changes made by a user record principalKind: user. Codes, tokens (the ID token
included), session ids, the client secret and the PKCE verifier are never logged.
Spaces¶
A space is a named partition, named like a Kubernetes namespace ([a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?).
| Field | Meaning |
|---|---|
name |
The space name. |
description |
Optional text, shown by GET /__admin/spaces. |
pathPrefixes |
Optional data-plane path prefixes that the space's stubs must stay under (ownership). Each must be a plain path starting with /: no query, fragment, . or .. segment, encoded slash or backslash (%2F, %5C) or backslash. |
hosts |
Optional Host values the space's stubs must match. |
What belongs to a space:
- Stubs carry a
spacefield. It is set on create and never changes:PUTandPATCHkeep the stored space and reject a different one (move a stub by deleting and creating it, both authorised). - Journal entries get the space of the stub that matched. Requests that no stub matched, and requests
matched by global stubs, belong to no space and are visible only with global
journal:read. - Callback jobs get the space of the stub that scheduled them. Callbacks scheduled by a plugin get the space of the stub being answered or, on a plugin route, the space that owns the request's path or host (when exactly one space does).
- Scenario states, key-value entries and body files of a space are stored apart from global data, in a key
namespace of their own. Two spaces can use the same scenario name, key or file name independently, and a global
name such as
payments/xis always global data, even when a spacepaymentsexists. Entries written by a principal bound to a space go to its space; global principals see and write global data as before, so existing state and files need no migration. - Data used by a stub comes from the stub's space: its scenario states and key-value entries are those of its
space, and
bodyFileNameis resolved among the files of its space first, then among the global files. A stub never resolves a file, scenario or key of another space, also when the name is built by a template. Global body files are therefore shared with every space: keep files that belong to one team in that team's space, and keep only files meant for everyone in the global area. - Contract test runs carry the space they were started in.
Messages published to Kafka, gRPC descriptors, chaos rules, global settings, recordings, async mocks and the service catalog are not scoped. On the data plane every enabled stub competes for a request, except inside the paths and hosts that a space owns (ownership).
A request naming a space that the access file does not define, or a space the caller cannot see (it holds no
space permission globally, info:read aside, and has no binding there), answers 404.
Selecting a space in the API¶
Collection endpoints take a space query parameter; stubs also take a space field.
| Caller | Reads without space |
Writes without space |
|---|---|---|
| holds the permission globally | everything (global area and every space) | the global area |
| bound only to spaces | the union of the spaces where it holds the permission | its space when it has exactly one; otherwise 400 |
With space, reads and writes apply to that space, and the caller must hold the permission there: a space the
caller cannot see answers 404 like an unknown one, a visible space without the permission 403. Deletions that select existing items (DELETE /requests, DELETE /callbacks, DELETE /scenarios,
DELETE /stubs?tag=, POST /stubs/remove-by-metadata, POST /requests/remove, DELETE /stubs/counters) select
like reads: without space they act on everything the caller may change. Single items (/stubs/{id},
/requests/{id}, /contract-tests/{id}) are found by id; one in a space the caller cannot read answers 404.
/kv/{key}, /scenarios/{name} and /files/{name} address one entry and resolve the space like writes. Stub ids
are unique across all spaces: POST /stubs or an import with an id that belongs to a stub in another space or in
the global area answers 409 with a generic conflict message.
| Endpoint | How the space is given |
|---|---|
POST /stubs |
space field of the stub or space query parameter (they must agree) |
POST /stubs/import, POST /import, /import/openapi, /import/wiremock, /import/postman, /import/har, /import/mockserver |
space query parameter; every imported stub goes to that space, and replaceTag/replace removes only that space's stubs with the tag. For a space that owns hosts, the host query parameter sets request.host on every imported stub; it defaults to the space's only host and is required when the space owns several |
| other collection endpoints | space query parameter |
Imports into a space are not recorded in the service catalog, which is global.
Ownership of the data plane¶
A space with pathPrefixes or hosts owns that part of the data plane.
Stubs of the space stay inside it. Every stub in the space must match only inside its prefixes and hosts,
checked on create, update and import (400 with the reason):
- with
pathPrefixes, the stub's URL matcher must beurl,urlPathorurlPathTemplatelying under one of the prefixes (/payments/and/paymentsboth allow/payments/x, neither allows/paymentsx). Regular expression matchers (urlPattern,urlPathPattern) and stubs without a URL matcher are rejected, and so are paths with a.or..segment, plain or percent-encoded (/payments/../billing/x,/payments/%2E%2E/x), and paths with an encoded slash or backslash in any case or a raw backslash (/payments/..%2Fbilling/x,/payments/a%5Cb,/payments\x), which a proxy or server that decodes them would read as other segments; - with
hosts, the stub must have arequest.hostmatcher withequalToone of the hosts and nothing else.
A space with both pathPrefixes and hosts needs both: the stub's path must lie under one of the prefixes and
its request.host must be one of the hosts. Importers set request.host from the host query parameter
(selecting a space).
The rules apply when a stub is written. Stubs stored before the access file gave the space prefixes or hosts, or
before it dropped the space, stay stored and keep their space. Each replica logs a warning at start-up for every
such stub (stored stub breaks the rules of its space, with stub_id, space and reason), and
GET /__admin/info lists them in warnings to principals that can read stubs in that space. Fix or delete them.
Owned prefixes and hosts do not overlap. Two spaces may not own overlapping path prefixes (such as
/payments/ and /payments/refunds/) or the same host; a host without a port overlaps the same host with any
port. An access file where they do stops the server at start-up, and the error names both spaces and the
conflicting values:
space payments and space refunds overlap: path prefix `/payments/` of space payments and `/payments/refunds/` of space refunds; each path belongs to one space.
Requests inside a space go to its stubs. A data-plane request whose path lies under a prefix owned by a space,
or whose Host is a host owned by a space, is answered only by stubs of that space or by global stubs; stubs of
other spaces are skipped for it. Requests outside every owned prefix and host are matched against all enabled
stubs as usual.
The data plane does not normalise request paths: the owning space is decided on the path as received, the same
path the stubs are matched against. A request is therefore answered only by stubs of the space that owns its
path as sent. Clients and proxies normally remove dot segments before sending; a request that keeps them, such as
/payments/../billing/x sent with curl --path-as-is, belongs to /payments/ and never reaches stubs of the
space that owns /billing/.
Stubs in the global area are not restricted; only principals with global stubs:write can create them. When
several teams share an instance, give each team's space the pathPrefixes or hosts of the traffic it mocks, so
that requests there are answered only by that team's stubs and global ones.
What is scoped and what is global¶
| Data | Scoped by space |
|---|---|
| stubs, journal entries, callback jobs, scenario states, key-value entries, body files, contract test runs, stub counters | yes |
| recordings, chaos rules, global settings, gRPC descriptors, async mocks, service catalog, Kafka messages, audit log | no (global permissions) |
Inspecting your permissions¶
GET /__admin/info returns the caller's principal:
{"principal": {"name": "ci-billing", "kind": "token", "role": "viewer",
"permissions": {"global": ["info:read"],
"spaces": {"billing": ["stubs:read", "stubs:write", "imports:run", "journal:read", "state:read"]},
"allSpaces": []}}}
permissions.global holds what is granted everywhere; permissions.spaces what is granted only in single spaces
(the effective permissions in a space are both lists together). permissions.allSpaces lists the permissions
granted through a binding or token in all spaces (empty when there is none); these permissions also
appear under every space of permissions.spaces, so clients that read only spaces keep working. kind is token for static tokens, apiToken
for managed tokens, user for OIDC users (anonymous when
authentication is disabled). Users also get groups, the group names from the provider. role is kept for older clients: the highest built-in role whose permissions
the principal holds everywhere, viewer when it holds less. stubsLoaded in the same response counts only the
stubs the caller can see.
GET /__admin/spaces lists the spaces the caller can see (every space for a principal that holds a space
permission globally or is bound in all spaces; info:read, which every principal has, does not count; otherwise its bound spaces) with the caller's permissions in each:
{"spaces": [{"name": "billing", "pathPrefixes": [], "hosts": [],
"permissions": ["stubs:read", "stubs:write", "imports:run", "journal:read", "state:read"]}]}
Viewing the access configuration¶
GET /__admin/access returns the configuration that the server loaded: spaces, roles and bindings, including the
global roles of static tokens. It needs the
global permission access:read, which the built-in admin role has; a custom role gets it by listing
access:read, access:* or "*" and being bound with global: true. Without an access file and OIDC it needs admin,
like every admin-only route.
{"configured": true, "oidc": true,
"spaces": [{"name": "billing", "pathPrefixes": ["/billing/"], "hosts": ["billing.example.com"]},
{"name": "payments", "pathPrefixes": ["/payments/"], "hosts": []}],
"roles": [{"name": "viewer", "builtin": true, "permissions": ["stubs:read", "journal:read", "..."]},
{"name": "editor", "builtin": true, "permissions": ["..."]},
{"name": "admin", "builtin": true, "permissions": ["..."]},
{"name": "ci", "builtin": false, "permissions": ["stubs:read", "stubs:write", "..."]}],
"bindings": [{"subject": "token:ci-payments", "role": "ci", "global": false, "spaces": ["payments"], "source": "accessFile"},
{"subject": "group:qa", "role": "editor", "global": false, "spaces": ["*"], "source": "accessFile"},
{"subject": "group:platform", "role": "admin", "global": true, "spaces": [], "source": "accessFile"},
{"subject": "token:ops", "role": "admin", "global": true, "spaces": [], "source": "adminTokens"}]}
| Field | Meaning |
|---|---|
configured |
an access file is loaded |
oidc |
OIDC sign-in or bearer JWTs are enabled |
spaces |
the spaces of the access file, sorted by name, with name, pathPrefixes and hosts |
roles |
the built-in roles first (viewer, editor, admin), then the custom roles sorted by name; permissions lists the permission names with wildcards expanded |
bindings |
the bindings of the access file in file order, then one global binding for each static token written name:role:hash in FASTMOCK_ADMIN_TOKENS or FASTMOCK_ADMIN_TOKENS_FILE, in entry order: subject (as written; token:<name> for a static token), role, global, spaces (["*"] for all spaces, empty for a global binding) and source |
bindings[].source |
accessFile for a binding of the access file, adminTokens for the role of a static token. A static token written name::hash (no role) has only its access-file bindings and adds no entry |
The response contains no token values or hashes, no file paths and no OIDC client settings. Without an access
file, configured is false, spaces is empty, roles holds the built-in roles and bindings holds only the
roles of static tokens (source: adminTokens). The response is read-only: spaces, roles and bindings change only
in the access file and the static token list, after a restart.
In the web UI¶
The web UI follows the same model; it has no privileges of its own and the server checks every call.
- Sign-in. With OIDC configured the sign-in page offers Sign in with SSO next to the token form. The UI
then uses the session cookie and sends
X-FastMock-Request: 1on every admin call; the account menu shows the user name, kind (token,managed tokenoruser), groups and bound spaces, and Sign out ends the session (and the provider session when it supports RP-initiated logout). The messages for eachloginErrorand for an expired session appear on the sign-in page. - Space selector. When the access file defines spaces, the header has a selector with the spaces the principal
can see, plus All spaces for principals with a global permission or several spaces. Lists (stubs, journal,
scenarios, callbacks, files, contract tests, tokens) send the selected space as
?space=and show a Space column; create and import forms preselect it and offer only the areas where the principal holds the needed permission. The choice is remembered in the browser. Without spaces the selector and the column are hidden. - Actions follow
principal.permissionsfromGET /__admin/info: controls the principal cannot use are hidden or disabled, and a disabled control's tooltip names the missing permission (for example "Requires the stubs:write permission in space billing"). - Admin tokens (visible with
tokens:readwhen the server liststokensin thefeaturesofGET /__admin/version) lists managed tokens with role, scope, creator, creation, expiry, last use and status, creates tokens limited to the roles and spaces ofGET /__admin/tokens/optionsand toFASTMOCK_TOKENS_MAX_DAYS, shows the new value once with a copy button, and revokes after a confirmation. All spaces is offered as a scope whereallSpacesof the chosen role istrue, and tokens in all spaces show All spaces in the list. - Access shows every signed-in user Your access: the global permissions and the effective permissions in
each space (All spaces for permissions granted in all spaces). With
access:readthe page also shows the spaces, roles and bindings ofGET /__admin/accessas read-only tables. Changes are made in the access file.
Errors¶
With an access file or OIDC configured, every 403 of the admin API has the same shape,
{"error":"forbidden","details":[...],"required":...}: details says what is missing and required names the
missing role or permission where there is one. With static tokens only, 403 bodies are those of earlier versions.
| Response | Meaning |
|---|---|
403 {"error":"forbidden","details":["requires role editor"],"required":"editor"} |
a principal holding only global built-in roles lacks the permission (as before) |
403 {"error":"forbidden","details":["requires permission files:read"],"required":"files:read"} |
any other principal lacks the permission |
403 {"error":"forbidden","details":["requires permission stubs:write in space billing"],"required":"stubs:write"} |
the permission is missing in the selected space |
400 {"error":"several spaces are bound (billing, payments); set space",...} |
a write without space by a principal bound to several spaces |
404 {"error":"space nope not found",...} |
unknown space, or a space the caller cannot see |
409 with a generic conflict message |
a stub id that belongs to a stub in another area |
400 {"error":"space payments owns /payments/, /psp/: ...",...} |
a stub outside the space's ownership |
403 {"error":"forbidden","details":["requires permission ... to grant role ... there"],"required":...} |
a token request that would exceed the caller's permissions (escalation rule) |
401 {"error":"unauthorized","details":["token expired"]} |
an expired managed token |
401 {"error":"unauthorized","details":["session expired or unknown: sign in again"]} |
an expired, logged-out or unknown session cookie |
401 {"error":"unauthorized","details":["invalid bearer token"]} |
a JWT that fails validation |
403 {"error":"forbidden","details":["missing X-FastMock-Request: 1 header"]} |
a cookie-authenticated change without the CSRF header |
403 {"error":"forbidden","details":["user bob has no access: ..."]} |
an OIDC user without any binding |
Denials count in fastmock_admin_auth_failures_total with reason="role" for principals holding only global
built-in roles and reason="permission" otherwise (including OIDC users without any binding); missing, unknown
and revoked tokens count as reason="token", expired managed tokens as reason="expired", rejected sessions as
reason="session", invalid JWTs as reason="jwt", missing CSRF headers as reason="csrf" and refused browser
origins as reason="origin". Audit events record the principal kind (principalKind) and the space of the
change (space).
Examples¶
A shared instance for two teams and a platform group, with the CI token of each team limited to its space:
roles:
- name: ci
permissions: [stubs:*, imports:run, journal:*, state:*, callbacks:*, files:*]
spaces:
- name: payments
pathPrefixes: [/payments/]
- name: billing
pathPrefixes: [/billing/]
hosts: [billing.example.com]
bindings:
- subject: token:ci-payments
role: ci
spaces: [payments]
- subject: token:ci-billing
role: ci
spaces: [billing]
- subject: token:dashboards
role: viewer
spaces: [payments, billing]
# FASTMOCK_ADMIN_TOKENS=ci-payments::<hash>,ci-billing::<hash>,dashboards::<hash>,ops:admin:<hash>
curl -s -X POST localhost:9090/__admin/stubs -H "Authorization: Bearer $CI_PAYMENTS_TOKEN" \
-H 'content-type: application/json' \
-d '{"request": {"method": "GET", "urlPath": "/payments/health"}, "response": {"status": 200}}'
# the stub lands in space payments, the only space of the token
curl -s "localhost:9090/__admin/requests?space=payments" -H "Authorization: Bearer $DASHBOARDS_TOKEN"
With Helm, put the same document under the access value (Helm: access control).
Upgrade notes¶
These notes apply when upgrading from a release without access control. Without an access file and without OIDC,
every endpoint keeps its role, response bodies (including every 403) are unchanged, and existing stubs, journal
entries, state and files stay in the global area. Check the points below before rolling out.
403 bodies. Once an access file or OIDC is configured, every 403 of the admin API reads
{"error":"forbidden","details":[...],"required":...}, also on routes whose 403 had another error text before
(Errors). Clients and scripts that match the error text of a 403 should read details and required
instead.
Database. The migrations are additive:
| Change | Tables |
|---|---|
new nullable space column |
fm_stubs, fm_journal, fm_outbox |
new nullable principal_kind and space columns |
fm_audit |
| new table for managed tokens | fm_api_tokens |
The migration that adds the space columns only adds them, in a short transaction. The three indexes on these
columns are built by separate migrations, one index each, with CREATE INDEX CONCURRENTLY IF NOT EXISTS outside a
transaction, so journal, callback and stub writes of running replicas are not blocked while a large journal is
indexed. Allow for the index build time in FASTMOCK_DATABASE_MIGRATION_TIMEOUT and the startup probe, or
run migrations separately. If you run migrations separately and grant the server user rights per table,
grant them on the new table too, for example
GRANT SELECT, INSERT, UPDATE, DELETE ON fm_api_tokens TO fastmock;. Without it the server starts, but managed
tokens cannot be created or used (a managed token answers 503 {"error":"token store unavailable",...}).
Logs. Audit log lines (target audit) change:
role=Adminbecomesrole=admin(lowercase, the role names of the principal's bindings);- the lines carry a new
kindfield (token,apiToken,user,anonymous) and, for changes inside a space,space; - the rejection line
admin request rejected: role too lownow readsadmin request rejected: permission missingand carries the missingpermission.
Update log-based alerts and dashboards that match these strings.
Metrics. Denials of admin-only routes (GET /audit, POST /reset, DELETE /stubs without tag) by a
non-admin are now counted in fastmock_admin_auth_failures_total{reason="role"} and write an audit warning line;
before, only the response was sent. fastmock_admin_auth_failures_total has new reason values, and
fastmock_store_errors_total new store values, see Observability. New metrics:
fastmock_api_tokens_active, fastmock_oidc_logins_total, fastmock_oidc_ready.
New routes. GET /__admin/auth/config, GET /__admin/auth/login, GET /__admin/auth/callback and
POST /__admin/auth/logout are reached without an admin token (the sign-in flow needs them). If a WAF, a Gateway
or a route allow-list sits in front of the admin port, allow them when you use OIDC sign-in; without OIDC they
answer 404, except /auth/config. The token endpoints /__admin/tokens*, GET /__admin/spaces and
GET /__admin/access need authentication like every other admin route; GET /__admin/access needs the global
permission access:read (admin). Custom roles bound with global: true that should see the
access configuration need access:read added.
Unlisted admin paths. With an access file or OIDC configured, an admin route without an explicit permission,
including an unknown path under /__admin, needs admin: a non-admin gets 403 there where it got 404 before.
Without them nothing changes: an unknown path answers 404 to a caller whose role allows the method. Plugin routes under
/__admin/plugins/<name>/ keep viewer for GET and editor for other methods.
Rolling upgrade and rollback. Upgrade every replica before you add an access file, create spaces or let
teams create stubs in spaces; while old and new versions run side by side, the old ones do not know spaces. A
previous version that starts against the new schema ignores the new columns and tables. Replicas of earlier
versions that are already running when the first new pod adds the columns may log
cached plan must not change result type and fail to claim callbacks or read the journal until they are
replaced, usually for a few seconds; due callbacks wait for a new replica and are then sent. From this version on
the queries name their columns, so later additive migrations do not cause this. After a rollback, stubs
in spaces behave as global stubs, the files, scenario states and key-value entries of spaces are not visible,
and managed tokens and SSO sign-in are not available. Before rolling back, remove the access file and the OIDC
settings, and give every entry of FASTMOCK_ADMIN_TOKENS / FASTMOCK_ADMIN_TOKENS_FILE a built-in role again: the
previous version refuses to start with an empty or custom role in a token entry.
Migrating an existing installation¶
- Upgrade as described in the upgrade notes: without an access file the behaviour is unchanged, and existing rows stay in the global area.
- Add spaces and bindings in the access file. Existing global tokens keep their global role, so they keep seeing and changing everything.
- Give teams new tokens with an empty role and space bindings (
name::<hash>plustoken:namebindings), create managed tokens for them, or bind their OIDC groups. Move their stubs into their space by exporting them (GET /__admin/export?tag=...), importing them with?space=<space>and deleting the global copies. - Clients that read
principal.rolefrom/__admin/infokeep working; useprincipal.permissionsfor new decisions.403responses carryerror,detailsandrequired; with an access file or OIDC,erroris alwaysforbidden(Errors).