Keycloak on Windows + LDAPS to FreeIPA

Run Keycloak on Windows 11 using bin\kc.bat and wire a User Federation provider to FreeIPA over LDAPS (636). Complete field values, Java truststore, Kerberos SSO, and the short list of errors that actually happen in practice.

Prereqs

• Windows 11 with local admin.
• Keycloak ZIP distribution extracted to C:\keycloak. This page uses Keycloak 26.x conventions; earlier versions need minor path changes but the federation steps are identical.
• A supported JDK for that Keycloak release (17 for 24.x, 21 for 26.x). Set JAVA_HOME to the JDK and add %JAVA_HOME%\bin to PATH.
• FreeIPA server (ipa.example.internal, realm EXAMPLE.INTERNAL) reachable on 636/TCP.
• A dedicated FreeIPA bind account for Keycloak (recommended) — see below.

Create a dedicated IPA bind account

Do not point Keycloak at cn=Directory Manager. Create a low-privilege account that can read users and groups:

# On the IPA server (or via /freeipa-cli-windows/)
ipa user-add keycloak-bind --first=Keycloak --last=Bind --random
ipa user-show keycloak-bind --all | grep -i 'Random password'

# Optional: add to a read-only helper group you maintain
ipa group-add-member ipausers --users=keycloak-bind

Record the password (Keycloak will store it in its own DB). The bind DN will be:

uid=keycloak-bind,cn=users,cn=accounts,dc=example,dc=internal

Getting the IPA CA into the Keycloak truststore

The single most common failure mode ("PKIX path building failed") is Keycloak's JVM not trusting the IPA CA. There are two supported ways; use option B for anything beyond a throwaway lab because it survives JDK upgrades.

Option A: import into the JDK's cacerts

& "$env:JAVA_HOME\bin\keytool.exe" -importcert `
  -trustcacerts -noprompt `
  -alias freeipa-ca `
  -file C:\certs\ipa-ca.crt `
  -keystore "$env:JAVA_HOME\lib\security\cacerts" `
  -storepass changeit

Option B (recommended): app-local truststore + env var

mkdir C:\keycloak\conf -Force | Out-Null
& "$env:JAVA_HOME\bin\keytool.exe" -importcert `
  -trustcacerts -noprompt `
  -alias freeipa-ca `
  -file C:\certs\ipa-ca.crt `
  -keystore C:\keycloak\conf\truststore.p12 `
  -storetype PKCS12 `
  -storepass changeit

Then make Keycloak use it. Create C:\keycloak\conf\keycloak.conf (Keycloak reads this at startup — no env-var juggling):

# C:\keycloak\conf\keycloak.conf
# ---- HTTP / hostname ----
http-enabled=true
http-port=8080
hostname=localhost
# For non-lab use, drop 'localhost' and set a real FQDN with TLS.

# ---- Truststore: this is how Keycloak trusts the FreeIPA CA ----
truststore-paths=C:/keycloak/conf/truststore.p12
tls-hostname-verifier=DEFAULT

# ---- Logging ----
log-level=info,org.keycloak.storage.ldap:debug

Note the forward slashes in truststore-paths — Keycloak tolerates either, but forward slashes avoid Windows backslash-escape problems if you ever migrate the config.

Launching Keycloak (kc.bat)

First-time build and development start

cd C:\keycloak
bin\kc.bat build
bin\kc.bat start-dev

The build step bakes in your keycloak.conf settings. The start-dev step launches with HTTP and relaxed hostname checks — useful while you are wiring up LDAPS, painful for production. Open http://localhost:8080, create the initial admin user, log in.

Production start

cd C:\keycloak
bin\kc.bat build
bin\kc.bat start --hostname=sso.example.internal --https-port=8443 ^
  --https-certificate-file=C:\certs\sso.example.internal.crt ^
  --https-certificate-key-file=C:\certs\sso.example.internal.key

For a real deployment, issue the sso.example.internal certificate from FreeIPA (ipa cert-request) so it chains to the same CA your federation is already trusting. That way browsers, curl, and Keycloak all validate with one CA.

Admin realm and a test realm

1. Log in as the initial admin to master.
2. Top-left realm picker → Create realm → name: example. This is where IPA users will live.
3. Switch to the example realm for all steps below.

User Federation: LDAPS to FreeIPA

User federation → Add provider → ldap. Use the values below exactly — almost every field that trips people up is in this table.

General options

Connection and authentication

LDAP searching & user attributes

Synchronization settings

• Import users: On
• Batch size: 1000
• Periodic full sync: enable, every 24h for small directories, off and use "on demand" for very large directories.
• Periodic changed-user sync: enable, every 5 min (IPA 389-DS supports modifyTimestamp).

Save. You should see a toast with the federation provider ID. Go back to the provider and click Synchronize all users — logs will show imports. Users (left menu) → you should now see your IPA accounts.

Group mapper

On the federation provider page → Mappers → Create. Type group-ldap-mapper.

Save. Back on the provider → Action → Sync all users. Then check Groups (left menu) — IPA groups should appear with members.

Optional: Kerberos / SPNEGO SSO

If you want browsers on IPA-domain-joined Linux clients (or Windows hosts configured per Windows 11 + FreeIPA) to log into Keycloak-protected apps without typing a password, add Kerberos to the same federation provider.

Create a service principal and keytab on IPA

ipa service-add HTTP/sso.example.internal
ipa-getkeytab -s ipa.example.internal \
  -p HTTP/sso.example.internal \
  -k /tmp/sso.keytab
# Copy to Windows:
# scp /tmp/sso.keytab user@win11:/C:/keycloak/conf/sso.keytab

Wire it into Keycloak

Same federation provider → scroll to "Kerberos integration":

Browser config

• Edge / Chrome: trusted by default for Kerberos to sites matching AuthServerAllowlist. Set via Group Policy or registry: HKLM\SOFTWARE\Policies\Microsoft\Edge\AuthServerAllowlist = *.example.internal.
• Firefox: about:config → network.negotiate-auth.trusted-uris = .example.internal.
• The browser must already have a Kerberos ticket (MIT kinit or a successful SSPI klist).

Troubleshooting

Verification

1. Create a client in the example realm (Clients → Create client), type OpenID Connect, root URL http://localhost:9090/. Save.
2. Use the Keycloak account console (http://localhost:8080/realms/example/account/) to log in as an IPA user. Password must work.
3. In Users → select your IPA user → Groups — the tab should list the IPA groups you expect.
4. Change the user's password in IPA (ipa passwd <uid>) and confirm the old password stops working in Keycloak within the Periodic changed-user sync interval.
5. If you configured Kerberos: from a pre-kinit'd browser, hit the account console and expect no password prompt.

Running Keycloak as a Windows Service

For production, run Keycloak under a Windows Service using NSSM so it restarts on reboot.

nssm install Keycloak "C:\keycloak\bin\kc.bat" start
nssm set Keycloak AppDirectory "C:\keycloak"
nssm set Keycloak AppStdout "C:\keycloak\logs\keycloak.out.log"
nssm set Keycloak AppStderr "C:\keycloak\logs\keycloak.err.log"
nssm set Keycloak AppStopMethodConsole 30000
nssm set Keycloak ObjectName "NT SERVICE\Keycloak" ""
nssm start Keycloak

Then sc query Keycloak and Get-Content C:\keycloak\logs\keycloak.err.log -Wait give you Linux-style service lifecycle on Windows.