Skip to content
SHC Docs

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

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

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_install and post_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.

PostureAppsNotes
auth.disable supporteduptime-kuma, sonarqubeThe 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, gatedagent-canvas, openhandsUpstream 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 gatedollamaUnauthenticated 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 cannotclickhouseAuthentication 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.