Skip to content
SHC Docs

Flow: authentication

Layer 10. Edge. Edge

Every way a person establishes identity against an SHC estate, and what is actually armed. Three independent axes (who proves identity, how the browser reaches the IdP, and which sessions exist) plus the eight concrete flows those axes compose into.

Source of truth:

  • traefik/plugin/launcher.go, traefik/plugin/menu.go: the injected apps menu and its silent OIDC check.
  • forward-auth/cmd/forward-auth/main.go: the forward-auth gate sidecar (authorize, callback, logout).
  • traefik/plugin/auth.go: the in-plugin gate (a second implementation; see §9).
  • ce/modules/auth/: service.go (bearer validation), forward_auth_client.go (the Keycloak client), backchannel_logout.go, session_revocation.go.
  • ce/modules/app/sso_redirect.go, traefik/plugin/ssoselect.go: the two edge auto-redirect mechanisms.

Related: access control is the authorization boundary (who may call what). This page is authentication (how you prove who you are). The launcher is covered in depth on its own page, flows/launcher.md. Design rationale for the edge redirect lives in the sso-auto-redirect proposal.

Provenance. This page began as a reference artifact measured against the live estates on 2026-08-10. It was checked against the tree the same day and four load-bearing claims did not survive; they are marked ★ where they appear, with the evidence that corrected them. Two failed against code that had been in the tree for days; one was overtaken by commits that landed hours later; one was a measurement-methodology artifact. Claims labelled measured are live-estate observations that a code read cannot confirm or refute; where a live measurement and a code citation disagree, both are recorded rather than one being silently dropped.


These are separate decisions. Most confusion about SHC auth comes from treating them as one. Any deployment is one choice from each.

PostureMechanism
App-nativeThe app runs its own OIDC or SAML flow; Traefik passes traffic through untouched. GitLab, Nextcloud, AFFiNE, Frappe.
Forward-auth gateaccess: gated. The proxy authenticates before the app is contacted. Gives SSO to an app that cannot do it.
LauncherThe apps menu’s own silent check. Independent of both, deliberately, so it works on ungated apps.
NonePublic. Traefik proxies and nothing else happens. access: open is the default.

★ The artifact said “exactly one deployment on either estate is gated: openhands on bitspur.” The app named does not exist. openhands was retired 2026-08-06 (apps/RETIRED:72, commit 4d0d7dc05), superseded by agent-canvas. Three catalogue apps pin access: gated today:

AppDeclaration
openreplayapps/flagship/openreplay/app.yaml:40
graphitiapps/ai/graphiti/app.yaml:47
agent-canvasapps/ai/agent-canvas/app.yaml:124

The deployment-level claim (one gated user-facing host on bitspur, the agents stack) remains consistent with tests/unit/modules/app/launcher_router_coverage_test.go:66-68. The posture was right; the name was four days stale.

Five mechanisms. Three are app-side, two are edge-side.

MechanismWhereHow it firesVisible to curl?
server 302appThe app redirects to Keycloak itselfyes
auto-submit formappA hidden <form method=post> plus a script that submits itno
client-side JSappAn SPA calls location on mountno
edge staticTraefikRouter rule → redirectRegex (ce/modules/app/sso_redirect.go:471)yes
edge selectorpluginBuffers the login page, reads the SSO button’s href, 302s there (traefik/plugin/ssoselect.go:322)yes

Two of these are invisible to every automated check. An auto-submitting form and a client-side redirect both look like “no redirect” to curl -L. That is how GitLab was reported broken when it worked, and how others were reported working when they were not. Only a real browser settles it.

★ That lesson has a second edge, and the artifact did not apply it to its own sweep: see §8, where a root-path probe concluded “0 edge rules armed” against six apps that declare one.

SessionScopeMeaning
Keycloak SSOauth.corp.<estate>The only one that means “who you are”. The launcher keys on this and nothing else.
App sessionthe app’s own cookie, own hostOnly the app can validate it.
shc_access_tokenhost-only, Path=/, SameSite=LaxThe gate’s cookie. Gated apps only. forward-auth/cmd/forward-auth/main.go:491-499.
shc_launcherhost-only, Path=/.shc/launcher/, SameSite=None, 30 minThe menu’s handle. One per hostname. traefik/plugin/launcher.go:674-681.

All host-only: no Domain attribute is set anywhere, verified at both SetCookie sites. So each hostname authenticates separately, and silently after the first login.

Three further cookies exist that are not sessions, and a complete inventory matters when reasoning about what a browser carries:

CookiePurposeAttributes
shc_oidc_stategate CSRF statePath=/, Lax, Max-Age=300 (main.go:51, 311-318)
shc_launcher_statelauncher CSRF statePath=/.shc/launcher/, None, Max-Age=300 (launcher.go:145, 561-569)
shc_id_tokenlogout id_token_hintPath=/api/auth/oidc, set at callback (main.go:81-87, 505-514)

The naming trap. What SHC calls “auto-redirect” is not IdP-initiated. It is SP-initiated with the click removed. The user still starts at the app; something bounces them onward before they see a button. True IdP-initiated starts at Keycloak and is a different flow with different security properties.

A: True IdP-initiated SAML · not implemented

Section titled “A: True IdP-initiated SAML · not implemented”

The flow starts at Keycloak, which pushes an unsolicited assertion into the app’s ACS URL. The app never sent an AuthnRequest, so there is no InResponseTo to match: no state, no nonce, nothing to bind the response to. That removes the standard replay and CSRF protections, which is why many SPs disable it outright.

Keycloak supports this per-client via an IdP Initiated SSO URL Name. Nothing in the repo sets one; ce/modules/keycloak/saml.socket.yaml:267-294 mints SAML clients with ACS/SLO/attributes and no such key, and no idpInitiatedSsoUrlName appears anywhere in either tree. The only related string is CISO Assistant’s reject_idp_initiated_sso: True, which is consumer-side refusal.

OIDC has no unsolicited push. The IdP links to the app’s initiate_login_uri and the app then drives an ordinary SP-initiated flow with full state and nonce, so it keeps every protection A gives up. Not wired here, and it is the safe way to build an IdP-side app list if one is ever wanted.

C: SP-initiated with a button · the default

Section titled “C: SP-initiated with a button · the default”

The user starts at the app, sees its login page, clicks “Log in with Keycloak”. This is the majority of the fleet.

Same flow as C; the app skips rendering its own login page, by one of three knobs (server 302, auto-submitting form, or client-side JS). Two of the three are invisible to curl. The app is still the initiating party; nothing about this is IdP-initiated.

Traefik 302s before the app is contacted (static form) or reads the rendered SSO button and 302s to its href (selector form). The app still runs the OIDC exchange; Traefik never holds a token here, it only redirects. That is what makes it composable with an app’s own SSO.

Do not confuse E with the gate. The gate (flow 3) authenticates: it holds a cookie and a token and decides whether the request may proceed. E only redirects; it holds nothing and decides nothing.

PathStarts atWho initiatesRemoves the clickHere?
A: SAML unsolicitedKeycloakIdPn/ano
B: initiate_login_uriKeycloakIdP links, app initiatesn/ano
C: buttonthe appappnomost of the fleet
D: app knobthe appappapp does4 hosts measured
E: edge rulethe appapp (proxy nudges)Traefik does★ 6 apps declare one: see §8

C, D and E produce the same app session by the same OIDC exchange. They differ only in who removes the click, which is why they mix freely across the fleet, and why auto-redirect is a UX feature, not an authentication mechanism.


Traefik proxies; Keycloak is never involved. Zero trips, zero prompts, zero cookies.

The app needs no login and the menu still appears, because the launcher authenticates independently of the app. The bootstrap XHR to /.shc/launcher/apps 401s, a hidden iframe hits /.shc/launcher/start, which 302s to Keycloak with prompt=none (launcher.go:571-583). With an SSO cookie present the code returns immediately and /.shc/launcher/callback mints shc_launcher; without one, Keycloak answers login_required and the launcher renders nothing (launcher.go:606-615). It never forces a login.

This is the case that shows the menu is orthogonal to app authentication: a wiki anyone can read still gets a menu, if you have a Keycloak session.

The app owns the whole flow: GitLab, Nextcloud, AFFiNE, Frappe. One Keycloak trip, one prompt, two sessions. Auto-redirect, where armed, only removes the click at the “send to login” step; it changes nothing else.

The gate decides before the app is contacted: how an app that cannot do SSO gets it. No shc_access_token → 302 to Keycloak with client_id=shc-forward-auth → login → /.shc/auth/callback (main.go:210) → server-side exchange → cookie set → retry allowed.

The gate already distinguishes browsers from API clients. With no credentials it keys on the Accept header: text/html gets a 302, anything else gets a bare 401 (main.go:265-269, wantsHTML at main.go:1003-1005). Scripts get a clean refusal, not a login page. Measured on the wire against agents.corp.bitspur.com, and it matches the code exactly.

★ The artifact claimed the launcher “never reads shc_access_token”, and therefore that a gated app costs two Keycloak trips. The first half is wrong. menuCredentialOf (traefik/plugin/menu.go:485-495) reads Authorization and the gate cookie:

func menuCredentialOf(r *http.Request) menuCredential {
var c menuCredential
if r == nil {
return c
}
c.authz = strings.TrimSpace(r.Header.Get("Authorization"))
if ck, err := r.Cookie(gateSessionCookie); err == nil {
c.cookie = strings.TrimSpace(ck.Value)
}
return c
}

serveLauncherApps only falls back to the shc_launcher handle when that credential is empty (launcher.go:390-400). The accurate statement is the one the code itself makes: the launcher does not mint shc_access_token, deliberately, because that cookie is SameSite=Lax and re-minting it (or widening it to SameSite=None so it survives the frame) “would weaken the CSRF posture of every gated app on the estate to make a launcher work” (launcher.go:71-74).

The architectural point the artifact was making (the launcher does not depend on the gate, which is what lets it work on ungated apps) survives intact. The mechanism stated for it does not.

Consequence, and it is unverified. shc_access_token is Path=/ and the /apps XHR is same-origin, so on a gated app the gate cookie should reach the launcher and satisfy it on the first call: no iframe, no second Keycloak trip. That makes the artifact’s “2 Keycloak trips, 3 sessions” for this flow likely wrong. It needs a browser measurement before either number is trusted; a curl cannot settle it, for the reason in Axis 2.

Two trips, one prompt, but the first belongs to the app, not to SHC. This is GitLab, Nextcloud, AFFiNE and Frappe. Round 2 is silent because round 1 already created the Keycloak SSO cookie; on a fresh browser the ordering is what makes it invisible.

Log in with a local app password and you get no menu. The launcher keys on the Keycloak session, not the app’s. A local login creates one and not the other, so prompt=none answers login_required and the menu renders nothing.

Three trips, and it breaks: the app’s own OIDC callback is itself behind the gate, so it is intercepted before the app can finish. Wasteful, fragile (the callback needs a per-app exclusion; forgetting it is a silent login loop), and it leaves four sessions with four lifetimes and no shared termination.

This is why GitLab, Nextcloud and AFFiNE are ungated: mechanics, not preference. The rationale is stated in-tree (apps/monitoring/superset/app.yaml:24-28):

# Access posture: NOT forward-auth gated (the default `access: open`).
# Superset carries its own auth end to end (flask-appbuilder AUTH_DB out of
# the box, AUTH_OAUTH against Keycloak once `-i oidc=<stack>` is attached)
# and the gate would 401 its /api/v1 surface and break the OAuth callback
# round-trip. Same posture as huly/gitea: apps with native SSO stay ungated.

The callback carve-out that prevents the loop where gating is used is at ce/modules/app/inject_traefik.go:101-104. For affine-rs the cost is measured rather than argued: every WebSocket upgrade credential through a gated route returned 401, and the failure is silent; the app loads, signs in, renders, and never syncs (proposal §affine-rs).

Edge static: a router rule keyed on the request path. Cheap, but it must know the path in advance (ce/modules/app/sso_redirect.go:471-478):

rule := "Host(`" + rt.Host + "`) && PathRegexp(`" + pattern + "`)" +
ssoNavigationMatchers() +
" && !Query(`" + bypass + "`,`false`)" +
excludeQueryMatchers(decl.ExcludeQuery)

The 302 itself comes from the SHC plugin since ruling S11 (traefik/plugin/ssoredirect.go, config key ssoRedirect, rendered by ce/modules/auth/launcher.go SSORedirectMiddleware): the rule carries no cookie term, and the loop guard is the selector flavour’s bounce counter, the shared shc_ssosel cookie, cap 3 per 90 s window, so a post-logout return trip still redirects while a real loop terminates in the app’s own rendered login form. The 10-second shc_ssoredir presence cookie (and the Set-Cookie middleware whose ordering used to be load-bearing) is retired: presence-suppression could not tell a loop from a return trip.

Edge selector: the plugin buffers the response and finds the SSO button, keying on the page rather than the path. It covers every login shape and self-limits by construction: an authenticated page has no SSO button, so nothing fires and no session inspection is needed (ssoselect.go:322-341). A miss serves the page byte-identically. It cannot see a button rendered client-side.

The bypass is ?sso=false, the shipped default (sso_redirect.go:69-73), guarded by TestTheBypassStillReachesTheLocalLoginForm. Every armed app must have it exercised and proven to reach a real login form first.

Three apps must not be armed, each for a measured reason:

AppWhyEvidence
SonarQubeRoutes ordinary 403s back through the login path with a query key the bypass cannot carve out: ERR_TOO_MANY_REDIRECTS in normal multi-user use. And no SAML SLO, so logout re-enters.apps/devops/sonarqube/app.yaml:76-101; proposal checks 5 and 6
affine / affine-rsZero password accounts and no mailer, so ?sso=false opens onto a page where no local method can succeed (bitspur 14 accounts / 0 with a password).apps/collaboration/affine-rs/vars.yaml:97-104
wazuhThe setting deletes the password form outright, including for the indexer admin: no local-admin escape hatch.apps/security/wazuh/app.yaml:51; compose.yaml:537-546

★ The artifact concluded “0 edge rules armed” and “the edge selector is written, shipped, and enabled nowhere.” Both are contradicted by the tree and by same-day measurements recorded in it.

Six apps declare sso_redirect::

AppFormDeclaration
kuttstaticapps/devops/kutt/app.yaml
windmillstaticapps/devops/windmill/app.yaml
hulystaticapps/business/huly/app.yaml
affinestaticapps/collaboration/affine/app.yaml
affine-rsstaticapps/collaboration/affine-rs/app.yaml
frappeselectorapps/devops/frappe/app.yaml: sso_selector: "a.btn-keycloak"

Frappe is the selector’s catalogue consumer, and it needed the selector specifically: its SSO href carries a single-use per-render state, so no static URL can express it.

Live-estate evidence that rules are armed, all from 2026-08-10:

  • apps/collaboration/affine-rs/vars.yaml:97-99: “app.yaml declares sso_redirect:, and it is ARMED on both estates today, so a logged-out browser is sent straight to Keycloak.”
  • The proposal’s fleet path table records affine/affine-rs /sign-in/ and /signIn “both measured, both 302”; windmill’s /user/login/ “evaded the rule on BOTH estates”; a rule must exist to be evaded.
  • Frappe on hq.corp.bitspur.com: /, /index, /index.html and /login/ all 200 with the login card; only /login 302s to Keycloak.

Why the artifact missed all of it. Its sweep probed each host’s root with a browser-shaped request. An edge rule anchored to a login path is structurally invisible to a root probe: the same “the probe decides what you can see” failure the artifact documents in Axis 2 for auto-submit forms and client-side JS, applied to app-side mechanisms but not to its own. The proposal states the trap in as many words: an anonymous curl -L can never witness AFFiNE auto-redirecting, and a curl trace here “should be read as no evidence, never as not working.”

The same root-probe limit produced a second misattribution: erp/hq were recorded as “server 302 (Frappe)”. A 302 on /login only, while /login/ and / return 200 with the same card, is the signature of a path-anchored edge rule, not app behaviour. (Frappe has since moved to the selector form with a broadened login_path, precisely because / is where operators actually land.)

What survives. The redirect sweep’s app-side findings stand: Frappe redirects, GitLab redirects browser-only via auto-submitting form, grc lands on its own /login with nothing armed, and quality (SonarQube) is refused deliberately. The count “4 of 25 redirect” is a correct statement about host roots, not about arming.

★ The artifact’s logout section was the strongest claim in it and is now the most wrong. It failed twice, in two different ways.

It was already wrong when written. “Zero occurrences of protocol/openid-connect/logout anywhere in the platform”; the pre-fix tree carried four, dating from 2026-08-07:

apps/media/wordpress/oidc.plug.yaml
apps/collaboration/nextcloud/oidc.plug.yaml
apps/collaboration/matrix/compose.yaml
apps/security/wazuh/compose.yaml

(verified with git grep at fd56361ca, the commit before the logout work). The grep behind the claim covered the platform Go code, not the app catalogue, while the sentence claimed “anywhere in the platform”: a corpus narrower than the claim made for it.

Then it was overtaken the same day. Platform logout landed in v0.0.49, 2026-08-10:

  • RP-initiated logout: logoutPath = "/api/auth/oidc/logout", mounted at forward-auth/cmd/forward-auth/main.go:216, handler at 530-612 (commit 66562f076, titled “the sidecar had no logout route and threw away the ID token”).
  • The ID token is now retained in shc_id_token and supplied as id_token_hint at logout (main.go:505-514, 605-607), so Keycloak ends the session without an interstitial.
  • Back-channel logout receiver at BackchannelLogoutPath = "/api/auth/backchannel-logout" (ce/modules/auth/backchannel_logout.go:50-55, commit c910379), registered on the shc-forward-auth client via backchannel.logout.url (ce/modules/auth/forward_auth_client.go:221-235).
  • A session-revocation ledger consulted by both places that admit a bearer (ce/modules/auth/session_revocation.go; enforced at service.go:411-412, 609-611).

So “the gate has no logout route at all and never parses the ID token, so it could not supply an id_token_hint” is false as of today, and “revoking access has no reliable mechanism” is the specific problem v0.0.49 was written to solve.

What the artifact got right, and what still stands:

  • The four-hour figure is real: DefaultAccessTokenLifespanSeconds = 14400 (ce/modules/auth/state.go:50). Before the revocation ledger, “revoke this person now” did mean “in up to four hours”; the CHANGELOG says so in the same words.
  • Six apps self-logout matches the in-tree count (main.go:211-216). Apps with app-native end-session wiring: librechat, nextcloud, wordpress, wazuh, matrix, immich. Apps that explicitly do not end the IdP session, each documented in its own app.yaml: frappe, gitlab, huly, ciso-assistant, defectdojo-classic.
  • The diagnosis that a logout loop makes logout impossible rather than merely incomplete, when auto-redirect is armed, is correct and is why author check 5 exists.

Two gaps remain open, and they are not what the artifact named:

  1. The in-plugin gate has no logout. traefik/plugin/auth.go is a second gate implementation; it omits the ID token entirely (auth.go:280-284) and mounts no logout handler. Only the sidecar path has one.
  2. The revocation ledger is in memory. Per the v0.0.49 CHANGELOG: “the logout revocation ledger is in memory.” A daemon restart is a revocation amnesty.

Three login shapes: why one rule cannot cover them

Section titled “Three login shapes: why one rule cannot cover them”
ShapeExampleWhy a path rule misses it
pathgrc → /login?next=/Works, if a rule is armed
inline at rootFrappe renders the card on //login redirects correctly; the user lands on / and never reaches it
query parametermailcow → /?iam_sso=1The login page is /. There is no path to anchor to
SPA-renderedSonarQube ships zero <a> and <form> tagsNothing in the served HTML to select

Whether / is a login page can be runtime data in the app’s own database rather than a property of the app. The same Frappe image, the same app.yaml, measured across three live sites: two serve the login card on / (Website Settings.home_page unset), and a third serves a 339 KiB public marketing page. A static router matching / would 302 every anonymous visitor of that third site into Keycloak and destroy the public website. That is the case only the selector form can serve; it asks the page that was actually rendered.


No PKCE and no nonce, anywhere. Neither the launcher (launcher.go:571-583, 688-697) nor the gate (main.go:302-308, 443-451) sends code_challenge or nonce. Confirmed at both implementations.

redirectUris: ["*"] on the gate’s client: ce/modules/auth/forward_auth_client.go:149-151. ★ The artifact stated this as an estate-wide property; it is specific to shc-forward-auth. Per-app OIDC clients use plug-declared URIs, and ce/modules/keycloak/oidc.socket.yaml:137-146 refuses a bare * for new plugs.

One shared client secret for shc-forward-auth, resolved once at global scope (ce/modules/auth/types.go:113-120; ce/modules/traefik/vars.yaml:131). ★ Again specific to that client, per-integration clients mint their own, and the SAML socket has no shared secret at all (ce/modules/keycloak/saml.socket.yaml:26).

★ “Already disclosed twice” is uncited. No incident, handoff or decision record in either repo documents a disclosure of forward_auth_client_secret. The only in-tree reference is docs/reviews/2026-08-05-live-proofs.md:165, which lists it as CLEAN in a scan. Either the incident is recorded somewhere outside the repo and should be linked here, or the claim should be dropped; an uncited breach assertion in a reference page is worse than no assertion, because it cannot be acted on or refuted.

aud is checked after the code is redeemed, and the check lives in the daemon, not at the edge. Neither the gate callback (main.go:443-498) nor the plugin gate (auth.go:593-641) validates audience before setting the session cookie; EnforceAudience runs inside ValidateBearer (ce/modules/auth/service.go:385-390 and the JWKS fast path at 592-595), which the gate reaches by proxying the bearer to /api/auth/forward-auth. The artifact’s timing claim is correct; the scope is broader than “the daemon’s own bearer path”, since the CLI and API paths validate through the same function.

A SAML login yields a Keycloak session an OIDC prompt=none check honours, recorded as measured on the wire. No test asserts it, and no SAML-to-OIDC assertion exists in either tree. Unguarded.


Claim classHow it was checked
Route registrations, cookie attributes, rule construction, middleware orderRead from source, cited above
Arming stateRepo declarations + live measurements recorded in-tree; not re-measured against the estates from this checkout
Redirect behaviour of individual hostsLive-estate measurements taken 2026-08-10, unverifiable from a code read
Flow 4’s trip countUnverified: needs a browser, not a curl
Secret disclosure historyUnsupported in-tree