Skip to content
SHC Docs

SSO coverage policy

The policy is one sentence: every app gets SSO. An estate’s identity lives in Keycloak, and an app whose sign-on does not resolve to that identity (one more password list, one more offboarding step) is a packaging defect, not a neutral default. The rest of this page is how that sentence is applied when apps and editions differ in what they can do.

Protocol preference is fixed, and each app takes the highest rung its edition supports:

  1. OIDC: the default. The Keycloak addon serves an oidc socket, and most of the catalog consumes it through a per-app oidc.plug.yaml: connect with -i oidc=<stack> and the socket’s job mints the client in the right realm before the app starts. See plugs & sockets for the mechanism.
  2. SAML: for apps whose edition gates out OIDC but carries SAML. The addon serves a saml socket; sonarqube and mautic consume it today. Certificate exchange replaces the shared secret: the plug reads the IdP’s signing certificate out of the realm descriptor at configure time.
  3. LDAP: the fallback for community editions that support neither. This rung is a design, not a shipped feature: the direction is recorded in the LDAP fallback proposal, which settles where the directory comes from (the bundled Keycloak’s currently-disabled LDAP face, productized as a socket) and which direction keeps Keycloak the source of truth. No ldap.plug.yaml exists in the catalog yet.

Estates that bring their own IdP front it through external-oidc instead of the addon; identity edges to an external provider are where edition entitlements apply, while edges to the bundled Keycloak never gate.

Coverage is not one UX. Four shapes satisfy the policy, in preference order, and an app should sit in the highest shape it can:

  1. Auto-redirect via a native knob. A logged-out browser is sent straight into the OIDC flow by the app itself: no app login page, no button. Many apps carry a knob for exactly this (GitLab, Immich, and Paperless among them, each with a documented local-login escape hatch). The audit of which apps have a knob, which have partial ones, and which verifiably have none lives in the SSO auto-redirect proposal; wiring the knobs behind one operator-facing flag is proposal-stage, so today this shape is configured per app.
  2. Auto-redirect via the SHC edge. For apps with no auth of their own, a gated install already behaves this way: the forward-auth gate redirects unauthenticated browsers to Keycloak. This is the gated-apps posture; its design center is apps without native SSO, and it must not front apps that have their own OIDC flow.
  3. Userless but gated. Apps with no user model at all (OpenHands is the example) get their entire access decision from the gate. Sign-on coverage here means reachability control, because that is all there is to control.
  4. The SSO button. The app’s own login page with a “sign in with SSO” option wired to Keycloak. The floor, not the goal: acceptable where a native auto-redirect knob does not exist at the pinned version, which the auto-redirect audit verified is a real class, not a configuration oversight.

Below all four is nothing acceptable: an app with local-only login and no gate does not meet the policy. It either gains a plug, gets gated, or its absence of SSO becomes a catalog decision documented in licensing postures; the DefectDojo split is what that looks like.

Two rules keep the policy honest where sign-on meets pricing:

  • EE-only SSO is packaged to work if licensed. When an upstream sells SSO in its paid edition, the catalog does not drop SSO from the app: the packaging carries the wiring so that an estate holding the vendor license gets working sign-on from the same install. What the packaging never does is defeat the vendor’s license enforcement; that line is stated in licensing postures.
  • Auth removal is not a substitute for SSO. Where a community edition has no SSO and no multi-user at any price, the answer is the gate (shape 2 or 3, via auth.disable where the app supports it), with per-person access and offboarding through Keycloak, without pretending the app has an identity model it lacks.

The plumbing behind the policy is spread across three places, each with its own page:

  • The sockets: the Keycloak addon’s oidc and saml sockets and the per-app plugs: plugs & sockets.
  • The gate: the forward-auth flow and its path exemptions: access control and gated apps.
  • The custom builds: where zero-touch SSO required baking a connector into the image (the Frappe image) or extending Keycloak itself: custom builds.