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.
The three axes
Section titled “The three axes”These are separate decisions. Most confusion about SHC auth comes from treating them as one. Any deployment is one choice from each.
Axis 1: who establishes identity
Section titled “Axis 1: who establishes identity”| Posture | Mechanism |
|---|---|
| App-native | The app runs its own OIDC or SAML flow; Traefik passes traffic through untouched. GitLab, Nextcloud, AFFiNE, Frappe. |
| Forward-auth gate | access: gated. The proxy authenticates before the app is contacted. Gives SSO to an app that cannot do it. |
| Launcher | The apps menu’s own silent check. Independent of both, deliberately, so it works on ungated apps. |
| None | Public. 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:
| App | Declaration |
|---|---|
| openreplay | apps/flagship/openreplay/app.yaml:40 |
| graphiti | apps/ai/graphiti/app.yaml:47 |
| agent-canvas | apps/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.
Axis 2: how the browser reaches the IdP
Section titled “Axis 2: how the browser reaches the IdP”Five mechanisms. Three are app-side, two are edge-side.
| Mechanism | Where | How it fires | Visible to curl? |
|---|---|---|---|
| server 302 | app | The app redirects to Keycloak itself | yes |
| auto-submit form | app | A hidden <form method=post> plus a script that submits it | no |
| client-side JS | app | An SPA calls location on mount | no |
| edge static | Traefik | Router rule → redirectRegex (ce/modules/app/sso_redirect.go:471) | yes |
| edge selector | plugin | Buffers 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.
Axis 3: four independent sessions
Section titled “Axis 3: four independent sessions”| Session | Scope | Meaning |
|---|---|---|
| Keycloak SSO | auth.corp.<estate> | The only one that means “who you are”. The launcher keys on this and nothing else. |
| App session | the app’s own cookie, own host | Only the app can validate it. |
shc_access_token | host-only, Path=/, SameSite=Lax | The gate’s cookie. Gated apps only. forward-auth/cmd/forward-auth/main.go:491-499. |
shc_launcher | host-only, Path=/.shc/launcher/, SameSite=None, 30 min | The 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:
| Cookie | Purpose | Attributes |
|---|---|---|
shc_oidc_state | gate CSRF state | Path=/, Lax, Max-Age=300 (main.go:51, 311-318) |
shc_launcher_state | launcher CSRF state | Path=/.shc/launcher/, None, Max-Age=300 (launcher.go:145, 561-569) |
shc_id_token | logout id_token_hint | Path=/api/auth/oidc, set at callback (main.go:81-87, 505-514) |
How a login begins: five entry paths
Section titled “How a login begins: five entry paths”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.
B: IdP-initiated OIDC · not implemented
Section titled “B: IdP-initiated OIDC · not implemented”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.
D: The app removes the click
Section titled “D: The app removes the click”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.
E: The proxy removes the click
Section titled “E: The proxy removes the click”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.
| Path | Starts at | Who initiates | Removes the click | Here? |
|---|---|---|---|---|
| A: SAML unsolicited | Keycloak | IdP | n/a | no |
B: initiate_login_uri | Keycloak | IdP links, app initiates | n/a | no |
| C: button | the app | app | no | most of the fleet |
| D: app knob | the app | app | app does | 4 hosts measured |
| E: edge rule | the app | app (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.
The eight flows
Section titled “The eight flows”1: Public
Section titled “1: Public”Traefik proxies; Keycloak is never involved. Zero trips, zero prompts, zero cookies.
1b: Public, with the menu
Section titled “1b: Public, with the menu”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.
2: App-native SSO
Section titled “2: App-native SSO”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.
3: Gated
Section titled “3: Gated”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.
4: Gated, with the menu
Section titled “4: Gated, with the menu”★ 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.
5: App-native SSO, with the menu
Section titled “5: App-native SSO, with the menu”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=noneanswerslogin_requiredand the menu renders nothing.
6: Gated and app-native SSO · avoid
Section titled “6: Gated and app-native SSO · avoid”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).
7: The two edge auto-redirect mechanisms
Section titled “7: The two edge auto-redirect mechanisms”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:
| App | Why | Evidence |
|---|---|---|
| SonarQube | Routes 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-rs | Zero 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 |
| wazuh | The 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 |
8: Arming state ★
Section titled “8: Arming state ★”★ 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::
| App | Form | Declaration |
|---|---|---|
| kutt | static | apps/devops/kutt/app.yaml |
| windmill | static | apps/devops/windmill/app.yaml |
| huly | static | apps/business/huly/app.yaml |
| affine | static | apps/collaboration/affine/app.yaml |
| affine-rs | static | apps/collaboration/affine-rs/app.yaml |
| frappe | selector | apps/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 declaressso_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.htmland/login/all 200 with the login card; only/login302s 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.
9: Logout ★
Section titled “9: Logout ★”★ 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.yamlapps/collaboration/nextcloud/oidc.plug.yamlapps/collaboration/matrix/compose.yamlapps/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 atforward-auth/cmd/forward-auth/main.go:216, handler at530-612(commit66562f076, titled “the sidecar had no logout route and threw away the ID token”). - The ID token is now retained in
shc_id_tokenand supplied asid_token_hintat 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, commitc910379), registered on theshc-forward-authclient viabackchannel.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 atservice.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 ownapp.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:
- The in-plugin gate has no logout.
traefik/plugin/auth.gois 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. - 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”| Shape | Example | Why a path rule misses it |
|---|---|---|
| path | grc → /login?next=/ | Works, if a rule is armed |
| inline at root | Frappe renders the card on / | /login redirects correctly; the user lands on / and never reaches it |
| query parameter | mailcow → /?iam_sso=1 | The login page is /. There is no path to anchor to |
| SPA-rendered | SonarQube ships zero <a> and <form> tags | Nothing 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.
Known gaps
Section titled “Known gaps”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.
Verification status
Section titled “Verification status”| Claim class | How it was checked |
|---|---|
| Route registrations, cookie attributes, rule construction, middleware order | Read from source, cited above |
| Arming state | Repo declarations + live measurements recorded in-tree; not re-measured against the estates from this checkout |
| Redirect behaviour of individual hosts | Live-estate measurements taken 2026-08-10, unverifiable from a code read |
| Flow 4’s trip count | Unverified: needs a browser, not a curl |
| Secret disclosure history | Unsupported in-tree |