Skip to content
SHC Docs

Access control

Layer 10. Edge. Edge

SHC enforces tenant isolation and per-stack permissions through a single Keycloak instance, one realm per tenant, and a role grammar evaluated at the ingress edge plus the API. This page is the authorization boundary: who may call what. The network boundary is a separate mechanism with its own documented limit on fabric estates: see Security §4.

PieceRole
System KeycloakSingle Keycloak deployment in the system tenant; the IdP for the entire SHC instance. Has no default main realm; realms are per-tenant.
Tenant realmOne realm per SHC tenant, named after the tenant (e.g. acme). Users belong to exactly one realm.
shc-access clientA bearer-only client provisioned in every realm. Holds the tenant:* and stack:* roles that drive permission decisions.
forward-authA service of the system Traefik deployment. Traefik calls it for every request to a gated host; it answers allow/deny from its node’s auth clusterfs section (the host→stack mapping, revocations, declared platform admins) and the user’s roles, and calls shcd for no verdict. See Primitives.
Access axisPer-deployment: access: gated (behind SHC SSO via Traefik forward-auth) or access: open (no gate; the app relies on its own auth). Set at install with the mutually-exclusive --gated / --open flags. open is the default.
Exposure axisPer-deployment and orthogonal to access: exposure: lan (the default, reachable on the LAN only) or exposure: internet. Set at install with --public, which raises exposure to internet. --public controls exposure, not access; it does not skip the SSO gate.

Access and exposure are two independent axes. Whether a deployment is gated (SSO in front) is decided by --gated/--open; whether it is reachable from the internet vs LAN-only is decided by --public. An app can be open + internet, gated + lan, or any combination.

The legacy per-app public: field in app.yaml is a read-only migration seed: on read, NormalizeDeploymentDisposition (modules/app/disposition.go) maps a set public: true → access: open and absent/false → access: gated, with exposure defaulting to lan. An already-set access/exposure always wins. There is no longer a --no-public flag; to gate an app use --gated.

External L4 load balancers are orthogonal to both axes. There is no --proxy flag and no proxy.connection config: LB attachment lives inside --expose. <port>[+udp]@<connection>[=<service>[:<container>]] rides the named proxy-capable connection’s load balancer (pfSense HAProxy / AWS NLB / GCP network LB), for any app including the system traefik itself (proxy the ingress once, --expose 80@mylb=traefik:80 --expose 443@mylb=traefik:443, and every HTTP --expose DNS record follows its VIP automatically). Per-app LB mappings remain for raw-port apps and deliberate own-LB overrides. The gate still runs at Traefik’s forward-auth regardless of which LB fronts the traffic.

interactive: drag/click to explore
  • shc tenant add acme calls provision_tenant_realm("acme"). If the system Keycloak is up, the realm + shc-access client are created via kcadm in the system Keycloak container. If Keycloak isn’t reachable yet, the call no-ops with a debug log; tenants still create cleanly, realms are reconciled when Keycloak comes online.
  • shc tenant rm acme calls deprovision_tenant_realm("acme") which drops the realm.
  • Reserved tenant names (from core/validation/reserved_names.go, case-insensitive): platform, tenant, stack, environment, use, read, operate, manage, admin, tenants, master, system, cluster, global-root, logs, metrics, traces, events, audit. Creating any of these fails the validation.TenantName check, which raises X400982NAMINV, wrapped by tenant create as X400974TNTNAM.
  • On install: _provision_stack_access_role creates the whole per-stack ladder (stack:<name> plus :use, :read, :operate, :manage and :deny (StackRoleNames → CreateAccessRoles)) on the tenant’s shc-access client. All of them, deliberately: AssignRole pre-checks that a role exists and hard-fails otherwise, so a role provisioned “lazily” is a role every grant of which fails. Always provisioned regardless of the deployment’s access axis; the role is used for admin grant tracking even when the deployment is open (no forward-auth gate at the Traefik layer). Skipped only for vdeployments (which share the role of the deployment that hosts them).
  • On uninstall: the symmetric delete_access_role runs after post_uninstall.
<scope>[:<verb>]
  • Bare scope → implicit use verb.
  • Verb hierarchy (descending): manage ⊃ operate ⊃ read ⊃ use.
  • Holding a higher verb implicitly satisfies any lower-verb check.

Scopes and what they grant:

ScopeMeaning
tenantMember of the tenant.
tenant:manageTenant admin (also operate/read/use). Also that realm’s Keycloak realm-admin, a composite, not a per-user mirror. See below.
env:<env>Membership in a specific environment.
stack:<name>Use rights on a specific stack: browser access through the SSO gate, nothing more. Identical in effect to the explicit stack:<name>:use.
stack:<name>:readThe developer / debugging role. Container logs, deployment status, and the no-ref configuration view. Grants no mutation and no resolved secret value. See Read: the developer role below.
stack:<name>:operateOperate (start/stop/restart) on a stack.
stack:<name>:manageFull lifecycle control.
stack:<name>:denyExplicit carve-out. Not a verb; any matching deny at any scope wins outright, ahead of every allow.
tenant:readThe same read tier as a blanket over every stack in the realm (R-1). stack:<name>:deny is how you punch a hole in it.
platform:manageSHC-platform admin (system realm only). Implicitly satisfies every other check on every tenant.
platform:readRead-only platform tier (system realm only): the condition snapshot and the every-tenant deployment list, nothing else. A master-realm identity holding it is not platform root. See platform:read.

Every one of those roles is created on the tenant’s shc-access client at install (StackRoleNames, modules/auth/keycloak_admin.go), because AssignRole pre-checks existence and hard-fails otherwise: an unprovisioned role is an ungrantable role.

Cross-class implication is only through platform:manage. Holding tenant:manage does not automatically grant stack:<name>:manage unless the user also has a per-stack role, but it does grant blanket access in user-facing list endpoints (see _accessible_stacks_for). Management API gates resolve the stack noun from X-SHC-Stack (the CLI and console stamp it). Without that header the noun is tenant and a stack:<name>:manage grant is inert (ce 4bb1f532).

tenant:manage is Keycloak realm administration

Section titled “tenant:manage is Keycloak realm administration”

Ruled 2026-08-23 (ce 8c7a20a9). tenant:manage used to be a client role on shc-access that Keycloak itself had never heard of. The Keycloak half was mirrored per user, at the two doors that write the SHC half. A door only reaches people who walk through it after it exists, so a holder granted earlier, or by a realm import, or by an operator in the admin console, or through a group, kept a grant the admin console could not see. Measured the same day: the estate owner on bitspur/corp held a hand-assigned realm-management/realm-admin and the console worked; the same user on promanager/corp held tenant:manage and nothing else, and https://auth.corp.promanager.vip/admin/corp/console/ answered 403.

The capability now lives on the role graph. tenant:manage is a composite whose child is that realm’s realm-management/realm-admin, asserted on every realm provision and every access-client ensure. Keycloak expands a composite at token mint and at every admin-console permission check, so the set of people who can administer a tenant’s realm is exactly the set who hold tenant:manage. Realms minted later get it from the same script that mints them.

The full realm-admin composite, not a curated subset: it is what tenant:manage already means on every other SHC surface, it is what bitspur already grants (a declared state below the live state is the one shape a converge cannot fix), and a hand-enumerated leaf list freezes against one Keycloak version.

A holder can do everything Keycloak calls administering that realm: create, disable and delete users, reset credentials, impersonate, edit clients, identity providers, roles, groups and flows, read events, and can grant themselves any role that exists there. That changes nothing on the SHC ladder: tenant:manage is already the top of that realm, and platform:manage is master-only.

They cannot leave the realm. realm-admin is scoped to the realm-management client of the realm that owns it; cross-realm administration lives on master’s <realm>-realm clients; creating realms needs create-realm there. Master is refused outright: a tenant grant must never confer administration of the identity provider itself, and master has no realm-management client to bind anyway.

Add-only and idempotent. Re-asserting a held edge is a 204. No user mapping is touched and no composite is deleted, so a hand-granted direct realm-admin becomes redundant rather than conflicting.

This is already in the ce pin (7155c9d62ea5 carries 8c7a20a9). It becomes live on an estate only after a deb roll plus a daemon restart that re-runs realm provision. Do not apply as part of landing the pin.

Ruled 2026-08-16. A developer debugging a deployment needs its logs, its metrics, its status and its configuration. They do not need to be able to stop it, and they must not be able to read the credentials it starts with.

Read access to a credential is not a weaker permission than write. Someone who can read the database password has the database, and never needed write access to the deployment to get it. A role sold as “read-only” that discloses one is a privilege escalation wearing a restricted-role label, so the useful half and the safe half are both load-bearing here: a view that masks everything passes the security review and fails the developer, which is how the role stops being used and the estate goes back to handing out :manage.

SurfaceRoute / gateWhat stack:<n>:read gets
Container logsshc.logs.get, shc.stack.logs.stream, shc.stack.logs: logs.ReadPermittedThe stream as the container wrote it, not masked (see below)
Deployment statusshc.stack.status (app module)Full status; the gate there is tenant membership, which read implies
Audit / eventsaudit:read, events:read + StacksWithPermission(VerbRead)Rows scoped to the stacks the caller can read
Configurationshc.stack.config.noref: logs.ReadPermittedThe no-ref render: ref+vault:// pointers left literal
Browser accessforward-authAllowed: read ⊃ use

And explicitly not:

  • shc.stack.start / .stop / .restart, shc.container.restart: those are :operate. An availability control is still a control.
  • shc.stack.install / .update / .uninstall / .exec / .dry_run / .config; those are :manage.
  • Any resolved secret value.

The configuration view is a different producer, not a filtered one

Section titled “The configuration view is a different producer, not a filtered one”

shc.stack.config (:manage) answers with the parsed docker compose config of the resolved deployment (every ref+vault:// already dereferenced, because that is what the container starts with) and masks it afterwards by provenance (modules/stack/config_redact.go). That is the right control for an operator entitled to those values anyway, and the wrong one for a role whose premise is that it must never reach one: its masking is a classifier over plaintext that has already been produced, and it is honest about its residue.

shc.stack.config.noref (:read) instead reuses the support bundle’s no-ref render (modules/supportbundle/render.go, NoRefRender): the deployment is re-templated from its persisted, ref-intact vars with vault-ref resolution skipped entirely, so a secret var’s value is its literal ref+vault://… pointer and no plaintext is ever produced to scrub. The resolved on-disk compose.yaml is never opened. A @secret-declared var holding an operator’s literal --var is masked by name before the template sees it.

There is deliberately one producer. Two independent secret-scrubbing paths is how one of them drifts: the bundle’s masking keeps gaining rules and a private copy behind the read role would not, silently, with each green against its own fixtures. NoRefRender is exported for exactly that reason, and TestReadConfigServesTheBundlesOwnRender fails if the two byte streams ever diverge.

Logs are the real leak risk, and they aren’t masked

Section titled “Logs are the real leak risk, and they aren’t masked”

Application logs routinely carry what the config path carefully avoids. This is measured, not hypothetical: the §21.6 production log census took 28,657 real lines off the bitspur and promanager estates and found 18 live credential occurrences in 5 of 36 container streams: Keygen crypto keys under an “add these to your .env” banner, 11 JWTs in ?token= access-log URLs, a postgres DSN with its password, a server secret in a JSON "Secret" field.

shc logs doesn’t mask any of that. Every log surface in both modules (shc.logs.get, shc.stack.logs.stream, modules/stack’s own Service.Logs and the internal container and stack routes) returns what the container wrote, so a secret an app prints appears as printed. That is the owner’s ruling, not a gap: whoever can read a deployment’s logs is already authorised for them, and masking a log costs the debugging it exists for.

Masking stays where the output leaves that trust: the collector’s scrub (pkg/scrub/spec.yaml, on what reaches the log store), shc.stack.config, peer inspect and the crash report.

So stack:<n>:read is a credential-disclosure risk on the log surface in a way it is not on the config surface. Grant it to people you would let read the logs.

One implementation note that bites everyone

Section titled “One implementation note that bites everyone”

auth.RequirePermissions(svc, "stack:read") (the middleware ce’s stack module mounts) resolves its resource from reqctx.Stack, which no client populates, so it falls back to the literal noun tenant; a two-segment role scope like stack:blog:read can never match it. Per-stack roles are inert at that middleware. The gates that do honour a per-stack grant narrow at the handler, via logs.ReadPermitted → user.EffectiveVerb, which is also where the deny sweep lives. A new per-stack gate must call that function rather than re-derive the rule: a private re-check that forgot the sweep reads exactly the deployment an operator carved out.

There is no user-facing syntax for cross-tenant integration. The tenant/stack form is not recognized; attempts fall through to the normal same-tenant resolver and fail to find the stack.

Cross-tenant access exists only via the SHC-controlled “magic tokens” registered in the magicProviders allowlist in modules/app/integration_magic.go. Each magic token is an all-caps string that resolves to a specific stack in the master (system) tenant, optionally with one plug-data field overridden to the consumer tenant’s name so each tenant lands in its own logical compartment within the shared system instance. The override is per-token: it exists where the field is a security compartment (Keycloak’s realm) and is omitted where it is not (BRANDING’s brand; assets are non-secret, and the override site stamps unconditionally, which would clobber an explicit --var choice). Parsing stamps IntegrationSpec.ProviderTenantName = master for these tokens; resolveIntegrations and validateIntegrationProviders are the only places that honour a non-empty ProviderTenantName, so the tenant boundary stays closed for every other integration.

Currently registered tokens:

TokenSystem stackSocketPlug-data overridePurpose
KEYCLOAKkeycloakkeycloakrealm=<consumer_tenant>Shared IdP: every tenant gets its own realm under a single Keycloak
BRANDINGbrandingbranding(none)Shared brand-asset store: non-secret logos; the plug’s default(tenant) scopes, --var branding.brand stays honoured (an override would clobber it). Registered at init by the proprietary shc-side branding module via RegisterMagicProvider (entitlements: branding pro-and-up, white_label top tier); absent from a CE-only build

(A LICENSE token existed briefly (the 2026-08-14 marketplace ruling §5 scaffolding) and was amputated by owner ruling 2026-08-18: BYOL is a plain consumer var, cluster-side licence enforcement is shcd’s, and licence management lives on the portal Frappe backend. See docs/decisions/2026-08-18-builtin-vs-deploy-placement.md. Do not re-add the row without that doc being superseded.)

Both forms work for any registered token:

Terminal window
# Form 1: auto-match the consumer's matching plug
shc install nextcloud --integrate KEYCLOAK
# Form 2: explicit plug-name binding (required when the consumer has
# more than one plug targeting that socket type)
shc install matrix --integrate oidc=KEYCLOAK

There is deliberately no observability token. Telemetry is fabric-only: an app never wires itself to the observability store, it pushes to SHC’s own collector, which stamps scope, scrubs, filters and routes. An OPENOBSERVE token and an app-facing openobserve socket both existed and were removed; see telemetry-fabric.md.

Magic tokens cannot be qualified with @env (the provider always lives in the master tenant’s default environment); validateIntegrationProviders rejects this combination with X400903INVAPP rather than failing later as “stack not found”. There is no socket-qualified form 3; the provider socket is predetermined.

Adding another magic token: append a magicProvider{...} to the magicProviders allowlist in integration_magic.go, install the corresponding stack into the master tenant, and document it here. The resolver and validator are generic over the table: no per-token branches needed.

Not every shared service is safe as a magic token. The registered token is a control-plane service that compartmentalises cleanly on a single shared field (Keycloak by realm). A shared datastore (postgres/mysql) is deliberately not registered: its integration mints a per-consumer role + database whose names come from the consumer’s plug (gitea, nextcloud, …) with no tenant component, so two tenants installing the same app against one shared instance would collide on the same cluster-global role/database name. The provisioning job’s create-if-absent + unconditional ALTER … OWNER/ALTER USER … PASSWORD turns that collision into silent cross-tenant takeover, and either tenant’s uninstall drops the shared database. Compartmentalising a datastore needs per-tenant namespacing of both the role and the database (e.g. <tenant>_<app>), which the single-field OverrideField cannot express, so datastores stay per-tenant until that exists.

A provider socket’s data: block is rendered against the provider’s vars, so for a magic (cross-tenant) provider it holds the master instance’s real credentials (e.g. the Keycloak admin password). Those must never land in a foreign tenant’s rendered compose. On a boundary-crossing edge (ProviderTenantName set and ≠ the consumer’s tenant), resolveIntegrations blanks every socket field the socket schema marks @secret in the consumer-facing copy (ConsumerSocketData); the full SocketData is kept only for the provider-side integration jobs, which run inside the master instance and legitimately need the admin credential. Same-tenant edges keep the secrets (one trust domain). The redaction is schema-driven, so it covers every @secret field automatically:

TokenRedacted socket fields (cross-tenant only)
KEYCLOAKoidc.socket.yaml → adminPassword
BRANDING(none; the branding socket declares no @secret fields)

A cross-tenant consumer authenticates with its own scoped credential (the clientSecret / per-tenant role / etc. it supplied through its plug, provisioned by the provider-side job), never the provider’s admin secret. (Virtual sockets, *.vsocket.yaml, are never bindable cross-tenant; findSocketForPlug / inferPlugFromProvider match only *.socket.yaml, so their secrets are safe by construction.)

The limits of this, stated plainly. The redaction is a property of the edge, not of the socket contract, and it is the only thing between the app catalogue and Keycloak’s master-realm admin credential, which is a cross-realm admin (ce modules/auth/keycloak_admin.go), able to administer every other tenant’s realm. Three consequences follow, and none of them is hypothetical:

  • “Same-tenant edges keep the secrets (one trust domain)” is a weaker statement than it looks for KEYCLOAK specifically. A consumer deployed in the master tenant has ProviderTenantName == tenant, so the rule never fires and its jobs.post_deployment shell receives the real cross-realm credential. The master tenant is one trust domain with the platform, not with the estate’s other tenants.
  • Only @secret fields are covered. adminUser is typed @string!, so the username half of the credential crosses every boundary. kcadmPath is likewise unredacted, and a consumer job that shells kcadm.sh authenticates with the same credential by another door.
  • There is no per-app boundary at all. Any app declaring an sso plug may read integration.socket.data.adminPassword; what stops it is the edge geometry, not the contract.

Target design (per-consumer service accounts with narrow realm-management roles, minted at bind time, replacing the shared admin credential) plus the measured table of which edge geometries do and do not redact, and a staged migration, are in docs/decisions/2026-08-05-sso-socket-credential-scope.md. Two guards keep the surface from growing meanwhile: tests/unit/catalog/sso_admin_credential_scope_test.go here and modules/app/sso_socket_secret_boundary_test.go in ce.

Cross-environment access (within a tenant)

Section titled “Cross-environment access (within a tenant)”

Same tenant, different environment is permitted via the @env suffix on the provider in any non-magic-token integration spec. Useful when infrastructure-shaped apps (mail, s3, etc.) live in a shared environment like main or prod and other environments within the same tenant want to consume them rather than running their own copy:

Terminal window
# `dev` environment's nextcloud uses `prod` environment's mail relay
shc -e dev install nextcloud --integrate mail@prod
# Explicit plug + cross-env
shc -e dev install nextcloud --integrate smtp=mail@prod
# Socket-qualified + cross-env
shc -e dev install nextcloud --integrate smtp=mail.smtp@prod

The consumer’s own stack is created in its requested environment (-e dev); only the provider lookup runs in the override env. The tenant-isolation rule still applies; provider@otherenv only resolves within the same tenant. Cross-tenant routes still require a magic token.

A magic-token provider must never be @env-qualified, which is why keycloak is deliberately absent from the list above. Magic providers are env-less by construction (MagicProviderEnvironment; they live once at (master, <stack>, default)), so the suffix is meaningless on them. ValidateIntegrationProviders refuses -i sso=KEYCLOAK@staging for that reason. It does not currently refuse the lowercase -i sso=keycloak@staging; its check is case-sensitive on the all-caps token while ApplyMagicToken is case-insensitive on the stack spelling, so that spelling silently resolves as an ordinary same-tenant cross-env provider and loses both cross-tenant rules: the realm compartmentalisation override and the @secret redaction below. Do not use it. Tracked, with the one-line fix, in docs/decisions/2026-08-05-sso-socket-credential-scope.md §5.

  1. Browser hits nextcloud.example.com.
  2. Traefik invokes forwardAuth middleware → the forward-auth service, with X-Forwarded-Host: nextcloud.example.com and the client’s Authorization header (or the session cookie).
  3. forward-auth verifies the token against the issuing realm’s keys (the realm comes from the JWT’s iss claim, not from any tenants payload claim), then applies the revocations and the declared platform admins from its node’s auth clusterfs section. It calls shcd for no verdict.
  4. forward-auth looks up the host in the section’s realms.json → tenant + stack.
  5. Decision tree:
    • Platform admin → allow.
    • User’s tenant != stack’s tenant → 403 (cross_tenant).
    • User has stack:<name>:use (or higher) → allow.
    • Otherwise → 403 (missing_role).
  6. Allow responses set X-SHC-User, X-SHC-Tenant, X-SHC-Stack for downstream consumption.

A request with no session is redirected to Keycloak only when its Accept header carries text/html; every other caller receives a bare 401 no credentials (forward-auth/cmd/forward-auth/main.go, wantsHTML). That is the right contract for a browser and the wrong one for a machine API the app authenticates itself: the gate rejects a bearer token it has no way to evaluate, so a scanner or CI job posting to the app’s own API fails closed.

Gating is binary, so that is not met with exemptions. An app whose API clients, mobile apps or agents cannot sign in through the gate ships access: open and guards itself; a gated app sits wholly behind the gate. Exactly two carve-outs exist, each a single caller that cannot carry the gate cookie: docuseal’s signing links (/s/<token>) and paperless’s bare /accounts/login. TestOnlyTheRuledCarveOutsDeclareUngatedPaths fails the unit job when any other app declares one:

access: open
ungated_paths:
- /accounts/login

For each declared prefix the route writer emits a sibling router, <project>_ungated_<n>, matching Host(`h`) && PathPrefix(`<route path><prefix>`), pointing at the app’s own upstream service with an empty middleware chain, at priority 89000. The gated catch-all keeps its chain, so the browser UI is unaffected. The priority sits below the 90000 OIDC-callback router so a broad exemption (/api) cannot take the code-exchange leg away from the forward-auth sidecar, and below SystemKeycloakRouterPriority (100000), which only system routes (keycloak, dashboard, identified by a non-empty upstream override) take. An app route never takes that stamp, so a path-routed deployment (--expose h/paperless) is exempted the same as a host-routed one.

The declaration is read on every reconcile sweep from the deployment’s verified declaration (the stored package, else the catalogue copy), so a repackaged exemption reaches a deployment on its next shc update. A declaration that cannot be read yields no exemptions. NormalizeUngatedPaths also refuses "/", any entry not rooted at /, and any entry containing a backtick (which would close the PathPrefix(…) matcher and let the remainder be parsed as rule syntax).

This is not a hole where the exempted API carries its own authentication. It is a hole wherever it does not: the exempted prefix is reachable by anyone who can reach the host, with whatever the app does at that path. The refusals above stop an exemption from silently ungating a whole host, but nothing can verify that what is behind the prefix is authenticated; the packager is asserting that, and a review of the app is what backs it.

The API docs at /docs, and the client that was minted for them

Section titled “The API docs at /docs, and the client that was minted for them”

subsystems/impl/unix_socket.go registers GET /openapi.json, GET /docs and GET /docs/oauth2-redirect on the public router (core/api/openapi.go). /docs serves a small HTML shell that loads Swagger UI from unpkg against /openapi.json.

There is no SSO on it, and there never has been in the Go daemon. This section used to describe an Authorize button, an initOAuth call and a KeycloakOIDC security scheme. None of those exist:

  • swaggerUIHTML calls SwaggerUIBundle with url, dom_id and oauth2RedirectUrl, and never ui.initOAuth(...), so the UI has no client id to authorize with.
  • buildOpenAPISpec emits openapi / info / paths and no components.securitySchemes, so the UI renders no Authorize button and has no flow to offer.
  • The config keys that named the client and its realm (keycloak.swagger_client_id, keycloak.swagger_realm) were deleted as dead, assigned into auth.Config and read by nobody.

To call the API with a token, use shc auth login (the shc-cli device grant) or a PAT and paste the bearer, or drive the API from the CLI.

BuildProvisionRealmScript used to create a public OIDC client called shc-swagger in every realm with:

publicClient: true, standardFlowEnabled: true,
redirectUris: ["*"], webOrigins: ["*"]

That is an authorization-code exfiltration path, shipped on by default, on every realm of every estate SHC has ever provisioned, measured live in all three realms on both production estates. An authorization request naming redirect_uri=https://evil.example.com/steal rendered the login form; an operator with a live realm session who followed such a link handed their code to the attacker’s origin.

PKCE was not a defence. The client carried pkce.code.challenge.method=S256, which is probably why the shape survived review. PKCE binds a code to the verifier held by whoever crafted the request, and when the attacker crafts it, the attacker holds the verifier. The redirect allowlist is the only control that decides where a code may be delivered, and * names every origin on the internet.

The old code told operators to “tighten to specific URLs in production via the Keycloak admin console”. A shipped default whose mitigation is a manual step in a code comment is not a mitigation.

The client is no longer created at all. Not tightened to a derived callback: there was no callback to derive, because nothing has ever redeemed a code through it (see the three bullets above). A public standard-flow client has to be earned by a consumer, and this one had none. If the docs UI ever grows an OAuth login, the client gets minted then, against the daemon’s own resolved API host, with the concrete https://<api-host>/docs/oauth2-redirect URI.

Estates that already have one are disarmed, not left. The client was create-if-missing and never reconciled, so deleting the mint would have healed new estates only. auth.buildShcSwaggerDisarmFragment runs on the same provisioning path (once per realm per daemon lifetime, so it fires on the upgrade restart): where it finds a shc-swagger still carrying a wildcard it PUTs redirectUris: [], webOrigins: [], standardFlowEnabled: false. It matches on the wildcard rather than the name, so an operator who did tighten their client keeps it; and it disarms rather than deletes, because a reconcile-time DELETE keyed on a client lookup is its own hazard (X400023HKNOID).

shc-swagger stays in reservedServiceClientNames, so no service client can re-claim the name.

shc doctor no longer lists it as a required realm object; demanding it would red-light healthy estates, and doctor --fix would have re-minted the exfiltration path.

The guard is TestNoShippedScriptMintsAPublicClientWithAWildcardAllowlist (ce modules/auth/keycloak_public_client_wildcard_test.go): it EXECUTES every shipped client-minting script against a request-logging curl shim, takes the POST/PUT bodies off the wire, and fails if any body that sets publicClient: true carries a bare * in redirectUris or webOrigins.

shc-forward-auth is deliberately outside that rule. Its wildcard is architecturally load-bearing (the gate must complete a login for any gated host) and is safe only because the client is confidential. A code landing on an attacker origin is not redeemable without the secret. A flip to publicClient: true lands it back in the rule.

  • GET /api/user/apps: every stack the user can use (plus app/host metadata). Platform admins see every tenant’s stacks.
  • GET /api/user/managed-apps: stacks where the user holds at least manage (per-stack, tenant-wide, or platform-wide).

A small <script> tag is injected into the </body> of every gated app’s HTML responses. It renders a fixed-position “Apps” button (currently a stub. Clicks do nothing yet; the eventual behavior is a popup app-list backed by /api/user/apps).

Body rewrite happens in Traefik itself via the public rewritebody plugin (Yaegi-based). No extra container, no extra hop, no proxy replacement; Traefik does the rewrite in-process.

Per gated stack with the button enabled, SHC declares the middleware in the Traefik file-provider dynamic config, the same route file SHC writes for the gated router (writeIngressRouteFile), NOT docker labels: (the file provider only reads docker labels on Traefik’s own node, so a per-project label wouldn’t reach cross-node routers). The emitted http.middlewares.shc-launcher-<project> block is:

http:
middlewares:
shc-launcher-<project>:
plugin:
rewritebody:
lastModified: true
rewrites:
- regex: "</body>"
replacement: "<script>...</script></body>"
# ...and the gated router's middleware chain points at this middleware after forwardauth.

The middleware name is namespaced by docker project so multiple gated stacks on the same Traefik don’t share state.

The single helper that emits this is RewritebodyMiddleware() in modules/auth/launcher.go (the name is produced by LauncherMiddlewareName(project)).

The plugin must be declared in Traefik’s static config so it gets loaded at startup. Add to the traefik command block:

- --experimental.plugins.rewritebody.modulename=github.com/traefik/plugin-rewritebody
- --experimental.plugins.rewritebody.version=v0.3.1

(Pin the version explicitly; the plugin is fetched at Traefik startup.)

Two sources resolved as a scoped override ladder (there is no deployment.launcher column and no state.json field; this is pure config):

SourceWhere
Scoped configthe launcher config key, resolved over the deployment → stack → environment → tenant → global cascade. Set at any scope, it wins outright (shc config set launcher false is the kill-switch).
App defaultapp.yaml field launcher: (true when absent), used only when the config key is unset at every scope.

If the scoped launcher config key is set anywhere it wins outright, so a config true can turn an app back on even if its author defaulted launcher: false, and vice versa. There is no “off-only” restriction.

modules/auth/launcher.go:EffectiveLauncher(appDefault bool, configValue *bool) bool is the single source of truth: if configValue != nil return it, else appDefault.

What we deliberately don’t support (yet)

Section titled “What we deliberately don’t support (yet)”
  • Per-host path-scoped roles (stack:nc:read /admin). The scope grammar reserves room for this but the resolver doesn’t read paths today.
  • Bring-your-own-Keycloak. v1 federation is via Keycloak brokering inside the system realm. A separate-Keycloak-per-tenant model is a bigger lift and adds operational surface; we kept the single-instance design until somebody needs more.
  • Self-service role assignment UI. Roles are managed via kcadm or the Keycloak admin console; an SHC-side abstraction can come later.