SSO auto-redirect: the arming plan
Status: open design. This is the per-app arming plan. Which apps on its list have since been armed is not recorded here. No estate was contacted in writing it: every value below is read out of the packages on
main, out of ce’s resolver, or out of the read-only live audit of 2026-08-10 (docs/handoff/2026-08-10-ssoautoredirect-arming-audit.md), which is cited wherever a claim rests on a live measurement rather than on source.
What this is for. The owner has hit five apps in a row whose login page shows an SSO button instead of redirecting (wazuh, penpot, ciso-assistant, dependency-track, highlight) plus frappe, which turned out to be working. This document replaces those five separate decisions with one.
0. What changed underneath this, and why the decision is now possible
Section titled “0. What changed underneath this, and why the decision is now possible”Until 2026-08-11 the documented operator surface armed almost nothing.
shc config set ssoAutoRedirect true was read in exactly one place in ce
(modules/app/ingress_materialize.go) and reached only the six apps
declaring an app.yaml sso_redirect: block. The ~16 apps that implement
auto-redirect natively read a per-app var (keycloak.autoRedirect,
keycloak.makeDefault, oidcOnly, ssoOnly) from their own compose
template, and ce’s compose render context carried no config value of any
kind, so the documented key could not reach them even in principle. It
failed silently.
Landed on both mains today:
| repo | commit | what it does |
|---|---|---|
| ce | 7112971 | resolves the decision once and publishes one resolved bool, sso_auto_redirect, into both surfaces an app package can reach: renderCtx (compose + hook jobs) and tmplCtx (consumer plug post_deployment jobs) |
| shc | 59ecac10f | eleven packages now gate on vars.<knob> or sso_auto_redirect; five that would lock an estate out deliberately do not |
Three properties of that change are load-bearing for everything below.
- Precedence is additive, not override:
vars.<knob> or sso_auto_redirect. Either surface arms; neither disarms the other. The alternative (“var overrides key”) is unimplementable, because every cataloguevars.yamlships its knobfalse; a deliberatefalseis byte-identical to an untouched default, so the packaged default would beat the operator’s intent, always. The way to exempt one deployment from a fleet-wide flip is therefore a config row at deployment scope, not a var. - The
or <name>form, never the bare name. A jinja{% if %}over an undefined name drops its branch silently, so a template gating only on the new name would render “off” on any older daemon, unarmable by any surface, which is strictly worse than the defect. Verified during landing, for both the block form and the inline{{ … if … else … }}form windmill’s init job uses: with the name absent, theorspelling renders exactly as before and collects zero missing refs (an older daemon would otherwise refuse the install withX500047CMPRND). A bare name renders “off” even when the var is true. The catalogue is safe ahead of a ce pin bump; shc’sgo.modstill pins ce6a3dcc5and does not need to move for this. - No
config.*namespace was exposed.core/config/default.yamlholdsbackup.password,backup.aws_secret_access_key,vault.providers.*.token,smtp.passwordand per-provider DNS tokens, and app packages are registry artifacts re-rendered by whatever daemon installs them. A whole-tree exposure would let any package emit the estate’s restic password. What ships is one bool naming a decision, guarded by an exact-set assertion ince/modules/app/sso_autoredirect_render_surface_test.goso that widening it fails a test rather than a production estate.
1. The decision, in one line
Section titled “1. The decision, in one line”Set
ssoAutoRedirect trueat global scope on both estates, after the two pre-flight cleanups in §5.
That arms bucket A only. Bucket B is structurally unreachable from this key (guarded by a differential render test, §3). Bucket C has no mechanism to arm (§4).
Live blast radius is smaller than the catalogue suggests. Most bucket-A apps are not deployed on either estate. The flip changes behaviour on five live deployments today; the rest is future installs.
2. Bucket A: SAFE TO ARM (has a verified local-login bypass)
Section titled “2. Bucket A: SAFE TO ARM (has a verified local-login bypass)”An entry belongs here only if the escape URL is verified against package evidence. That URL is what makes arming reversible during a Keycloak outage; without one, an entry belongs in bucket B.
A1: native-knob apps (the eleven newly unified)
Section titled “A1: native-knob apps (the eleven newly unified)”| App | Knob | Escape URL | Evidence | Deployed |
|---|---|---|---|---|
| gitlab | keycloak.autoRedirect | /users/sign_in?auto_sign_in=false | apps/devops/gitlab/compose.yaml:332 (gate :324) | both estates |
| ciso-assistant | keycloak.autoRedirect | /login?local=1, any non-empty query string | apps/security/ciso-assistant/compose.yaml:383-388; the Caddy matcher fires only on {http.request.uri.query} == "" | both estates |
| nextcloud | keycloak.autoRedirect | <basePath>/login?direct=1 | apps/collaboration/nextcloud/oidc.plug.yaml:723-725,751 | bitspur |
| librechat | keycloak.autoRedirect | /login?redirect=false | apps/ai/librechat/compose.yaml:247-251 (ALLOW_EMAIL_LOGIN stays true) | none |
| paperless | keycloak.autoRedirect | /accounts/login/?loggedout=1 | apps/documents/paperless/compose.yaml:172-175 | none |
| immich | keycloak.autoRedirect | /auth/login?autoLaunch=0 | apps/media/immich/oidc.plug.yaml:63-66 | none |
| defectdojo-classic | keycloak.autoRedirect | /login?force_login_form | apps/security/defectdojo-classic/compose.yaml:118-121 | none |
| midpoint | keycloak.makeDefault | <base>/midpoint/auth/default | apps/security/midpoint/compose.yaml:604,672-675 | none |
| midpoint-classic | keycloak.makeDefault | <base>/midpoint/auth/default | apps/security/midpoint-classic/compose.yaml:604,672-675 | none |
| ⚠ wordpress | keycloak.autoRedirect | /wp-login.php?login-error=1 | apps/cms/wordpress/compose.yaml:60-67 | none |
⚠ wordpress is a half-bypass and should be treated as bucket B until
fixed. The page renders, then the plugin strips the credential form with
JavaScript; recovery needs a browser with JS disabled (the credential POST
itself is never intercepted). It is listed here because its knob is wired
to the key, not because the escape hatch is sound. If the owner wants a
clean fleet-wide yes, set ssoAutoRedirect false at wordpress’s stack scope
as part of the arming change; there is no wordpress on either estate today,
so this is a catalogue-hygiene item, not an outage risk.
A2: sso_redirect: router apps (already answered the key; unchanged)
Section titled “A2: sso_redirect: router apps (already answered the key; unchanged)”Six apps take auto-redirect at the Traefik edge. They have always read this
key. ce’s rule carries a !Query(sso,false) clause, so every one of them
has the same escape hatch, ?sso=false: defaultSSOBypassQuery at
ce/modules/app/sso_redirect.go:73, rendered at :471-474 and :817-820.
No app in the catalogue overrides bypass_query:.
| App | Escape URL | Deployed / armed today |
|---|---|---|
| frappe | /login?sso=false | bitspur ×3 (ffx, bit, erpnext), already armed at deployment scope |
| huly | /login?sso=false | both estates, already armed at stack scope |
| windmill | /user/login?sso=false | both estates, already armed at stack scope |
| affine-rs | /sign-in?sso=false | both estates, already armed at deployment scope |
| affine | /sign-in?sso=false | armed but inert (down on bitspur; orphan dir on promanager) |
| kutt | /login?sso=false | none |
★ windmill is the one app under both mechanisms, and its two bypasses are
not interchangeable. Windmill’s own ?no_sso=1 is read in the browser and
is therefore defeated by an edge 302 that fires before any HTML is
delivered. Measured on both estates 2026-08-10: ?no_sso=1 → 302,
?sso=false → 200. Document ?sso=false; documenting ?no_sso=1 is a
lockout instruction. A bats guard asserts the description names
?sso=false first (apps/automation/windmill/tests/tests.bats:776-779).
★ frappe’s ?sso=false reaches the login page on all three installs,
but whether a password form renders is per-site.
disable_user_pass_login is 0 on erp.corp.bitspur.com ✔, 1 on
hq.corp.bitspur.com ✘ and hq.flyingfoxlabs.in ✘. Pre-existing, detected
by login-path-audit.job.yaml (G8), unrelated to this flip, but it means
two of three frappe sites have no credential door regardless of what this
key says.
Logout behaviour is a separate axis, and it bites
Section titled “Logout behaviour is a separate axis, and it bites”On gitlab, frappe, huly, affine, ciso-assistant, defectdojo-classic a
logout does not end the Keycloak session, so signing out signs the user
straight back in. On those apps the escape URL doubles as the only way to
actually stay logged out. gitlab is the exception that already handles it:
its after_sign_out_path companion is set outside the autoRedirect
block (apps/devops/gitlab/compose.yaml:363, inside {% if integrations.oidc %} at :339) and is deliberately not conditioned on the
knob, so federated sign-out is already on whenever OIDC is bound.
3. Bucket B: NO BYPASS. Arming risks total lockout.
Section titled “3. Bucket B: NO BYPASS. Arming risks total lockout.”Leave these for a separate, explicitly-consented decision.
Five apps. All five declare local_login.closed_by: in their own app.yaml,
the same declaration ce’s post-restore usable-login check reads
(ce/modules/app/login_path_postcheck.go:121-122,171,323,336 →
X200042NOLOGIN). The catalogue guard derives the exclusion from that
declaration rather than from a hand-maintained list.
| App | Knob | What the knob actually does | Bypass |
|---|---|---|---|
| gitea | keycloak.autoRedirect | sets ENABLE_PASSWORD_SIGNIN_FORM: false | none at 1.27.1; recovery needs shell access to redeploy |
| wazuh | keycloak.autoRedirect | names openid the dashboard’s sole auth type, deleting the password form | none |
| matrix | keycloak.autoRedirect | flips MAS passwords.enabled: false; Synapse password auth is already force-closed for MAS delegation | none |
| journiv | oidcOnly | disables password login outright | none |
| vaultwarden | ssoOnly | disables password login outright | none |
★ journiv and vaultwarden are not redirect knobs at all. oidcOnly and
ssoOnly do not redirect anything; their entire effect is removing the
credential login form, and both render unconditionally (gated_on_edge: false), so they close the door with or without a bound IdP. Collapsing them
into a fleet-wide “auto-redirect” would strand every local admin on every
deployment, for a setting that never had “redirect” in its meaning. That is
why they are excluded, and it is a different reason from gitea/wazuh/matrix,
where the redirect is the removal of the form.
They stay per-deployment --var, and that is the recommendation. A
fleet-wide redirect preference must never make a fleet-wide lockout
decision. If the owner does want any of these armed, it should be one named
deployment at a time, with the recovery path rehearsed first.
This is enforced, not documented.
tests/unit/catalog/sso_unified_surface_test.go:377
(TestTheScopedKeyNeverClosesADeclaredDoor) is a differential render test:
for every app declaring local_login.closed_by, the render under
ssoAutoRedirect true must be byte-identical to the render with both
surfaces off, and the --var must still change it (so exclusion never
becomes deafness to both surfaces). It fails loudly if the corpus is empty,
the failure mode this project has already shipped once.
4. Bucket C: CANNOT. Structural, with the failing author check named.
Section titled “4. Bucket C: CANNOT. Structural, with the failing author check named.”These apps have no auto-redirect mechanism to arm. The flip is a strict no-op for them; they are listed so the owner knows the button is not coming back for them without work.
| App | Failing check | Detail |
|---|---|---|
| penpot | checks 1 and 2 | GET /api/rpc/command/login-with-oidc → 405, POST-only; and its login page is the SPA fragment /#/auth/login, which is never transmitted to the server, so no PathRegexp can see it. Pinned: tests/unit/catalog/sso_redirect_audit_test.go:316-336 |
| dependency-track | check 2 | browser-minted PKCE: discovery and code_challenge are built in the browser, the verifier never leaves browser storage, redirect_uri=https://<host>/static/oidc-callback.html. The selector form cannot help either: the shell has zero anchors (the button is a Vue component). Measured 2026-08-09 in Chromium; apps/security/dependency-track/app.yaml:110-157, pinned at sso_redirect_audit_test.go:281-315 |
| vaultwarden | check 2 | browser-minted PKCE (Bitwarden web-vault mints its own verifier against /identity/connect/authorize and calls /api/sso/prevalidate first). ⚠ asserted in-repo, never measured; not deployed on either estate |
| minio | check 2 | POST-only/JSON login-strategy endpoint. ⚠ the measurement is STALE: it was taken against the old embedded console, and SHC now ships a third-party community fork sidecar (georgmangold/console) whose OIDC flow the package itself says is “NOT yet live-verified against a Keycloak” (apps/storage/minio/compose.yaml:126-127) |
| sonarqube | check 5 | passes checks 1-4 (/sessions/new?sso=false → 200 with the local form) but logout lands on /sessions/new with no distinguishing key, and Community Build has no SAML SLO → infinite re-login. A documented refusal, pinned at sso_redirect_audit_test.go:200-259 |
| highlight | check 1 + cross-host | SPA shell with no server-visible login path, and the cross-host class below |
The cross-host class: one instance, not a pattern
Section titled “The cross-host class: one instance, not a pattern”ce builds the redirect target from each route’s own host, by design:
resolvePath strips any scheme+host from a declared sso_start:
(ce/modules/app/sso_redirect.go:319-329) and
ssoRedirectReplacement(rt.Host, ssoStart) re-attaches this route’s origin
(:498-506, :555-560). The intent is written into the file at :29-39
and pinned by TestEachHostRedirectsToItsOwnOrigin
(sso_redirect_test.go:118-140): a multi-host service must never bounce a
visitor cross-origin mid-login. So an app whose login page is on one host
and whose SSO start is on another cannot have a redirect built for it.
highlight is such an app: login page on highlight-frontend, OIDC start
/private/oauth/login on highlight-backend
(apps/enterprise/highlight/compose.yaml:86-88; oidc.plug.yaml:8-9 pins
the plug to highlight-backend alone).
dependency-track is NOT the second instance; checked, and the answer is
no. The “two hosts sbom and sbom-api” premise is stale. At HEAD
dependency-track is one hostname, path-routed; the ingress contract is
written into apps/security/dependency-track/app.yaml:42-108 (”★ INGRESS
CONTRACT: ONE HOSTNAME, TWO SERVICES, PATH-ROUTED”), the frontend owns the
entire browser auth surface including /static/oidc-callback.html
(:88-91), and TestDependencyTrackOIDCCallbackStaysOnTheFrontend
(tests/unit/catalog/dtrack_single_host_test.go:378-381) pins it. Its
refusal is browser-minted PKCE, above.
Recommendation: do not build a cross-host mechanism. The class has one
live member (highlight), which is separately ruled out of the errors league
on the paid-SSO axis (docs/decisions/2026-08-06-flagship-tier.md:280);
its OIDC auth mode is license-gated upstream, so a mechanism built for it
buys an app the estate has decided not to run. One dormant member exists,
blockscout, whose ACCOUNT_KEYCLOAK_* support arrives only at backend
v10.1.0 while the pin is 9.0.2, worth watching on a bump, not worth
pre-building for. matrix is structurally cross-host but has a native knob
and never needs the router.
The cheaper fix already exists and has already been applied once: consolidate onto one hostname with path prefixes, which ce handles natively and which dependency-track has already done.
★ One defect worth fixing regardless of the above. A cross-host
declaration fails silently. A packager who writes sso_start: "{{ url('other-service') }}/oauth/login" gets no warning; resolvePath
quietly discards the origin and the router 302s to
https://<this-route's-host>/oauth/login, which 404s. The only refusals
ssoRedirectRouter emits are loginPath == ssoStart and an unrenderable
rule pattern. Recommend a lint check that refuses a sso_start:
templating a different service than the route it lands on.
5. Pre-flight: two cleanups that must land in the same change
Section titled “5. Pre-flight: two cleanups that must land in the same change”Neither is optional; both were found in the 2026-08-10 live audit and neither has been touched.
-
★ Delete
zz-ssoedge.yamlon bitspur, in the same change that arms the key. It is a hand-written Traefik dynamic file arming nextcloud (cloud.corp.bitspur.com,^/login/?$, priority 90000). Its own header says it exists because the catalogue nextcloud does not declaresso_redirect:, and that it must be deleted oncessoAutoRedirectis set; otherwise the two duplicate. Nextcloud is a bucket-A app whose knob is applied from a consumer plug job, so a global flip does trigger this condition. Today there is exactly one router and no duplication; arming without deleting creates two. -
Reconcile the
affine-rssplit rows. Both estates carryssoAutoRedirect falseat stack scope andtrueat deployment scope. Deployment wins so it resolves true today, but the pair reads like a half-finished edit, and the next operator to delete the deployment row silently disarms it. A globaltruedoes not change the resolution (deployment still wins), but it makes the strayfalseactively misleading. Remove the stack row:shc config set ssoAutoRedirect! -t corp -s affine-rs --scope stack.
Also worth clearing while in there, though inert: corp/affine is armed on
both estates and serves nothing (down on bitspur; an orphan
/var/lib/shc/deployments/corp/affine directory on promanager, not in shc ls).
6. The exact commands
Section titled “6. The exact commands”Arm bucket A, both estates (run once per estate, on the estate’s node,
against unix:/run/shc/shc.sock):
# pre-flight 1, bitspur onlysudo rm /var/lib/shc/system/traefik/dynamic/zz-ssoedge.yaml
# pre-flight 2, both estatesshc config set ssoAutoRedirect! -t corp -s affine-rs --scope stack
# the arming decision itselfshc config set ssoAutoRedirect true --scope globalGlobal scope is the right tier because the resolution ladder is
deployment > stack > environment > tenant > global: a global row is the
weakest, so every existing stack/deployment row (all of which already say
true, bar the affine-rs stray) keeps winning, and any future exemption
is a narrower row rather than an edit to this one.
Exempt one deployment (this is the only correct way; a false var is
indistinguishable from an unset one):
shc config set ssoAutoRedirect false -t corp -s <stack> -e prod --scope deploymentRollback. Two forms, and the difference matters:
# preferred: delete the global row, falling back to the packaged default (false)shc config set ssoAutoRedirect! --scope global
# or pin it off explicitlyshc config set ssoAutoRedirect false --scope global★ A removal deletes the row at exactly one tier (the one set with the
same flags would have written) and nothing else
(ce/modules/config/commands/set.go:29-60). It is the exact inverse of the
set, deliberately not “make this key go away”. So the rollback above removes
only the global row; every pre-existing stack/deployment true survives it,
which is what you want; rollback should restore the state before the flip,
not disarm apps that were armed on purpose beforehand.
No redeploy is required. ce re-resolves the flag every ingress sweep,
and the compose surface re-renders on the next update. For the native-knob
half (bucket A1) the template value only changes on the next deploy of
that app, so a bucket-A1 app already running will pick it up at its next
shc update.
Verification after arming (read-only, per the audit’s own recipe):
sudo grep -n 'rule:\|loginPattern\|ssoSelector\|redirectRegex' \ /var/lib/shc/system/traefik/dynamic/ingress-*.yamlcurl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' https://<host>/<login-path>curl -sS -o /dev/null -w '%{http_code}\n' 'https://<host>/<login-path>?sso=false'7. Cross-site hosts: a correction, and why they are a different risk
Section titled “7. Cross-site hosts: a correction, and why they are a different risk”A host whose registrable domain differs from the estate’s primary is
cross-site relative to auth.corp.<primary>. That matters here because
the launcher’s silent check and the post-logout behaviour both differ
cross-site (it is exactly the case the cross-site click-through fallback was
built for), and because each such host carries its own DNS zone and its own
certificate, so an ACME/renewal failure can hit it without touching any
corp.* host.
★ git.corp.promanager.online does not exist. The string
promanager.online appears in no file on this box. The GitLab host on that
estate is git.corp.promanager.vip, same registrable domain as the
estate primary, therefore same-site, and not a cross-site case at all.
The promanager estate’s DNS connection carries zones = ["promanager.vip"]
(promanager-ops/hetzner/hel1/infra/main.tf:474), one zone only, so it
cannot currently serve a cross-site host.
| estate | primary | cross-site hosts |
|---|---|---|
| promanager | promanager.vip (.gitlab-ci.yml:124) | none |
| bitspur | bitspur.com (.gitlab-ci.yml:78) | two |
bitspur’s zones = ["bitspur.com", "selfhostedcloud.org", "flyingfoxlabs.in"] (bitspur-ops/hetzner/hel1/infra/main.tf:353) is the
structural enabler of both:
- ★
hq.flyingfoxlabs.in: frappe, stackffx, SSO-bound to bitspur’s Keycloak, already armed at deployment scope and live-measured working. It is the canonical cross-site case in the code (shc/traefik/plugin/launcher_crosssite_test.go:47) and the named reason a parent-domain launcher cookie was refused (traefik/plugin/launcher.go:38). It is declared in no file anywhere, a CLI-created deployment from the k8s→SHC restore whose only file-level lever is that one string inzones. A customer’s domain, on bitspur’s Traefik, with its lifecycle in CLI history: the single highest-leverage undocumented dependency in either estate, and worth declaring in the ops repo independent of this plan. license.selfhostedcloud.org: license-broker. No OIDC by design (gated = false;/activateis a machine API with no browser session), so it is out of scope for arming. Note it is the one host pinned toacme_provider = "prod", and its URL is baked into every released shc binary from v0.0.12, a frozen consumer contract.
Implication for arming: the only cross-site host that this flip touches
is hq.flyingfoxlabs.in, and it is already armed and already working. The
global flip does not change its resolution (its deployment row wins). No new
cross-site exposure is created by this decision.
8. Summary: the one yes
Section titled “8. Summary: the one yes”| bucket | count | what the flip does |
|---|---|---|
| A: safe to arm | 16 packages: 11 native-knob + 6 router, windmill being in both (5 live deployments newly affected: gitlab ×2, ciso-assistant ×2, nextcloud ×1) | arms them; every one has a verified escape URL |
| B: no bypass | 5: gitea, wazuh, matrix, journiv, vaultwarden | strict no-op, enforced by a differential render test |
| C: cannot | 6: penpot, dependency-track, vaultwarden, minio, sonarqube, highlight | strict no-op; no mechanism exists |
Recommended: yes to §6 on both estates, with the two §5 pre-flights in the same change, and wordpress pinned off at stack scope until its JS-stripped bypass is fixed.
Deferred to a separate, explicitly-consented decision: bucket B, one named deployment at a time.
Recommended not to build: a cross-host redirect mechanism. One live member, itself already ruled out on the payment axis. Build the silent- misdeclaration lint (§4) instead.
9. The native-knob tier: which surface arms it, and the two that must not be armed
Section titled “9. The native-knob tier: which surface arms it, and the two that must not be armed”Added 2026-08-11 after walking every native-knob package that ships its knob
OFF: paperless, immich, midpoint, midpoint-classic, wordpress,
defectdojo-classic. All six were already wired to the fleet-wide surface by
59ecac10f; the open question was whether any of them should be armed in the
CATALOGUE rather than on an estate.
9.1 There are three surfaces, and only one of them is an estate decision
Section titled “9.1 There are three surfaces, and only one of them is an estate decision”| surface | where it lives | can a scoped row turn it back off? |
|---|---|---|
vars.keycloak.<knob> | the package’s vars.yaml | no |
app.yaml sso_auto_redirect: | the package’s app.yaml | yes; a scoped row overrides it outright |
ssoAutoRedirect config row | the estate’s dqlite | yes; it is the row |
★ A vars.yaml default of true would be UNEXEMPTABLE, and that is a
stronger objection than “it changes behaviour”. The two surfaces are
additive (vars.<knob> or sso_auto_redirect), so a packaged true arms the
var leg on every install and no config row at any scope can clear it; shc config set ssoAutoRedirect false --scope deployment would clear only the
other leg. It is refused by TestNativeKnobDefaultsOffInVarsYaml and, for the
makeDefault spelling, by TestChannelKnobDefaultsOffInVarsYaml.
★ The app.yaml sso_auto_redirect: field IS a real catalogue lever and it
stays exemptable; ce resolves it as a DEFAULT that a scoped row beats
(ce/modules/app/launcher.go, SSOAutoRedirectForAppDir: the scoped value
returns if present, the app.yaml field is the fallback). It is still not
used here, deliberately. ce’s own resolver states the design in as many
words: “the app.yaml default is FALSE. The launcher is cosmetic and ships on;
this changes where a login attempt lands, and an app whose IdP is
misconfigured would send every visitor into a broken flow. It is opt-in, per
deployment, by an operator who can see the IdP.” The failure mode it names is
a misconfigured IdP, not an absent one, so the and integrations.oidc
gate every one of these six carries does not cover it. A bound-but-broken
Keycloak (wrong realm, rotated secret, expired cert) is exactly the case that
strands a consumer of selfhostedcloud.org/apps whom this repo cannot see and
cannot roll back for.
Conclusion: no catalogue default changes. Arming this tier is an estate action, per §6, on an estate whose IdP the operator can see.
9.2 The four that arm cleanly
Section titled “9.2 The four that arm cleanly”Every row’s break-glass is package evidence, and every row’s knob was
confirmed to emit a real navigation, not merely to hide a credential form
(the force_sso/ssoOnly class, which fails the definition rather than a
check).
| App | Knob | Break-glass | Logout (check 5) | Guarded by |
|---|---|---|---|---|
| paperless | PAPERLESS_REDIRECT_LOGIN_TO_SSO | /accounts/login/?loggedout=1 | ✔ logout lands on the bypass | TestNativeKnobRendersOnlyWhenArmed/paperless |
| immich | OIDC_AUTO_LAUNCH → .oauth.autoLaunch | /auth/login?autoLaunch=0 | ✔ | awaitingBothLegsGuard (plug-job shape) |
| midpoint | keycloak.makeDefault | <base>/midpoint/auth/default | ✔ | TestChannelKnobMovesTheDefaultOnlyWhenArmed |
| midpoint-classic | keycloak.makeDefault | <base>/midpoint/auth/default | ✔ | same |
★ midpoint’s two packages had no guard at all until this change, and no
error either. They spell the knob keycloak.makeDefault, and
TestEveryNativeKnobAppIsInThisTable swept vars.yaml for autoRedirect
alone, so the ratchet whose entire job is to say “this app is unguarded”
walked past both of them in silence. The sweep now covers every spelling
(nativeKnobVarNames), and the mechanism itself is asserted on three legs
plus the break-glass in sso_auto_redirect_channel_knob_test.go: arming moves
the #user channel default and must not delete the admin-gui-default
sequence or change its urlSuffix, because that surviving suffix is the whole
recovery path. midpoint’s and midpoint-classic’s makeDefault descriptions
named no bypass at all before this change; they do now.
9.3 The two refusals
Section titled “9.3 The two refusals”wordpress: REFUSED. The break-glass is half a hatch.
/wp-login.php?login-error=1 renders the page and then
remove_login_form() deletes the credential form from the DOM in JavaScript
(daggerhart-openid-connect-generic 3.11.3 login-form.php:85,197). Recovery
therefore needs a browser with JS disabled. “Reaches a local credential form
when the IdP is down” is the standard, and a form deleted on load does not
meet it. The knob stays wired and stays off; if the fleet key is set globally,
wordpress needs an explicit stack-scoped exemption (§9.4).
defectdojo-classic: REFUSED. Check 4 passes, check 5 fails, measured.
/login?force_login_form genuinely reaches the form, so this is not the
gitea/wazuh no-bypass class. But dojo/user/views.py:139-143 is
logout(request) followed by return login_view(request) without the
force_login_form marker, and 2.58.4 has no RP-initiated logout, so an armed
deployment signs the user straight back in off the live Keycloak session.
Arming it ships an app that cannot be signed out of. Same exemption.
Both refusals were already written into the packages’ own app.yaml var
descriptions and into nativeKnobs’ evidence comments; §9.3 is where the
decision that follows from them is recorded.
9.4 The exact commands: estate-side, NOT applied by this change
Section titled “9.4 The exact commands: estate-side, NOT applied by this change”Run on each estate’s node, against unix:/run/shc/shc.sock. Verify first,
because the resolution ladder means a pre-existing narrower row wins:
# what is set today, at every scopeshc config ls -o json | grep -A2 ssoAutoRedirect# nothing printed = no row anywhere = the packaged default (false) is in forceArming the tier is the §6 global flip; these apps need no per-app row. What they need is the exemptions and a redeploy:
# the two refusals: set BEFORE the global flip, so they are never armed at allshc config set ssoAutoRedirect false -t <tenant> -s wordpress --scope stackshc config set ssoAutoRedirect false -t <tenant> -s defectdojo-classic --scope stack
# the arming decision itself (§6)shc config set ssoAutoRedirect true --scope global
# native knobs are TEMPLATE values: an already-running deployment picks the# new render up on its next update, not on the next ingress sweep.shc update -t <tenant> -s <stack> -e <env>To undo, remove the row rather than pinning it off; a removal deletes exactly the tier it names and leaves every deliberate narrower row standing:
shc config unset ssoAutoRedirect --scope global★ §6 spells the removal shc config set ssoAutoRedirect! --scope global. The
subcommand in the shipped CLI is shc config unset <key> --scope <scope>; use
that.
None of the six is deployed on either estate as of the 2026-08-10 audit,
so the blast radius of the flip on this tier is future installs plus whatever
shc ls --all-tenants shows at the time it is run. Confirm that before
running it; the audit is a snapshot, not a lock.