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.
The pieces
Section titled “The pieces”| Piece | Role |
|---|---|
| System Keycloak | Single Keycloak deployment in the system tenant; the IdP for the entire SHC instance. Has no default main realm; realms are per-tenant. |
| Tenant realm | One realm per SHC tenant, named after the tenant (e.g. acme). Users belong to exactly one realm. |
shc-access client | A bearer-only client provisioned in every realm. Holds the tenant:* and stack:* roles that drive permission decisions. |
| forward-auth | A 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 axis | Per-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 axis | Per-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 beopen + internet,gated + lan, or any combination.The legacy per-app
public:field inapp.yamlis a read-only migration seed: on read,NormalizeDeploymentDisposition(modules/app/disposition.go) maps a setpublic: true→access: openand absent/false→access: gated, withexposuredefaulting tolan. An already-setaccess/exposurealways wins. There is no longer a--no-publicflag; to gate an app use--gated.External L4 load balancers are orthogonal to both axes. There is no
--proxyflag and noproxy.connectionconfig: 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--exposeDNS 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.
Tenant lifecycle
Section titled “Tenant lifecycle”shc tenant add acmecallsprovision_tenant_realm("acme"). If the system Keycloak is up, the realm +shc-accessclient 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 acmecallsdeprovision_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 thevalidation.TenantNamecheck, which raisesX400982NAMINV, wrapped by tenant create asX400974TNTNAM.
Stack lifecycle
Section titled “Stack lifecycle”- On install:
_provision_stack_access_rolecreates the whole per-stack ladder (stack:<name>plus:use,:read,:operate,:manageand:deny(StackRoleNames→CreateAccessRoles)) on the tenant’sshc-accessclient. All of them, deliberately:AssignRolepre-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’saccessaxis; the role is used for admin grant tracking even when the deployment isopen(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_roleruns afterpost_uninstall.
Role grammar
Section titled “Role grammar”<scope>[:<verb>]- Bare scope → implicit
useverb. - Verb hierarchy (descending):
manage⊃operate⊃read⊃use. - Holding a higher verb implicitly satisfies any lower-verb check.
Scopes and what they grant:
| Scope | Meaning |
|---|---|
tenant | Member of the tenant. |
tenant:manage | Tenant 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>:read | The 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>:operate | Operate (start/stop/restart) on a stack. |
stack:<name>:manage | Full lifecycle control. |
stack:<name>:deny | Explicit carve-out. Not a verb; any matching deny at any scope wins outright, ahead of every allow. |
tenant:read | The 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:manage | SHC-platform admin (system realm only). Implicitly satisfies every other check on every tenant. |
platform:read | Read-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.
read: the developer role
Section titled “read: the developer role”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.
| Surface | Route / gate | What stack:<n>:read gets |
|---|---|---|
| Container logs | shc.logs.get, shc.stack.logs.stream, shc.stack.logs: logs.ReadPermitted | The stream as the container wrote it, not masked (see below) |
| Deployment status | shc.stack.status (app module) | Full status; the gate there is tenant membership, which read implies |
| Audit / events | audit:read, events:read + StacksWithPermission(VerbRead) | Rows scoped to the stacks the caller can read |
| Configuration | shc.stack.config.noref: logs.ReadPermitted | The no-ref render: ref+vault:// pointers left literal |
| Browser access | forward-auth | Allowed: 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.
Cross-tenant access
Section titled “Cross-tenant access”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:
| Token | System stack | Socket | Plug-data override | Purpose |
|---|---|---|---|---|
KEYCLOAK | keycloak | keycloak | realm=<consumer_tenant> | Shared IdP: every tenant gets its own realm under a single Keycloak |
BRANDING | branding | branding | (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:
# Form 1: auto-match the consumer's matching plugshc 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=KEYCLOAKThere 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.
Secrets never cross the boundary
Section titled “Secrets never cross the boundary”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:
| Token | Redacted socket fields (cross-tenant only) |
|---|---|
KEYCLOAK | oidc.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
KEYCLOAKspecifically. A consumer deployed in the master tenant hasProviderTenantName == tenant, so the rule never fires and itsjobs.post_deploymentshell receives the real cross-realm credential. The master tenant is one trust domain with the platform, not with the estate’s other tenants. - Only
@secretfields are covered.adminUseris typed@string!, so the username half of the credential crosses every boundary.kcadmPathis likewise unredacted, and a consumer job that shellskcadm.shauthenticates with the same credential by another door. - There is no per-app boundary at all. Any app declaring an
ssoplug may readintegration.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:
# `dev` environment's nextcloud uses `prod` environment's mail relayshc -e dev install nextcloud --integrate mail@prod
# Explicit plug + cross-envshc -e dev install nextcloud --integrate smtp=mail@prod
# Socket-qualified + cross-envshc -e dev install nextcloud --integrate smtp=mail.smtp@prodThe 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.
Forward-auth flow
Section titled “Forward-auth flow”- Browser hits
nextcloud.example.com. - Traefik invokes
forwardAuthmiddleware → the forward-auth service, withX-Forwarded-Host: nextcloud.example.comand the client’sAuthorizationheader (or the session cookie). - forward-auth verifies the token against the issuing realm’s keys
(the realm comes from the JWT’s
issclaim, not from anytenantspayload claim), then applies the revocations and the declared platform admins from its node’sauthclusterfs section. It calls shcd for no verdict. - forward-auth looks up the host in the section’s
realms.json→ tenant + stack. - 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).
- Allow responses set
X-SHC-User,X-SHC-Tenant,X-SHC-Stackfor downstream consumption.
Per-app path exemptions (ungated_paths)
Section titled “Per-app path exemptions (ungated_paths)”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: openungated_paths: - /accounts/loginFor 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:
swaggerUIHTMLcallsSwaggerUIBundlewithurl,dom_idandoauth2RedirectUrl, and neverui.initOAuth(...), so the UI has no client id to authorize with.buildOpenAPISpecemitsopenapi/info/pathsand nocomponents.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 intoauth.Configand 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.
shc-swagger: retired 2026-08-08
Section titled “shc-swagger: retired 2026-08-08”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.
User self-introspection
Section titled “User self-introspection”GET /api/user/apps: every stack the user canuse(plus app/host metadata). Platform admins see every tenant’s stacks.GET /api/user/managed-apps: stacks where the user holds at leastmanage(per-stack, tenant-wide, or platform-wide).
Floating launcher button
Section titled “Floating launcher button”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).
Injection mechanism
Section titled “Injection mechanism”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)).
Operator step (one-time per deployment)
Section titled “Operator step (one-time per deployment)”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.)
Per-stack and global enable/disable
Section titled “Per-stack and global enable/disable”Two sources resolved as a scoped override ladder (there is no
deployment.launcher column and no state.json field; this is pure
config):
| Source | Where |
|---|---|
| Scoped config | the 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 default | app.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.