2026-08-26 · run 2026-08-26-starttls-1389

StartTLS on 1389: works when trusted, and fails *silently* (unlike LDAPS)

Why this run existed

Run D (2026-08-26-runD-ldaps-starttls) covered implicit LDAPS on 1636 and left three rows unchecked: StartTLS on 1389, hostname-verification failures, and expired certificates. This run closes all three, and the first one changes what Run D concluded about the failure signature.

Environment

Result — four legs, one sync each

Full sync via POST /admin/realms/lab/user-storage/{id}/sync?action=triggerFullSync.

Findings

1. StartTLS failure is silent; LDAPS failure is loud

Run D established that an untrusted certificate on LDAPS (1636) fails with {"errorMessage":"SocketReset"} and HTTP 400 — loud, and the word "certificate" never appears. On StartTLS the equivalent failures all return HTTP 200 with a body that looks like a successful, empty sync:

{"ignored":false,"added":0,"updated":0,"removed":0,"failed":0,
 "status":"0 imported users, 0 updated users"}

The real cause is only in the Keycloak log, as a full stack trace. An operator (or monitoring integration) that checks the HTTP code — or only greps for SocketReset/errorMessage — sees a successful sync that imported nothing, and reaches for "is the directory empty? is the DN wrong?" instead of "is the certificate trusted?". The same misdirection Run D warned about for LDAPS is worse on StartTLS, because there is no error at all at the API level.

The one correct signal in the response is the count: added:0 where you expect users. The lesson for the runbook is check the imported count, not the status code — on StartTLS, "0 imported" is a failure signal, not a success.

2. Keycloak enforces hostname verification on LDAP TLS

A trusted CA with a cert whose SAN is DNS:wronghost fails with SSLPeerUnverifiedException / No subject alternative DNS name matching ldap found. Keycloak does not default to "trust everything, skip hostname" on LDAP connections — the HostnameChecker runs, and a SAN that does not match the connection hostname is a hard failure (silent at the API, loud in the log). This means a directory cert issued for the wrong name — or a wildcard that does not cover the host — breaks federation exactly like an untrusted CA.

3. StartTLS itself works and survives, matching LDAPS

With the CA trusted and the SAN matching, StartTLS on 1389 imports all three users — no functional difference from implicit LDAPS. The mode is not the problem; the failure signature is.

Verification