Skip to content
SHC Docs

LDAP as the universal SSO fallback

Status: built; this note is still its only description. The socket is addons-overlay/keycloak/ldap.socket.yaml. The owner policy is taken as given, not re-litigated: every app gets SSO, in precedence OIDC → SAML → LDAP by what the app’s edition supports; LDAP is the fallback for community editions that support neither OIDC nor SAML, and the estate needs an LDAP directory apps can bind to, federated with Keycloak. This document decides where that directory comes from and, the load-bearing question, which direction keeps Keycloak the source of truth.

Recommendation in one line: the directory the estate needs already exists (the MyVD LDAP face bundled in the pinned system-keycloak image, currently hard-disabled by compose env) and the right move is to finish productizing it as the bundled keycloak’s ldap socket (work already in flight on a ce wip branch), not to package an OpenLDAP/lldap app. No new apps/ package is proposed, and §6 says why packaging one here would be the wrong call.


Every claim in this section was verified against the named file or the cited external source, not inferred.

1.1 The identity sockets the bundled keycloak already serves

Section titled “1.1 The identity sockets the bundled keycloak already serves”
  • builtin/keycloak/oidc.socket.yaml (ce main): the OIDC socket (renamed from sso, ce 1c8aba62), consumed by most of the catalog’s oidc.plug.yaml files.
  • builtin/keycloak/saml.socket.yaml (ce main): the SAML socket; mautic and sonarqube consume it (apps/mautic/saml.plug.yaml, apps/sonarqube/saml.plug.yaml).
  • apps/external-oidc/: the BYO-IdP front. The EE identity-edge gate (modules/app/sso_gate.go, mirroring ce’s) rules only on edges to an external provider; bundled-keycloak edges never gate, and the gate is scoped to SocketOIDC || SocketSAML in ce’s integration_service.go.

So OIDC and SAML rungs of the precedence ladder are live. The LDAP rung is the gap.

1.2 The pinned system-keycloak image already carries an LDAP server

Section titled “1.2 The pinned system-keycloak image already carries an LDAP server”

keycloak/docker/Dockerfile (this repo) builds the SHC keycloak image FROM the pinned multiplatform.one bundle digest (sha256:6ed21b40…) and closes with:

Everything else, entrypoint, exposed ports, the MyVD/vKDC faces SHC hard-disables via compose env, is inherited unchanged from the base.

builtin/keycloak/compose.yaml on ce main sets ENABLE_MYVD: "false" and ENABLE_VKDC: "false", and builtin/keycloak/vars.yaml budgets heap “headroom for the bundled MyVD/vKDC”. In other words: every estate is already shipping an LDAP face inside the system keycloak container, switched off.

MyVD (MyVirtualDirectory) with first-party inserts, maintained in the keycloak distribution repo (~/selfhosted-cloud/keycloak, myvd/ module, ~2.6k lines of Java):

  • KeycloakInsert: projects every realm as ou=<realm>,<baseDn> with ou=people / ou=groups / ou=sudoers subtrees and full POSIX attributes, generated from Keycloak’s admin API on every search. A simple bind on uid=<user>,ou=people,ou=<realm>,<base> is validated by running a password grant against Keycloak’s token endpoint for that realm, a bind passthrough. No password is stored anywhere but Keycloak.
  • AdminBindInsert: exactly one service DN (LDAP_ADMIN_DN), validated as a password grant for the master realm admin.
  • PasswordModifyInsert: RFC 3062 Password Modify extended op, round-trips a password change into Keycloak.
  • RootDseSchemaInsert: root DSE + subschema.

The distribution repo’s e2e suite (bats) covers the full hybrid Linux-login flow, SSSD identity from MyVD over LDAP, auth via Kerberos, driven through the real PAM stack with pamtester, 31/31 at the last recorded run.

1.4 The productization is already in flight

Section titled “1.4 The productization is already in flight”

ce branch wip/redactor-batch-checkpoint (not on ce main) carries:

  • builtin/keycloak/vars.yaml: enableLdap (default false), ldapBaseDn (dc=shc,dc=internal), keystore secret; measured costs documented (keycloak ~945M RSS, MyVD ~330M, vKDC ~111M on the pinned digest).
  • builtin/keycloak/compose.yaml: ENABLE_MYVD gated on enableLdap, 389/636 exposed on the provider network only, memory limit stepped 3G→4G when a face is on.
  • builtin/keycloak/ldap.socket.yaml: a complete socket: endpoint + DIT-shape data, two-step discovery probe (config check fails fast, readiness check retries), a realm-projection integration job, and an honest header documenting the three properties a consumer must design around (read-only projection; anonymous search with no useful bind to hand out; every realm projected, reachability as the boundary).

No consumer ldap.plug.yaml exists anywhere in apps/ yet, on any branch.


2. Architecture (a): Keycloak AS the LDAP server

Section titled “2. Architecture (a): Keycloak AS the LDAP server”

Keycloak does not serve LDAP. There is no LDAP listener, no “LDAP provider” in the authentik outpost sense, and no supported extension point that turns the Quarkus runtime into a directory server. authentik ships exactly this feature (its LDAP provider/outpost); Keycloak has no equivalent (authentik docs).

Verdict: does not exist as a Keycloak feature. The estate’s bundled MyVD face is the closest realization of (a)‘s operational shape, the keycloak stack answers on 389, but it is a supervised sibling process in the same container, which is architecture (c-i) below, not a Keycloak capability.


3. Architecture (b): OpenLDAP as the directory of record

Section titled “3. Architecture (b): OpenLDAP as the directory of record”

The classic layout: OpenLDAP holds users and credentials; Keycloak attaches LDAP user federation and fronts it for OIDC/SAML; LDAP-only apps bind directly to OpenLDAP.

3.1 What Keycloak’s LDAP federation actually does (official docs)

Section titled “3.1 What Keycloak’s LDAP federation actually does (official docs)”

Per the Keycloak server admin guide:

  • Federation is designed to import from LDAP into Keycloak.
  • WRITABLE edit mode synchronizes username/email/profile and password changes back to LDAP; password writeback sends the plaintext over the LDAP connection for the LDAP server to hash.
  • Sync Registrations pushes users newly created through Keycloak into LDAP.
  • There is no mechanism that exports pre-existing realm-local users into LDAP. The docs describe importing only; “sync registrations” covers new users by its own wording. (Confirmed by documented absence, not an explicit statement.)

3.2 What that means for a Keycloak-first estate

Section titled “3.2 What that means for a Keycloak-first estate”

The owner’s estates are Keycloak-first: users live in Keycloak realms today, one realm per tenant.

  1. The credential source of truth moves. Under WRITABLE federation the authoritative password hash lives in OpenLDAP; Keycloak becomes a cache plus management plane. That is the real trade-off in this option and it is permanent.
  2. Existing users strand. Every user already in a realm keeps a realm-local password that never reaches LDAP. Getting them into the directory means per-user password resets (hashes cannot cross) or accepting a split estate where old users cannot use LDAP-only apps.
  3. Per-tenant fan-out. Realm-per-tenant means one federation component per realm, one subtree (or one directory) per tenant, and teardown logic for both, a second identity object model to operate next to the one that already works.
  4. The image supply is bad. Verified 2026-08-06:
    • bitnami/openldap is dead as a pin: Broadcom moved all versioned Bitnami images to docker.io/bitnamilegacy effective 2025-08-28 (“no further updates… temporary migration purposes only”); Docker Hub returns zero tags for bitnami/openldap (bitnami/containers#83267).
    • osixia/openldap is abandoned: last stable 1.5.0 ships OpenLDAP 2.4.57 (Feb 2021) (releases).
    • The one maintained option is symas/openldap (Symas/containers); Symas commercially maintains OpenLDAP itself. Viable, but it does not repair points 1–3.

lldap is its own credential store (SQLite default) and is explicit about direction in its Keycloak guide: “LLDAP is read-only … you should create the user from LLDAP, and it will appear in KeyCloak.” READ_ONLY federation works; WRITABLE (sync registrations, LDAP ADD) does not. So lldap moves not just the credential store but the user-creation surface out of Keycloak; the inversion is total.

Verdict on (b): real, production-proven, and the wrong direction. It keeps Keycloak as a login front while quietly relocating the thing the estate actually is, the user store. Rejected as the universal fallback. It remains the honest choice only for an estate that wants an LDAP-native source of truth, which this one does not.


4. Architecture (c): an LDAP facade that authenticates against Keycloak

Section titled “4. Architecture (c): an LDAP facade that authenticates against Keycloak”

The direction that keeps Keycloak the sole source of truth: something speaks LDAP on the front and validates binds against Keycloak on the back.

4.1 The off-the-shelf field (verified 2026-08-06)

Section titled “4.1 The off-the-shelf field (verified 2026-08-06)”
ProjectWhat it isKeycloak bind passthrough?
glauth (v2.5.2, active)Standalone LDAP serverNo. Backends: config file, ownCloud, LDAP proxy, SQL plugins (docs). No OIDC/Keycloak/HTTP backend exists, official or third-party.
lldap (active)Own-store LDAP serverNo. Cannot proxy auth to an external IdP (§3.3).
please-openit/LDAP-Bind-Proxy (pushed Jan 2026)Python/ldaptor LDAP front translating binds to password-grant calls against KeycloakYes, the one true bind-passthrough in the wild. Young and small (29 stars); searches serve cached token claims, not a full directory projection.
alan-turing-institute/apricot (0.1.2, 2025-07)OIDC→LDAP mirror with a Keycloak backendNo, read-only directory mirror; bind-password passthrough is not part of its model.
authentik LDAP outpostThe feature done rightauthentik-only; adopting it means replacing Keycloak.

Nothing off the shelf is both maintained and complete enough to bet the fallback rung on.

4.2 The in-house facade (c-i): the bundled MyVD face

Section titled “4.2 The in-house facade (c-i): the bundled MyVD face”

Everything §4.1 fails to deliver already exists in the estate’s own image (§1.2–1.4): a full directory projection (POSIX attributes, groups, sudoers; SSSD-grade, not just app binds), bind passthrough via password grant, RFC 3062 password-change round-trip, live e2e coverage, and a written socket with discovery probes. Keycloak remains the only credential store; the projection is regenerated from Keycloak on every search, so there is no sync job, no drift, and nothing to migrate.

Consequences a consumer must design around (all inherent to any LDAP facade, not MyVD-specific, except where noted):

  • A bind is a password. Users whose Keycloak login is OTP-gated, passwordless, or brokered from an upstream IdP cannot LDAP-bind; an LDAP simple bind carries exactly one credential. This bounds what the LDAP rung can ever do, under every architecture in this document.
  • Read-only identity. Users and groups are created in Keycloak (or via the keycloakAdmin surface), never over LDAP. Correct for an auth fallback; disqualifying only for an app that must write directory entries, which the fallback policy does not require.
  • No per-consumer bind at the current image. MyVD’s listener accepts anonymous search, and the only service DN it knows maps to the master admin credential, so the in-flight socket publishes bindDn empty and leans on network reachability as the boundary. Scoped per-consumer service binds need a new MyVD insert, an image change, flagged as follow-up work in the distribution repo, not a catalog concern.
  • Availability couples to keycloak. When keycloak is down, LDAP binds fail, the same blast radius every OIDC consumer already has, so this is not a regression, but it is worth stating.
  • Cost. ~330M RSS inside the keycloak container when enableLdap is on; off by default.

4.3 Architecture (c-ii): an LDAP-listener SPI inside keycloak/spi

Section titled “4.3 Architecture (c-ii): an LDAP-listener SPI inside keycloak/spi”

Assessed for feasibility only, as a third option: embed an LDAP listener (e.g. the UnboundID SDK’s) in a Keycloak extension inside this repo’s keycloak/spi/, validating binds in-process against the credential manager. Feasible in principle, and strictly dominated here. It would re-implement ~2.6k lines of working, tested insert code inside a Quarkus runtime that owns neither the port lifecycle nor the listener’s threading; it couples LDAP availability to Keycloak’s own deploy/augmentation cycle even harder than the sibling process does; and the one thing an in-process validator could do differently, check the stored hash directly, sidestepping the token endpoint, is a policy bypass (it would authenticate users whose realm requires OTP), which is worse, not better. Rejected.

4.4 OpenLDAP-with-delegated-bind, for completeness

Section titled “4.4 OpenLDAP-with-delegated-bind, for completeness”

OpenLDAP can delegate binds outward; slapd-sock can forward BIND to an external program (man page), and {SASL} passthrough delegates verification to saslauthd, whose backends are PAM/Kerberos/IMAP; no HTTP/OIDC (admin guide). Either path to Keycloak is bespoke glue with no upstream. Running a full slapd to host a hand-written passthrough shim, when a tested facade already ships in the estate’s own image, needs no further argument.


Credential storeUser creationExisting realm usersSync machinery
(b) OpenLDAP + WRITABLE federationmoves to LDAPKeycloak (synced in)stranded (no export)federation component per realm
(b) lldap + READ_ONLY federationmoves to lldapmoves to lldapstrandedimport sync
(c-i) MyVD facestays in Keycloakstays in Keycloakjust worknone: projection, not sync

Only the facade direction keeps Keycloak the source of truth. Keycloak’s LDAP federation imports; it does not export an existing estate, and no configuration makes it. Any design that starts “and then Keycloak federates from the new directory” has already moved the estate’s center of gravity; that is the trade-off, stated plainly, and this estate should not take it.


  1. Adopt the bundled MyVD face as the LDAP universal fallback. Concretely: land the in-flight ce work (enableLdap + ldapBaseDn vars, gated compose env, builtin/keycloak/ldap.socket.yaml). That landing is the owner’s call under the ce landing doctrine (direct to ce main, pin bump carries regenerated docs), which is why this proposal stops at the design and packages nothing.
  2. Do not package an OpenLDAP or lldap app. Not as the fallback (wrong direction, §3), and not “just in case”; a directory-of-record app in the catalog next to a facade socket is an invitation to split the estate’s identity, and the maintained-image situation (§3.2.4) makes it a poor citizen besides. If a customer estate genuinely needs an LDAP-native store, symas/openldap is the image to package that day, as its own decision.
  3. Consumer work, once the socket lands: per-app ldap.plug.yaml files in apps/, following the recipe the socket header already documents (realm in plug data; realm-scoped search DNs assembled in compose from integrations.ldap.socket.* parts). First candidates: the community editions in the catalog whose builds gate out both OIDC and SAML.
  4. Image follow-ups (distribution repo, not this one): per-consumer scoped service-bind DNs (new MyVD insert); an LDAPS keypair whose SANs cover the socket hostname so consumers can verify instead of pinning.
  5. Licensing posture: the identity-edge gate rules oidc/saml edges to external providers; an ldap edge to the bundled keycloak is an ungated CE capability, consistent with “bundled-keycloak edges never gate”. If an external-ldap app ever appears, whether it joins the EE sso entitlement is a decision to make then; the gate’s socket scope would need widening, and that is deliberate today, not an oversight.

What this recommendation costs, honestly: the LDAP rung inherits every facade limit in §4.2: OTP/passwordless/brokered users cannot bind anywhere LDAP is the only door, per-consumer binds wait on an image change, and LDAP auth is down when keycloak is down. Each of those except the second is intrinsic to LDAP-as-fallback under any architecture; the second has a named owner and a named location.


Verified against files in this estate: keycloak/docker/Dockerfile (base digest, MyVD/vKDC inheritance note); ce main builtin/keycloak/{compose.yaml,vars.yaml,oidc.socket.yaml,saml.socket.yaml} (ENABLE_MYVD=false, heap note, socket inventory); ce wip/redactor-batch-checkpoint builtin/keycloak/{ldap.socket.yaml,vars.yaml,compose.yaml} (the in-flight productization); distribution repo myvd/src/main/java (KeycloakInsert bind = token-endpoint password grant; AdminBindInsert; PasswordModifyInsert) and its README (component map, e2e matrix); modules/app/sso_gate.go (gate scope); apps/ sweep (no ldap.plug.yaml exists; mautic/sonarqube consume saml).

Verified against live external sources (2026-08-06): Keycloak federation semantics (official server admin guide); glauth backend list; lldap Keycloak guide; please-openit/LDAP-Bind-Proxy and apricot repos; authentik LDAP provider docs; Bitnami catalog freeze (bitnami/containers#83267); osixia release history; Symas container images; OpenLDAP slapd-sock man page and admin-guide SASL passthrough section.

Assumed, not independently re-proven here: the distribution repo’s “31/31 passing” e2e claim and its measured RSS figures (taken from that repo’s README and the in-flight ce comments, which state they were measured against the pinned digest); that the mp1 base digest’s MyVD build matches the distribution repo’s current source (the ce wip socket says its claims were verified against the pinned digest by hand, and this document trusts that statement).