Gated apps and auth.disable
Some apps in the catalog carry an auth.disable variable: set it true and
the app performs no authentication of its own, trusting the SHC edge gate
as the only door. This page is the contract behind that variable: when to
use it, what it costs, and exactly how it fails when misused.
The gate
Section titled “The gate”The SHC gate is Keycloak-fronted forward authentication at the edge: for a
deployment whose access posture is gated, Traefik sends every request
through an auth middleware before the app sees it. An unauthenticated
browser is redirected to Keycloak to sign in; a non-browser request without
a session gets a plain 401. Only a user in the deployment’s tenant realm holding
the deployment’s role gets through at all. The gate covers the whole app: an app
that needs open paths is public and guards itself, and only two carve-outs
exist (docuseal /s/<token>, paperless /accounts/login). The mechanics
are covered in access control and
the access / ungated_paths fields
of the app definition.
The gate authenticates reachability. It does not log the user into the app
behind it; what the app does with an authenticated visitor is the app’s
own affair, which is where auth.disable comes in.
When to turn an app’s own auth off
Section titled “When to turn an app’s own auth off”The design case is an app whose available edition has no usable identity
story (no SSO, no multi-user), so its own login adds a second credential
without adding access control worth having. Uptime Kuma is the type
specimen: MIT-licensed, no paid tier, and structurally single-admin, with no
per-user accounts, no roles, no SSO at any price. Without the gate, the
only access control available is one shared admin password. With
auth.disable and a gated install, the team gets per-person access,
revocation on offboarding, and SSO, for an app that will never ship them
itself.
This is explicitly not a paywall workaround. Where an upstream sells SSO, the answer is the SSO coverage policy and, where relevant, a license, not stripping auth. And where an app has real SSO of its own, prefer it: the gate must not front native-OIDC apps anyway (it 401s the app’s non-HTML traffic and breaks its callback and WebSocket flows).
The contract
Section titled “The contract”The variable’s own documentation says it plainly: setting it true “removes ALL authentication” from the app. The app then trusts the gate completely: there is no second line of defense behind it. No username to guess, no password to brute-force, no token to steal: whoever can open a TCP connection to the app’s port is the administrator.
So the setting is safe only when every path to the container goes through the gate, and each of the following is total unauthenticated compromise, not a degraded posture:
- A published host port.
--expose <hostPort>=<service>:<containerPort>hands the whole instance to anything that can reach the node. - An ungated second route to the same deployment, or a gate posture set to open for its host.
- Container-port reachability on the internal network: another stack that can dial the container’s port directly never passes the gate.
Flip auth.disable true on a deployment that is not gated and you have
published full admin to whatever can reach it; for an internet-reachable
route, full admin to the internet. uptime, uptime-kuma, shlink and sonarqube
refuse that render outright. The per-app packaging spells out what
“admin” means in each case; for a monitoring tool it includes every stored
notification credential and the ability to point probes at internal hosts.
Read the app’s own app.yaml note before flipping the variable; each app
that carries it documents its measured exposure surface.
Convergence
Section titled “Convergence”auth.disable is not install-time-only: flipping it on a live install
converges, in both directions. The two shipping apps implement that in the
two ways the pattern allows:
- SonarQube: configuration-level. The compose template renders
SONAR_FORCEAUTHENTICATION: "false"only when the variable is true, so the default render is byte-identical to an install without the variable. SonarQube reads the property at every startup and persists nothing, so a redeploy converges either direction; the startup property also outranks the stored admin setting, so the UI cannot silently re-enable forced authentication (at the known cost that the admin settings page keeps displaying it as on; trust the variable, not the page). - Uptime Kuma: API-level. The setting lives in the app’s own database,
so a hook job runs on
post_installandpost_update, authenticates over the app’s control channel, and drives the stored setting to match the variable. The false branch is not a no-op: if it finds auth disabled it turns it back on; a one-way variable would leave an operator who reverted it silently serving an unauthenticated instance. The job deliberately does not run on restore: a restore replays what the backup archive held, and the next deploy reconverges it.
Both converge on shc update; neither destroys the admin credential, so
reverting the variable restores the original login.
Which apps, today
Section titled “Which apps, today”| Posture | Apps | Notes |
|---|---|---|
auth.disable supported | uptime-kuma, sonarqube | The two contracts above. More apps adopt the pattern over time; the marker is an auth.disable variable in the app’s vars.yaml, always with a matching warning note. |
| Userless by design, gated | agent-canvas, openhands | Upstream has no login and no setting to add one, so neither carries auth.disable: there is nothing to disable. Gate access is the only access decision, and everyone through the gate shares one settings store and one set of stored secrets. Both declare self_auth: false, so overriding to --open warns instead of silently publishing an unauthenticated command-execution endpoint. openhands additionally binds the Docker socket, which is its own broker socket and never the host’s, and needs privilege.deployment_grants.<t>.<e>.<s> at global scope. |
| Userless by design, not gated | ollama | Unauthenticated API by design, but machine-facing: a forward-auth gate would 401 the API calls that are its whole job. It ships access: open with LAN-only exposure, treated like a database backend: never publish a port to it in production. |
| Structurally cannot | clickhouse | Authentication is protocol-wide: alongside HTTP it serves its native TCP wire protocol (port 9000), which an HTTP forward-auth gate can never front. Disabling ClickHouse’s auth would leave the wire ports open with nothing in front of them, so the app keeps its own credentials and no auth.disable exists for it. |
Apps with their own SSO are the complement of this table: they integrate through plugs and sockets and stay ungated; see the SSO coverage policy for the full ladder.
See also
Section titled “See also”- SSO coverage policy: where the gate sits among the four acceptable SSO shapes
- Access control: the forward-auth flow, roles, and path exemptions
- App definition: the
accessaxis andungated_paths - Custom builds: builds that exist so an app does not need this posture