Gate One configuration

userId

string

no

Default X-User-Id.

username

string

no

Default X-Username.

email

string

no

Default X-Email.

roles

string

no

Default X-Roles (comma-separated).

scopes

string

no

Default X-Scopes (comma-separated).

claims

string

no

Default X-Claims (base64 JSON).

account

object

no

A link rendered in the expanded user badge. URL: http(s) absolute or a local absolute path (/…​); javascript:/data: are refused. target defaults to _blank; rel is forced to noopener noreferrer.

type

string (one of: bolt, redis)

no

bolt (default, single instance) or redis (shared, multi-instance, immediate revocation).

path

string

no

bbolt file path. Default ./gate-one-state.db (relative to the config file).

url

string

no

Redis URL for type redis (redis:// or rediss://). Mutually exclusive with sentinel mode.

sentinelAddrs

array of string

no

Redis Sentinel addresses (host:port). Required with masterName.

masterName

string

no

Redis Sentinel master name. Requires sentinelAddrs.

sentinelUsername

string

no

ACL user used to authenticate to the Sentinels themselves (sentinel mode only). Separate from username, which is the Redis data user.

sentinelPasswordEnv

string

no

Environment variable holding the Sentinel password (sentinel mode only). Never put the password in this file.

tls

boolean

no

Use TLS in sentinel mode (Sentinels and the discovered master). In URL mode use a rediss:// URL instead.

tlsCaFile

string

no

PEM CA bundle for the Sentinel TLS connections. Requires tls=true; empty = system roots.

tlsServerName

string

no

TLS server name override (useful when the Sentinels are addressed by IP). Requires tls=true.

username

string

no

Redis ACL username.

passwordEnv

string

no

Environment variable holding the Redis password. Never put the password in this file.

db

integer

no

Redis logical database. Default 0. Minimum: 0.

prefix

string

no

Shared revocation key prefix. Default cladone:auth:v1:. Must match the embedded IAM’s redis.authPrefix.

dialTimeoutMs

integer

no

Redis dial timeout in milliseconds. Default 500. Minimum: 0.

readTimeoutMs

integer

no

Redis read timeout in milliseconds. Default 300. Minimum: 0.

writeTimeoutMs

integer

no

Redis write timeout in milliseconds. Default 300. Minimum: 0.

poolSize

integer

no

Redis connection pool size. Default 64. Minimum: 0.

users

array of object

no

Development users exposed by the embedded login form. Loopback only.

sessionTtlSeconds

integer

no

Session lifetime. Default 43200 (12h). Minimum: 1.

services

object

no

A link rendered in the expanded user badge. URL: http(s) absolute or a local absolute path (/…​); javascript:/data: are refused. target defaults to _blank; rel is forced to noopener noreferrer.

roles

array of string

no

Required Keycloak roles (realm roles + flattened client roles, see auth-bridge’s X-Roles). AND between them. Example of a fixed name: offline_access (realm role granted to every user via default-roles-<realm>).

scopes

array of string

no

Required granted scopes (token scope claim, see auth-bridge’s X-Scopes). AND between them. Example of a fixed name: profile (default client scope, always present).

claims

map of string to string or array of string

no

Token claims: key = claim name, value = one accepted string or a list of accepted strings (OR / anyOf on the same claim). "*" = the claim is present. All keys combine with AND. A token claim that is itself a list (groups, roles…) matches when one of its elements matches. Example: {"email": ["alice@example.com", "a.rolland@example.com"], "email_verified": "true"}.

user

string

no

Exact username required (preferred_username).

service

string

yes

mcp.name of the referenced service.

path

string

yes

Path relative to the set endpoint ("/" = the set endpoint itself).

tools

array of string

no

Optional glob allow-list restricting the service’s tools inside this set.

enabled

boolean

no

Expose this member (default true). false = not materialized, and its service is neither compiled (no OpenAPI fetch) nor provider-validated.

appearance

string (one of: always, execute, interaction-only)

no

Turnstile render appearance of the challenge widget. Default interaction-only in gate/both: the widget stays hidden unless Cloudflare requires an interaction. always shows it; execute renders without running the challenge until executed.

shareBytes

integer

yes

Maximum size of this type’s WAL on this node. Minimum: 1.

fsync

string (one of: none, window_ms, always)

no

Durability: none, group commit every windowMs, or fsync before the response (zero_loss). always is refused for request/error (the proxy emitter cannot fsync before a streaming response).

windowMs

integer

no

Group-commit interval for fsync=window_ms. Default 100. Minimum: 1.

segmentBytes

integer

no

Append-file rotation size. 0 = share/4 capped at 8 MiB. Minimum: 0.

hosts

array of string

no

Request hosts or glob patterns to capture. Empty = all hosts.

routes

array of string

no

Request path patterns to capture. Empty = all paths.

methods

array of string

no

HTTP methods to capture. Empty = all methods.

types

array of string

no

Event types to attach attrs to. Default: [billing].

query

array of string

no

Allow-listed query parameter names whose values are copied as q.<name>. Sensitive names are skipped.

body

object

no

Optional JSON-body extraction.

maxAttrsBytes

integer

no

Total attrs budget in bytes. Default 1024, clamped to 2048. Minimum: 0. Maximum: 2048.

unit

string

yes

Free-form unit label (request, token, byte, second, …​). Minimum length: 1.

scale

integer (one of: 0, 3, 6)

yes

Decimal scale of the quantity: 0 (units), 3 (milli) or 6 (micro).

maxDimensions

integer

no

Maximum number of dimensions accepted per measure; must not exceed the declared dimensions. Minimum: 0.

dimensions

map of object

no

Declared dimension names and their types; an undeclared dimension is rejected.

measurement

string (one of: event, periodic)

no

event (discrete fact) or periodic (continuous quantity emitted by heartbeat, e.g. time, bytes, storage). Default event.

heartbeatSeconds

integer

no

Heartbeat period of a periodic metric. Default 60. Minimum: 10. Maximum: 3600.

pricing

string (one of: declarative, plugin)

no

declarative (core rate table) or plugin (signed pricing plugin). Default declarative.

fallback

string

no

Declarative tariff version used when pricing=plugin is unavailable. Required with pricing=plugin.

metric

string

yes

Minimum length: 1.

version

string

yes

Minimum length: 1.

currency

string

yes

Minimum length: 3. Maximum length: 3.

effectiveFrom

string

yes

—

charges

array of object

yes

—

dir

string

no

Outbox directory. Default ./usage-outbox, resolved from the configuration file.

maxAge

string

no

Maximum age of the oldest pending record (duration, e.g. 6h). Default 6h.

maxBytes

integer

no

Maximum pending bytes. Default 512 MiB. Minimum: 0.

maxRecords

integer

no

Maximum pending records. Default 50000. Minimum: 0.

onFull

string (one of: block, drop)

no

block (default): new billable requests answer 503 when the buffer is full. drop: discard (counted, logged) — never silent but loses revenue.

url

string

no

Managed ingest endpoint (http/https). Empty = export only.

secretEnv

string

no

Environment variable holding the Bearer secret sent with every push.

signingKeyEnv

string

no

Environment variable holding the base64url 32-byte Ed25519 seed that signs each batch and each export bundle. Required when metrics are configured.

batchRecords

integer

no

Maximum records per batch. Default 500. Minimum: 1.

batchBytes

integer

no

Maximum batch size in bytes. Default 1 MiB. Minimum: 1.

batchWaitMs

integer

no

Maximum wait before flushing a partial batch. Default 1000 ms. Minimum: 1.

exportDir

string

no

Directory receiving signed export bundles (bundle .jsonl, .sig and manifest). Required for the airgap profile.

exportAfterSeconds

integer

no

How long the push may fail before an export bundle is written. Default 300 s. Minimum: 0.

receiptPublicKey

string

no

Base64 Ed25519 public key of the ingest service, verifies the signed receipts that acknowledge an air-gap bundle (gate-one billing ack). Required for the airgap profile.

name

string

yes

Unique plugin name (assertion audience). Minimum length: 1.

url

string

yes

Absolute http(s) base URL. /health and /events are appended.

manifest

string

no

Path of the signed plugin manifest. When set, the manifest is authoritative for the event subscription and the licence feature; artifact is required and usage.trustStore must be configured.

artifact

string

no

Path of the signed plugin artefact (binary/container). Required with manifest; its digest is verified against the manifest.

types

array of string (one of: request, auth, error, billing, audit)

no

Subscribed event types when no signed manifest is used; each must be configured in usage.types.

filters

object

no

Narrow the subscription by host, route, tenant, method, status class or sample rate. Route patterns match the path only, so use hosts to avoid matching the same path on every host.

maxLagBytes

integer

no

Allowed subscriber lag. Beyond it, onMaxLag applies. Minimum: 0.

onMaxLag

string (one of: block, drop)

no

block (default): 503 until catch-up; drop: move the cursor to the lag limit and let eviction proceed.

licenseFeature

string

no

Required signed-licence feature; the plugin is refused without it.

host

boolean

no

true = the Host header sent to the backend is that of the backend’s origin (required for an external site that routes by Host, e.g. Cloudflare — otherwise the request arrives with the public host and the origin does not recognize it). Absent/false = public Host passed as-is (internal backends). TLS/SNI always targets the backend’s origin.

hostOverride

string

no

Explicit value of the Host header sent to the backend, when it must differ from both the public host and the backend’s origin (rare). Precedence over host.

headers

map of string to string

no

Static request headers set toward the backend (Set: overwrite any value the client may have sent). Uses: get through an origin basic auth ("Authorization": "Basic ${MYSITE_BASIC_AUTH}") or the Cloudflare Access service tokens (CF-Access-Client-Id / CF-Access-Client-Secret). Values with ${VAR} interpolation from the container environment — missing variable = fatal error at load (never a silent empty credential); empty value = header removed from the request. Values are never logged.

rewriteRedirects

boolean

no

true = ABSOLUTE Locations targeting the backend’s origin are rewritten to the public host (https scheme, path/query preserved) — otherwise the browser would leave the proxy at the target site’s first absolute redirect (e.g. 301 of the trailing slash). Relative Locations and those targeting other origins (e.g. a Cloudflare Access team domain) pass intact. Default: false.

responseHeaders

object

no

Adjustment of the backend’s RESPONSE headers before sending to the browser — typically remove an origin Content-Security-Policy that would block the injected guard script, or set a deployment header. Prefer csp.merge (hashes) or csp.own (explicit removal, logged) for CSP: removing the origin’s CSP here is a blunt, unlogged operation and loses the origin’s protections.

rewriteBody

object

no

Rewriting of the HTML body (200 text/html only, STREAMING — O(1) memory): the origin’s absolute URLs cited in the pages ("https://origin/…", "http://origin/…", "//origin/…") are rewritten to the route’s public host, so the browser stays in the proxy. Any explicit port is part of the rewritten prefix and is lost (target served on the standard port). The path, query and fragment follow as-is. Routes expanded from one wildcard automatically rewrite sibling editions toward their public hosts. targets and followRoutes add explicit cross-route mappings (bare hosts only: the request’s scheme and port are inherited). At runtime (fetch/XHR/sendBeacon launched by the site), the client SW served on /__gate-one_pwa/sw.js applies the same policy — it is auto-registered by the guard script, served pre-authentication. One same policy (origins × exceptions × targets) is implemented three times (Go engine, client SW, script patch) — parity tested. Default: absent (no body rewriting).

rewriteCookies

object

no

Translation of the Set-Cookie set by the origin: a Domain attribute targeting its own namespace ("Domain=original…domain.dev") would be rejected by the browser from the public host — the cookie would be silently lost. Active: a Domain targeting the origin host (equal or parent) is rewritten to the public host in "rewrite" mode (the sharing scope — host + subdomains — is transposed as-is), or the attribute is removed in "strip" mode (host-only on the public host). Other cookies pass intact (surgery of the Domain attribute only: Path/Secure/HttpOnly/SameSite/Expires come out byte-exact). Auth protection: an origin Set-Cookie bearing a name reserved for the gateway session (access_token, refresh_token, id_token, session) is removed with a warning — set on the same public host, it would overwrite the session cookies. Default: absent (no cookie rewriting).

stripCookies

string (one of: all, none)

no

REQUEST-side cookie filtering toward the backend. The gateway session cookies (access_token, refresh_token, id_token, session) carry Domain=<parent domain> (COOKIE_DOMAIN, e.g. .cladone.com): the browser presents them to EVERY public host, so without this filter a proxified third-party site receives the user’s tokens on every request. "all" = every cookie removed except the names in keep (the proxified app’s own cookies); "none" = historical behavior, everything forwarded. Default: "all" as soon as an upstream policy is declared (fail-closed).

keep

array of string

no

Cookie names preserved when stripCookies is "all" (typically the proxified application’s own session). Names reserved for the gateway session (access_token, refresh_token, id_token, session) are refused at load: they must never reach an external origin.

browserCache

object

no

HTTP-cache orientation to the BROWSER for assets the origin serves with no Cache-Control (and no Last-Modified either: without these two headers the browser has no heuristic cache — every re-view re-fetches or revalidates each asset, one full round-trip each). Only 200 responses of content-type image/*, Cache-Control absent only: the origin’s own declarations pass untouched. Sent as "private, max-age=…" — private: resources under authentication stay out of any shared cache; the origin’s ETag remains for revalidation after expiry. Default: absent (headers preserved as-is).

tokenBroker

object

no

Per-user credentials supplied by the token broker for the authenticated caller. Requires the top-level tokenBroker block and route.auth (the broker needs an authenticated user id). A missing connection produces a 401/403/409 with a connect_url (403 when the user paused the delegation, 409 when reauthorization is required), or a redirect for frontend routes, never a request without credentials. The same policy applies to REST tool calls produced by an MCP route.

provider

string

no

ID of the authProviders entry used to verify this route. Empty = defaultAuthProvider. The binding is static and compiled at load; a request cannot choose another provider.

when

object or array of object

no

Technical conditions deciding WHEN authentication is required. Empty = always. One object = AND; an array = OR of ANDs.

identity

object

no

Identity policy conditions, evaluated AFTER authentication on the verified token (failure = 403 forbidden). All conditions combine with AND.

requests

integer

yes

Maximum number of requests in the period.

period

string

yes

Rate-limit period: second, minute, hour or day.

when

object

no

Rate-limit / quota triggering conditions (rateLimit.when, quota.when). Two families: technical (method/query/header/body — evaluated BEFORE authentication) and identity (roles/scopes/claims/user — evaluated AFTER authentication on the verified token). All conditions combine with AND. NB: the authentication policy (auth) does NOT use this type: auth.when takes technical conditions only, auth.identity takes identity conditions only.

limit

integer

yes

Maximum billable units in the period.

period

string

yes

Quota period: second, minute, hour or day.

when

object

no

Rate-limit / quota triggering conditions (rateLimit.when, quota.when). Two families: technical (method/query/header/body — evaluated BEFORE authentication) and identity (roles/scopes/claims/user — evaluated AFTER authentication on the verified token). All conditions combine with AND. NB: the authentication policy (auth) does NOT use this type: auth.when takes technical conditions only, auth.identity takes identity conditions only.

url

string

yes

OpenAPI 3.x JSON document of the host (absolute URL, or path relative to the route backend). Also the document used to resolve the mcp policy’s operations.

public

boolean

no

false = the openapi.json is only served authenticated.

enabled

boolean

yes

Enable the MCP service on this route.

path

string

no

Default: /mcp.

name

string

no

Service name, referenced by mcpSets members. Empty = the route cannot be a set member.

standalone

boolean

no

Expose this service on its own endpoint (default true). false = served only through the mcpSets referencing it (the set carries the access rights).

resource

string

no

OAuth protected-resource identifier (audience) of the standalone service. Empty = the endpoint URL. Ignored when the service is reached through a set.

scope

string

no

Keycloak client scope required from MCP clients (bearer scope claim), announced in /.well-known/oauth-protected-resource and checked by auth-bridge (internal X-MCP-Scope header). The realm must grant it. Default: mcp-tools.

operations

array of object

no

REST operations exposed as MCP tools. Empty = no tool (the MCP endpoint still serves metadata and initialization). Mutually exclusive with upstream.

upstream

object

no

Proxy an external MCP server over Streamable HTTP instead of deriving local REST tools. The upstream receives the per-user token of upstream.tokenBroker (or static upstream.headers), never the Gate One bearer. Tool filtering is enforced on both tools/list and tools/call.

enabled

boolean

yes

Enable the PWA shell on this route.

name

string

no

Application name shown in the PWA manifest.

shortName

string

no

Short application name for the home screen.

themeColor

string

no

Theme color for the PWA manifest and browser UI.

icon

string

no

Legacy singular (still read).

icons

array of string

no

Same-host paths referenced by the manifest (Chrome: 192×192 and 512×512 PNG for full install).

apiCache

object

no

One service-worker API cache policy (path prefix, method, retention).

apiCaches

array of object

no

API cache policies for the service worker.

apiGETCache

object

no

Its presence activates the universal GET cache (everything nothing else covers).

networkOnly

object

no

Its presence activates the "never cached" route. When a PWA route shares the authentication scope, the identity-provider endpoints (discovery, authorize, token, JWKS, end-session) and the RP callback carrying a one-time code/state MUST be excluded, or the service worker can replay a stale identity or a one-time code.

assets

object

no

Strategy of same-origin pages/assets (documents, scripts, styles). Default: staleWhileRevalidate without timeout.

mode

string (one of: off, merge, hash, nonce)

yes

"off" = nothing (the origin’s policy passes as-is); "merge" = keep the origin policy and only add the hashes of the gateway’s injected scripts (no policy of our own); "hash" = emit our policy with those hashes, no body rewrite; "nonce" = emit our policy with a per-response nonce and stamp the HTML in STREAMING mode (O(1) memory, upstream forced to gzip so the body is plain text).

reportOnly

boolean

no

Emit Content-Security-Policy-Report-Only instead of the enforcing header (progressive rollout: violations are collected, nothing is blocked). Requires mode nonce or hash.

own

boolean

no

The gateway OWNS the policy: the origin’s enforced and report-only CSP headers are removed before ours is emitted. Opt-in and logged (never silent). Requires mode nonce or hash and reportOnly=false: removing the origin’s enforcing policy to replace it with a report-only one would remove protection without enforcing anything. Use only for a site you control/accept, with a complete policy.

reportTo

string

no

Local path served by the gateway collecting the violations (report-uri). Default: /__gate-one_csp/report. Bounded ring buffer (256 entries), 16 KiB body limit, 50 reports/second, never authenticated. Pattern: /[\s?#]*$.

stampScripts

string (one of: inline, all)

no

"inline" (default) = only <script> tags WITHOUT src receive the nonce (external scripts stay governed by the host allow-list); "all" = every <script> tag. Nonce mode only. A tag that already carries a nonce is never rewritten.

directives

map of string to string or array of string

no

Directive name → sources, as one string ("'self' https://x") or an array. The gateway appends the nonce (nonce mode) and the injected scripts' / guard stylesheet’s hashes to the effective script-src / style-src, and report-uri when reportTo is set. To let the guard’s nonce/hash pass, declare style-src (e.g. "'self'").

position

string (one of: left, right)

no

Top edge (default right).

claims

boolean or array of string

no

What the expanded badge displays as claims: true = every claim of the session, false = none, a list = only these (missing ones omitted).

roles

boolean or array of string

no

Session roles displayed as chips in the expanded badge: true = every role, false = none, a list = only these (same data as the auth.identity.roles conditions, served by the /__gate-one/auth probe).

scopes

boolean or array of string

no

Granted scopes displayed as chips in the expanded badge: true = every scope, false = none, a list = only these.

logoutLabel

string

no

Label of the logout button (default Log out).

links

array of object

no

Application-specific links, appended after the connector links (account, then services when the deployment delegates). Duplicate URLs are dropped (the connector link wins); at most 8 links after merge.

loginBadge

boolean

no

true = the badge ALSO appears when anonymous, from the very first visit, in invitation mode ("👤 Sign in") — clicked, it opens the login tab: offer sign-in without touching the site’s markup. Default false (badge only once authenticated; when anonymous it only appears after a detected session death).

selector

string

yes

CSS selector (querySelectorAll) of the targeted elements.

roles

array of string

no

Visible if AT LEAST ONE of these roles is held.

scopes

array of string

no

Visible if AT LEAST ONE of these scopes is granted.

claims

map of string to string or array of string

no

All keys must match; each value is one accepted string or a list (OR / anyOf); "*" = presence. A token claim that is itself a list matches when one element matches. Example: {"email": ["alice@example.com", "a.rolland@example.com"]}.

auth

string (one of: after, before)

no

Turns the selected elements into login triggers: after = native action preserved + invitation tab; before = click neutralized + direct tab. Activation only: deactivations (unchecking, closing details, reset, returning a value control to its OFF value) are never gated. Value controls (select/range/date/…) are gated on change, with their default value as the OFF value (data-gtw-auth-off on the element overrides it).

hidden

string (one of: before, after)

no

Hiding: before = hidden before authentication (any click reaching it is neutralized → banner); after = hidden once authenticated.

enabled

boolean

no

false = opt-out (the front handles its own 401).

loginUrl

string

no

Default: https://login.cladone.com/login (auth-bridge page).

forbidden

object

no

Opt-in UX for the gateway’s OWN identity 403 (rights refusal — auth.identity not satisfied). A backend 403 is never concerned. Browser navigations get a readable HTML page (or a redirect to pageUrl); fetch()/XHR get the JSON 403 unchanged, plus an optional dismissable banner hinting the front authors to hide the feature.

type

string (one of: bolt, redis)

no

bolt (default, single instance) or redis (shared, multi-instance, immediate revocation).

path

string

no

bbolt file path. Default ./gate-one-state.db (relative to the config file).

url

string

no

Redis URL for type redis (redis:// or rediss://). Mutually exclusive with sentinel mode.

sentinelAddrs

array of string

no

Redis Sentinel addresses (host:port). Required with masterName.

masterName

string

no

Redis Sentinel master name. Requires sentinelAddrs.

sentinelUsername

string

no

ACL user used to authenticate to the Sentinels themselves (sentinel mode only). Separate from username, which is the Redis data user.

sentinelPasswordEnv

string

no

Environment variable holding the Sentinel password (sentinel mode only). Never put the password in this file.

tls

boolean

no

Use TLS in sentinel mode (Sentinels and the discovered master). In URL mode use a rediss:// URL instead.

tlsCaFile

string

no

PEM CA bundle for the Sentinel TLS connections. Requires tls=true; empty = system roots.

tlsServerName

string

no

TLS server name override (useful when the Sentinels are addressed by IP). Requires tls=true.

username

string

no

Redis ACL username.

passwordEnv

string

no

Environment variable holding the Redis password. Never put the password in this file.

db

integer

no

Redis logical database. Default 0. Minimum: 0.

prefix

string

no

Shared revocation key prefix. Default cladone:auth:v1:. Must match the embedded IAM’s redis.authPrefix.

dialTimeoutMs

integer

no

Redis dial timeout in milliseconds. Default 500. Minimum: 0.

readTimeoutMs

integer

no

Redis read timeout in milliseconds. Default 300. Minimum: 0.

writeTimeoutMs

integer

no

Redis write timeout in milliseconds. Default 300. Minimum: 0.

poolSize

integer

no

Redis connection pool size. Default 64. Minimum: 0.

id

string

yes

Provider id used by routes (auth.provider). Must be globally unique. Minimum length: 1.

loginBaseUrl

string

yes

Public origin of this domain’s login service. Must be the cookieDomain or one of its subdomains.

loginUrl

string

no

Optional full login page URL. Defaults to loginBaseUrl + /login.

cookieDomain

string

yes

Registrable parent domain for this provider’s session cookie (e.g. app-a.com or app-b.fr). Distinct and non-overlapping within the group; route hosts must be covered by it. Minimum length: 1.

cookieName

string

no

Optional session cookie name. Empty = provider-scoped default.

redirectUrl

string

no

Optional OIDC callback URL. Defaults to loginBaseUrl + /auth/callback. Must be on cookieDomain or a subdomain.

links

object

no

Links owned by the authentication connector, displayed in the user badge. account is the IdP’s own account console: NO OIDC standard, so the URL is explicit (Keycloak /realms/<realm>/account/, Entra myaccount.microsoft.com, Google myaccount.google.com, Okta /enduser/settings…).

mcpAudience

string

no

MCP access-token audience policy. Empty = scope-only (compatible default). A literal value requires that value in aud. "auto" requires the endpoint’s own protected-resource identifier (recommended, and used with Keycloak audience mappers).

defaultAppUrl

string

no

Application to send a bare visit to this provider’s login host root to. Must be a route host of this provider (or a host covered by its cookieDomain). Overrides the group/global fallback for this domain. Prefer a neutral page rather than one application.