Connect Keycloak to FreeIPA and Red Hat IdM

Overview

SSO needs a reproducible identity platform, clean certificates, controlled clients and traceable federation or LDAP integration.

The article builds Keycloak with Podman or the specific integration task step by step and explains the relevant security decisions.

Teams gain a reliable base for SSO, MFA, federation, central login and secure application integration.

Tested environment / validation

• Status: September 2026

• Product & version: Keycloak 26.x

• Infrastructure: separate Keycloak reference instances with Podman, PostgreSQL and TLS

• Security: admin passwords, client secrets and internal tokens are replaced by placeholders.

1. Starting point & prerequisites

The starting point is an empty or deliberately separated Keycloak instance. DNS, TLS, persistent volumes, database, reverse proxy and truststore must be prepared before production use.

2. Step-by-step guide

The following steps describe the practical flow. Run them in order and validate the result after each larger section.

This second part continues after installing Keycloak 26.7 with Podman and the existing FreeIPA series. You learn what Keycloak is responsible for in an identity stack, why FreeIPA or Red Hat Identity Management remain the leading directory and how Keycloak makes users visible through LDAP.

In short: FreeIPA or Red Hat IdM manage identities, groups, Kerberos, host access, HBAC, sudo and PKI-adjacent operational functions. Keycloak translates those identities into modern web and API logins through OIDC, OAuth2 and SAML. Applications such as grommunio, XWiki, OpenProject, ForgeOneCMS or internal portals can then use the same central identity base.

The screenshots come from an isolated local Keycloak lab with a synthetic LDAP directory. The configuration follows FreeIPA/Red Hat IdM principles: read-only user source, dedicated realm, LDAP sync, no clear-text secrets in the article and no customer data.

Read first: FreeIPA and Red Hat IdM

If you do not yet have an IdM server, start with installing FreeIPA. If you want to understand architecture, HBAC, sudo, PKI and the Keycloak role in a larger environment, continue with FreeIPA in large environments. For RHEL environments, Red Hat Identity Management is the supported enterprise variant.

Target architecture

The target state is deliberately separated: users and groups live in IdM. Keycloak connects to the directory via LDAP or LDAPS. Applications do not talk directly to FreeIPA; they talk to Keycloak. This lets you manage MFA, client policies, token lifetime, redirect URIs and claim mapping centrally.

FreeIPA / Red Hat IdM
  -> LDAP / LDAPS
  -> Keycloak User Federation
  -> OIDC / SAML Clients
  -> Applications and portals

Step 1: Separate the application realm

Do not use the `master` realm as a catch-all for applications. Create a dedicated realm for the environment, for example `forgeone-idm`. Configure user federation, MFA and application clients there, separated from Keycloak administration.

http://127.0.0.1:18080/admin/forgeone-idm/console/

Step 2: Add the LDAP provider

In Keycloak, open User Federation and add an LDAP provider. For FreeIPA and Red Hat IdM, this is the central entry point. The lab used a synthetic LDAP directory; in production, use your real IdM FQDN, preferably via LDAPS.

http://127.0.0.1:18080/admin/forgeone-idm/console/#/forgeone-idm/user-federation

3. Validation / technical acceptance

4. Typical issues & troubleshooting

• Container does not start: check Podman logs, environment, ports, volumes and SELinux contexts.

• Certificates are not trusted: review CA chain, truststore and reverse proxy configuration.

• LDAP or federation shows no users: check bind DN, filters, mappers, time and group model.

5. Conclusion & outlook

Keycloak is now positioned as an identity building block and technically verifiable. FreeIPA/Red Hat IdM, federation, theming and application integration build on this foundation.

Step 3: Configure connection and search base

Configure the connection so Keycloak only reads the intended user tree. In production, use `ldaps://ipa01.example.test:636`, a dedicated bind account with minimal read permissions and an internal CA certificate in the Keycloak truststore. The local lab used `ldap://forgeone-keycloak-ldap:389`.

http://127.0.0.1:18080/admin/forgeone-idm/console/#/forgeone-idm/user-federation

UI display name: freeipa-example-test
Vendor: Red Hat Directory Server
Connection URL: ldaps://ipa01.example.test:636
Bind DN: uid=svc-keycloak,cn=users,cn=accounts,dc=example,dc=test
Users DN: cn=users,cn=accounts,dc=example,dc=test
Edit mode: READ_ONLY
Import users: ON
Sync registrations: OFF

Step 4: Plan TLS and truststore

LDAPS is only clean when Keycloak trusts the CA of the IdM server. Import the internal root or intermediate CA into the Keycloak truststore and test the connection afterwards. Without a correct trust chain, login or sync errors become unnecessarily hard to read.

install -d -m 0750 /opt/keycloak/conf/truststores
cp example-test-root-ca.pem /opt/keycloak/conf/truststores/example-test-root-ca.pem

keytool -importcert -noprompt \
  -alias example-test-root-ca \
  -file /opt/keycloak/conf/truststores/example-test-root-ca.pem \
  -keystore /opt/keycloak/conf/truststores/keycloak-truststore.p12 \
  -storetype PKCS12

Step 5: Decide import, sync and write model

For many enterprise environments, `READ_ONLY` is the right starting point: users are maintained in IdM, Keycloak reads and synchronizes them. Passwords are not copied to Keycloak. Authentication happens against the external directory. User lifecycle changes remain in IdM.

Keycloak can import users or read directly from LDAP. Imported users improve many Keycloak features, but create local metadata. This is not a second source of truth; it is a cache and mapping model. Groups, roles and claims must therefore be designed intentionally.

Step 6: Run a full sync

After saving, run a full sync. In the lab, two synthetic users were imported. In production, start with a small search base or test group and only then broaden synchronization.

/opt/keycloak/bin/kcadm.sh create "user-storage/<provider-id>/sync?action=triggerFullSync" \
  -r forgeone-idm

/opt/keycloak/bin/kcadm.sh get users -r forgeone-idm \
  --fields username,email,firstName,lastName,origin

http://127.0.0.1:18080/admin/forgeone-idm/console/#/forgeone-idm/users

Step 7: Search users deliberately

Do not blindly search huge directories. Check individual users, attributes and email addresses. If users are missing, verify search base, object classes, filters, bind permissions, paging and LDAP mapping.

http://127.0.0.1:18080/admin/forgeone-idm/console/#/forgeone-idm/users

Step 8: Do not skip mappers and groups

A basic user sync is rarely enough for production applications. You need clear mappers for username, email, first name, last name, groups and possibly roles. With FreeIPA/Red Hat IdM, do not randomly turn groups into Keycloak roles; design a clear claim model.

Step 9: MFA belongs into the login flow

MFA can be enabled in Keycloak per realm, group or flow. This keeps IdM as the identity source while Keycloak secures the web login. MFA should be mandatory for administrators; for users it depends on protection level, application and risk.

Step 10: Operational checks

After integration, do not only check the UI. What matters are logs, sync result, login test, account lockout, disabled users, group changes, certificate chain and what happens if LDAP is temporarily unavailable.

podman logs --tail=200 forgeone-keycloak-lab | grep -i ldap
curl -fsS https://sso.example.test/realms/forgeone-idm/.well-known/openid-configuration | jq '.issuer'
ldapsearch -H ldaps://ipa01.example.test:636 \
  -D "uid=svc-keycloak,cn=users,cn=accounts,dc=example,dc=test" \
  -W \
  -b "cn=users,cn=accounts,dc=example,dc=test" "(uid=mathias)" uid mail cn

Final checklist

At the end, realm, LDAP connection, truststore, bind account, search base, import model, sync, user visibility, mappers, MFA plan and operational checks should be documented. Only then is Keycloak ready to connect applications through OIDC or SAML.

Next part of the series

The next logical step is Keycloak federation: one Keycloak can use another Keycloak as an identity provider. This is useful when tenants, organizations or existing SSO landscapes should remain separated while still working together centrally.