Gate header injection: SSO for apps that will never have SSO
Status: proposed. Not implemented. Needs an owner ruling and a ce change. Date: 2026-08-06
Problem
Section titled “Problem”Some apps will never have OIDC on a licence SHC can use. The estate has three answers today and all three are unsatisfying:
- Fork it: what
apps/openreplaynow does. Correct when the app’s user model is worth keeping, but it is a permanent commitment to one file in someone else’s release train. - Gate it and live with two credentials: Keycloak at the door, then the app’s own login. Works, but the operator types a password into a tool they already authenticated for.
- Buy the enterprise edition, often disqualified on licence grounds anyway (see the resale audit).
There is a fourth answer that costs nothing and is already proven on one app: have the gate present the app’s own credential on the operator’s behalf.
★ FIRST: check whether the app can simply turn its own auth OFF
Section titled “★ FIRST: check whether the app can simply turn its own auth OFF”Added after owner review, which correctly pointed out that most of this document was solving a problem the estate already solves.
The question is not “does the app accept a static credential”. It is:
| tier | the app… | what to do | feature needed |
|---|---|---|---|
| 1 | has a disable-auth knob | turn it off, put the gate in front | NONE |
| 2 | has no disable-auth knob, but validates a static credential per request | inject the header | gate_headers |
| 3 | needs a client-held session token | fork it | (openreplay) |
Tier 1 is already the estate’s pattern and needs nothing built.
apps/standalone/pmm/compose.yaml literally says “AUTH OFF, GATE IN FRONT”,
rendering GF_AUTH_ANONYMOUS_ENABLED=true + GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
behind vars.auth.disable. Windmill’s NO_AUTH is the same pattern. openhands
is already auth-off and gated in its SHC packaging.
So this feature is justified by tier 2 alone, and only one app has been
proven into tier 2: openobserve: no no_auth/disable_auth/skip_auth/
anonymous knob exists anywhere in its config.rs, yet its validator accepts
Basic on every request. mailpit, shlink and docuseal’s REST surface are
candidates but unproven.
Before building anything, someone should confirm the tier-2 population is larger than one. If it is not, the cheaper answer is a documented recipe for the single app rather than a platform feature, and the family-B material below becomes a record of what was measured, not a plan.
What that does to the family-B findings
Section titled “What that does to the family-B findings”sonarqube already ships a working saml.plug.yaml with real per-user identity;
header auth there swaps one working mechanism for another and adds a
forgeable-header hazard. Not worth doing.
pmm’s auth-proxy result is real but buys attribution only: named users instead of anonymous, at identical privilege, on an internal monitoring dashboard. Weigh that against the measured trap that mixing it with Basic silently collapses every user into one shared admin.
The criterion
Section titled “The criterion”Header injection works iff the app validates a static, stateless credential on every request. It fails iff the app requires a session established by a login flow whose token the client must hold.
That one line separates every case measured this session:
| app | mechanism | injectable |
|---|---|---|
| openobserve (AGPL build) | HTTP Basic, every request (validator.rs:986) | yes, proven |
| openhands | SESSION_API_KEY, one shared bearer (server/dependencies.py:6-23) | yes, same shape |
| shlink | static X-Api-Key on /rest/ | yes, for the API |
| openreplay | JWT the client attaches from localStorage, bound to a DB row within a 1-second jwt_iat window | no: this is why it needed a fork |
| uptime-kuma | socket.io session from a login event | no |
Evidence (openobserve, measured 2026-08-06)
Section titled “Evidence (openobserve, measured 2026-08-06)”Community image public.ecr.aws/zinclabs/openobserve:v0.91.5 behind an nginx
edge injecting Authorization: Basic base64(ZO_ROOT_USER_EMAIL:ZO_ROOT_USER_PASSWORD):
| request | result |
|---|---|
/web/ through the injecting edge | 200 |
/api/organizations through the edge, no client credentials | 200, real payload |
| same API direct, no injection (control) | 401 |
The SPA does not defeat it. Its redirect to /login fires on an API 403
(…status===403 && l(), where l() dispatches logout and pushes /login), not
on absent local state; with injection that call returns 200, so the logout path
never runs. The localStorage.getItem("creds") && push("/logs") line is the
inverse: it bounces an already-credentialed user away from the login page.
Not yet verified in a real browser (no Chrome on the debug port here). The API half and the redirect-trigger logic are proven; “the UI renders fully” is strong inference.
★ There are two families, and the second one is the prize
Section titled “★ There are two families, and the second one is the prize”The above is family A: shared-credential injection: everyone through the gate becomes one app account. There is a strictly better family.
Family B: trusted-header identity mapping. The app natively supports “the reverse proxy already authenticated this person; their username is in header X” and maps it to a real, per-user account, auto-provisioning on first sight. Genuine multi-user identity, real attribution, real RBAC; no SSO licence, no fork, no shared account. Two are confirmed by measurement, not documentation:
sonarqube 26.7.0-community: full family B, NOT edition-gated
Section titled “sonarqube 26.7.0-community: full family B, NOT edition-gated”sonar.web.sso.enable plus loginHeader / nameHeader / emailHeader /
groupsHeader. The property block is in the pinned image’s own
/opt/sonarqube/conf/sonar.properties, and the documentation is the Community
Build doc set; this is not a paid feature.
Measured live against the pinned image: GET /api/users/current → 401 bare,
→ 200 with X-Forwarded-Login: alice, auto-provisioning a real account with
name and email. A second header set produced a second distinct account, and
X-Forwarded-Groups: sonar-administrators gave that account real global
admin (/api/users/search → 200).
Caveat: sonarqube already ships a working saml.plug.yaml, so this is a
simplification, not new coverage.
pmm 3.7.0: partial family B, with a measured boundary
Section titled “pmm 3.7.0: partial family B, with a measured boundary”Percona does not lock down Grafana’s auth proxy. GF_AUTH_PROXY_ENABLED +
GF_AUTH_PROXY_HEADER_NAME=X-WEBAUTH-USER reaches Grafana through supervisord
and survives PMM’s own nginx, which fronts every location with auth_request.
Measured: /graph/api/user 401 bare → 200 with the header; alice id=2,
bob id=3, both authLabels: ["Auth Proxy"].
Boundary, measured not assumed: pmm-managed’s /v1 control plane cannot be
reached by header identity at all. grep -a of /usr/sbin/pmm-managed finds
Authorization (240 hits), Cookie (125), /api/user (370) and zero
X-WEBAUTH-*. It stays 401 with the header even at org Admin, and the auth proxy
mints no session cookie to bridge with.
Still a clear improvement: the package today documents auth.disable, i.e.
anonymous org-Admin. Auth-proxy has the identical /v1 gap but gives named
users and real Grafana RBAC.
★ Anti-pattern: A and B cannot be layered
Section titled “★ Anti-pattern: A and B cannot be layered”The obvious fix for PMM’s /v1 gap, inject Authorization: Basic alongside
X-WEBAUTH-USER, backfires silently. Grafana then resolves
login=admin id=1 authLabels=[]: basic auth outranks the auth proxy, collapsing
every user into the shared admin and downgrading family B to family A without
any error. Do not mix them.
The header IS the credential
Section titled “The header IS the credential”Both families make the injected header the credential, so the app must be
unreachable except through the gate. This is not theoretical:
sonarqube.socket.yaml publishes hostname and port 9000 to plugged deployments
by design, so a plugged sibling container could forge the header. Any app
enabling either family needs the same explicit warning the auth.disable vars
already carry, and it is a fair reason to prefer sonarqube’s existing SAML path
and reserve header auth for pmm, where no SSO exists at all.
Proposal
Section titled “Proposal”A new app.yaml property, sibling to sso_redirect and ungated_paths:
access: gatedgate_headers: Authorization: "Basic {{ b64(vars.rootUser ~ ':' ~ vars.rootPassword) }}"The traefik middleware attaches these headers to requests that have already passed forward-auth, and only those.
★ The footgun: interaction with ungated_paths
Section titled “★ The footgun: interaction with ungated_paths”This is the part that must not be got wrong. Four packages already declare
ungated paths: openreplay (/ingest/, /script/), shlink (/rest/),
graphiti, defectdojo. Those paths are deliberately reachable without
Keycloak.
If injection applied to an ungated path, the gate would become an auth bypass: root credentials attached to requests that never authenticated. That is strictly worse than having no feature.
Requirements:
- the ungated set must provably win over the injection set;
- the renderer must refuse (not warn) when
gate_headersappears withoutaccess: gated; - a test must assert the intersection is empty.
That last point is not paranoia. This layer has a documented habit of failing
open: a plug pin naming a service that does not exist is only a warning
(X200983PLGSVC), which is how apps/openreplay shipped with its S3 router
unattached: install green, healthchecks green, tests green, feature dead. A
config error here must fail closed and loud.
Templating: reuse the existing mechanism
Section titled “Templating: reuse the existing mechanism”gate_headers is templated, like the sso_redirect fields beside it:
gate_headers: Authorization: "Basic {{ b64(vars.rootUser ~ ':' ~ vars.rootPassword) }}"This introduces no new secret-handling. SHC resolves the template at render
time and the vault resolver handles the ref, which is exactly how every app
secret already reaches a container; apps/openreplay/compose.yaml renders
JWT_SECRET: "{{ vars.jwtSecret }}" where vars.jwtSecret is
ref+vault://jwt_secret?autogen&length=48. A credential in a middleware config
is the same mechanism as a credential in an env var; the authored file holds a
reference, never a literal.
The scope of app.yaml templating today is narrow: sso_redirect.login_path
and sso_redirect.sso_start are the only {{ }} in any app.yaml on any
branch (39 branches carry those two fields and nothing else templated;
ungated_paths are literal strings). Those two currently need only routing
helpers (path(), url()), so whether the render context for these properties
already exposes vars is an implementation detail to confirm rather than assume.
If it does not, widening it is the change, not a new resolution mechanism.
The same argument extends the other way: anything the gate needs to know about an app’s login surface is a candidate for the same treatment: an explicit redirect URL, or a selector identifying the app’s own SSO control. These are all “values the middleware resolves from the package”, and they belong in one templated block rather than accreting as special cases.
No cycle, because app.yaml is read in two phases
Section titled “No cycle, because app.yaml is read in two phases”app.yaml is an input to the templating engine, so it is worth stating why this
does not become self-referential.
The vars: block in app.yaml holds declarations: names, types,
descriptions, not values. Values live in vars.yaml. So the var context can be
built without rendering anything in app.yaml, and the templated properties are
consumed downstream, by the ingress/middleware renderer, rather than being
needed to construct the context they render against.
That ordering is not hypothetical; the existing feature requires it. apps/kutt’s
sso_start: "{{ url('kutt') }}/login/oidc" resolves the deployment’s HOST, which
does not exist until the deployment does, and per the comment there, the renderer
“keeps only the PATH and re-attaches EACH ROUTE’S OWN host”, i.e. it renders
per-route, late. sso_redirect is therefore already a phase-2 property. Adding
vars.* to that context moves nothing earlier.
phase 1 (structural): vars declarations, access, exposure, ungated_paths, hooksphase 2 (rendered): sso_redirect.*, gate_headers, against resolved vars + routing helpersGuard for the degenerate case: the phase-2 properties must be excluded from
whatever feeds the engine. If app.yaml is ever passed to the renderer whole, a
templated property could reference the block it lives in. Strip the phase-2 keys
from the render input rather than relying on authors not to do it.
What this is not
Section titled “What this is not”A shared-identity feature. Everyone through the gate becomes the same app user.
- Right for operator-internal tools. openobserve’s community build has no RBAC at all, so nothing is lost that exists, and the estate’s openobserve instances are operator-only (owner confirmation, 2026-08-06).
- Wrong for anything tenant-facing, and for anything where attribution matters. The property name and docs should say so plainly so it is not reached for casually.
For openhands specifically: injection removes the credential prompt but does not fix that app’s real problem: one identity, one shared secrets store, and a read-write host docker socket. Do not let this feature make that look solved.
Alternatives considered
Section titled “Alternatives considered”- Fork each app to add OIDC, correct where the user model is worth keeping (openreplay), disproportionate for a single-user internal tool.
- Buy enterprise; for openobserve the EULA restricts use to “internal business operations” and forbids providing the software to third parties; no paid tier buys that out. Fine while operator-internal, but it is not a route to a tenant-facing deployment.
- Accept two logins: status quo. Works; the operator pays for it daily.
Owner decisions required
Section titled “Owner decisions required”- Option A or B for secret resolution.
- Whether
gate_headersshould be refused outright on any app whoseaccessis notgated, or merely warned. (Recommendation: refused.) - Whether this feature is permitted on tenant-facing apps at all. (Recommendation: no, enforced by an arch-fitness check.)
Not started because
Section titled “Not started because”The traefik/SSO middleware surface is under active change in several concurrent
lanes: oidc-socket-rename, oidc-socket-sweep, fix/oidc-public-clients,
sso-native-knobs. This should land after that campaign settles, or be folded
into it deliberately.