Skip to content
SHC Docs

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

Some apps will never have OIDC on a licence SHC can use. The estate has three answers today and all three are unsatisfying:

  1. Fork it: what apps/openreplay now 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.
  2. 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.
  3. 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:

tierthe app…what to dofeature needed
1has a disable-auth knobturn it off, put the gate in frontNONE
2has no disable-auth knob, but validates a static credential per requestinject the headergate_headers
3needs a client-held session tokenfork 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.

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.

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:

appmechanisminjectable
openobserve (AGPL build)HTTP Basic, every request (validator.rs:986)yes, proven
openhandsSESSION_API_KEY, one shared bearer (server/dependencies.py:6-23)yes, same shape
shlinkstatic X-Api-Key on /rest/yes, for the API
openreplayJWT the client attaches from localStorage, bound to a DB row within a 1-second jwt_iat windowno: this is why it needed a fork
uptime-kumasocket.io session from a login eventno

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):

requestresult
/web/ through the injecting edge200
/api/organizations through the edge, no client credentials200, 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.

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.

A new app.yaml property, sibling to sso_redirect and ungated_paths:

access: gated
gate_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_headers appears without access: 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.

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, hooks
phase 2 (rendered): sso_redirect.*, gate_headers, against
resolved vars + routing helpers

Guard 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.

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.

  • 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.
  1. Option A or B for secret resolution.
  2. Whether gate_headers should be refused outright on any app whose access is not gated, or merely warned. (Recommendation: refused.)
  3. Whether this feature is permitted on tenant-facing apps at all. (Recommendation: no, enforced by an arch-fitness check.)

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.