How Keycloak fronts FreeIPA for web single sign-on
This section covers connecting Keycloak to FreeIPA so web applications can sign users in with OIDC or SAML while Linux identities, groups and host access stay in FreeIPA. Your web apps need standard browser protocols, but the accounts, groups and host policy they depend on already live in FreeIPA, so the design question is how to let Keycloak read that identity data without moving its authority out of FreeIPA. Keycloak handles the protocol side: it issues OIDC tokens and SAML assertions, holds browser sessions, and stores the registration of each client application (redirect URIs, signing keys, scopes and mappers). FreeIPA remains the source of truth for user accounts, group membership, Kerberos tickets, password policy, OTP tokens and host access rules such as HBAC.
The federation mechanism is the core of this design, and it must be confirmed before anything is built. Check how the Keycloak release you plan to run supports the SSSD-based provider, whether it reads through D-Bus, what access that requires on the Keycloak host, and which attributes and groups it imports and how often. Confirm each point against the Keycloak server administration guide and the SSSD documentation for the exact versions in use. Do not assume any connector is available until you have verified it in a test realm. Your team should also decide, at this stage, which system owns user creation, password changes and disablement, because a federated Keycloak realm can hide that answer until an offboarding step fails.
What you need in place before connecting Keycloak to FreeIPA
Connecting Keycloak to FreeIPA depends on a stable directory, a production-grade Keycloak deployment and a few shared foundations that both sides rely on. Work through these cards before you choose a federation path, because each one changes what you build and who must approve it.
A stable FreeIPA topology
Keycloak will query FreeIPA for every login and group lookup, so the directory it binds to must already be healthy. The FreeIPA deployment recommendations call for at least two to three replicas in each datacenter, dedicated servers and at least two DNS servers in each client's resolv.conf. Confirm replication is clean and that the server Keycloak targets is one you can fail over from before adding a second identity source.
A supported Keycloak production database
Keycloak should run on one of its supported production databases, not the development file database. PostgreSQL 14 to 18 is among the listed options, but confirm the exact version against the Keycloak release you plan to deploy. Both supported high availability designs require a synchronously replicated database, so ask your database team whether that exists in your environment before sizing the cluster.
An enrolled Keycloak host
The SSSD federation provider runs on the Keycloak host, so that host must be an SSSD-enrolled IPA client with a working sssd.conf and a read-only D-Bus path for the Keycloak process. The LDAP federation route instead needs only network access and a bind account. Decide which path you need first, then confirm the host's enrollment, service account permissions and which local user runs the Keycloak service.
Kerberos-grade DNS and time
Kerberos rejects tickets when clocks drift and fails when hostnames do not resolve consistently, so both must be correct on Keycloak hosts and on the FreeIPA servers they contact. Check forward and reverse resolution for the Keycloak host and its IPA server, and confirm that time sources are synchronized on every node. Test these before enrollment, because a failure here looks like a federation fault later.
TLS for Keycloak and LDAP
Keycloak's public endpoint needs a certificate that browsers trust, and any LDAP connection carrying bind credentials should use TLS. Decide whether FreeIPA's Dogtag CA will issue these certificates or whether your enterprise CA will, and confirm that the Keycloak truststore contains the chain your IPA servers present. Plan the renewal process now, since certificate expiry is a common cause of federation outages.
Approvals and the Keycloak release
Creating a bind or service account in FreeIPA usually needs an administrator who controls the directory, so name that approver and the location of the account before work starts. Confirm the Keycloak release you will run, and if you plan to use Red Hat build of Keycloak, confirm its support requirements with Red Hat, since its latest published version may differ from the upstream release. The upstream Keycloak project lists its current release on its website.
SSSD federation provider or LDAP federation: choosing the path
With the SSSD path, Keycloak does not open its own connection to the directory. It asks the SSSD service on the Keycloak host for identity data. SSSD answers from its local cache or fetches entries from FreeIPA on demand. The Keycloak host is enrolled as an IPA client, so SSSD already holds the Kerberos and LDAP settings it needs.
- Read-only D-Bus access: Keycloak reaches SSSD over the system D-Bus. This design only needs lookups, so the access granted to the Keycloak process should be limited to read calls. Confirm the exact D-Bus policy the chosen Keycloak release expects before you write it.
- What SSSD caches: SSSD keeps user, group and membership entries in a local cache and refreshes them on its own timeouts. A change made in FreeIPA can reach Keycloak only after the cache refreshes or is cleared. Confirm the cache settings in your SSSD configuration.
- Network reach from the Keycloak host: The host must reach the FreeIPA servers SSSD uses for LDAP and Kerberos, usually found through DNS discovery. Test DNS resolution and ports from the Keycloak host itself.
- Enrollment prerequisites: Enrollment, time synchronization and the SSSD domain configuration are part of the Keycloak build, and they belong in the same change plan.
- Ongoing host work: SSSD upgrades and cache troubleshooting now run on the Keycloak host, so the team that patches Keycloak must also own those tasks.
Before you document the provider name or configuration keys, confirm them in the Keycloak release you plan to run, then test a user and group lookup from the Keycloak host.
Direct LDAP federation makes Keycloak a client of the FreeIPA directory. Keycloak binds with a service account, searches a base DN and maps directory attributes to its own user model. No SSSD component is needed on the Keycloak host, so this is often the simpler choice when the Keycloak host cannot be enrolled in FreeIPA or when the team wants fewer moving parts on that host.
- Service account: Create a dedicated bind identity in FreeIPA with read access to the user and group subtrees. Keep the bind password in Keycloak's secret handling and set a rotation process. Check whether the LDAP system accounts feature in FreeIPA 4.13 fits your version.
- Bind DN and search bases: Point the bind DN and the user and group search bases at the FreeIPA subtrees you intend to expose. Narrower bases limit what Keycloak can import.
- Attribute mapping: Map FreeIPA attributes such as login name, given name, surname and email to Keycloak user attributes. List the attributes your applications need before you build the mapping.
- Transport security: Use encrypted connections to the directory and make Keycloak trust the FreeIPA certificate authority chain.
- Group handling: Decide whether Keycloak imports groups or evaluates membership at sign-in, because each choice changes how group changes appear.
Test the bind and a search from the Keycloak host using the same base and filter that Keycloak will use. The Keycloak server administration guide describes the user federation settings for the release you run.
The two paths differ most in how changes arrive and how each one behaves during an outage. In both designs FreeIPA remains the source of users and groups. The path determines how Keycloak sees them and what the Keycloak host has to maintain.
- Who manages users: In both paths, administrators create, change and disable users in FreeIPA. Keycloak should not become a place where Linux accounts are edited, since that splits ownership of the same identity.
- How group changes propagate: With SSSD, group changes appear after SSSD refreshes its cache. With LDAP federation, they appear according to Keycloak's sync and lookup behavior. Confirm the sync schedule and any on-demand refresh option in your release.
- When a FreeIPA replica is unavailable: SSSD can serve cached entries and reconnect to other discovered IPA servers, so sign-in for cached users may continue during part of an outage. With LDAP federation, Keycloak uses the server URLs you configure. Unless you configure more than one server or a load balancer, an outage on that server blocks lookups and sign-ins. Confirm the failover and offline options for both paths in your environment.
- Where the maintenance sits: The SSSD path adds host-level components to patch. The LDAP path adds a service account and bind secret to govern and rotate.
- Replica layout: Both paths depend on the replica placement in the FreeIPA deployment recommendations, so set replica locations before you design federation.
Record the chosen path for each Keycloak realm, then test a replica outage in staging before go-live.
How to configure the Keycloak and FreeIPA federation in order
This sequence takes a Keycloak host from a FreeIPA client with working SSSD lookups to a test realm that issues OIDC and SAML tokens carrying FreeIPA identities. Each step ends with a check so you know it is safe to move on.
Create the FreeIPA service identity with minimum read rights
An administrator creates a dedicated bind identity in FreeIPA for Keycloak, separate from any personal or admin account, and grants it only the read access the chosen federation method needs. Confirm the exact permission set in the documentation for your Keycloak version and the federation provider you selected before granting anything, because the SSSD and LDAP routes depend on different access paths. The step is closed when a test read of one known user's attributes succeeds with that identity and a write attempt is refused.
Enroll the Keycloak host as a FreeIPA client
The platform team enrolls the server that will run Keycloak as a FreeIPA client using the standard client enrollment process, then confirms that SSSD is running and configured for the IPA domain. Keep the host on a dedicated, supported Linux distribution and check the client enrollment guidance for the version of FreeIPA in use. The step is closed when the host joins the realm and a Kerberos ticket can be obtained for a test user.
Confirm SSSD resolves users and groups
On the Keycloak host, the team runs id lookups for a test user and for a group the user belongs to, and checks that the results match what the FreeIPA web UI shows. Verify that the Keycloak service account runs under a local user that can read the SSSD D-Bus or LDAP path it will use, and that nothing relies on a cached result from an earlier configuration. The step is closed when id returns the expected UID, primary group and supplementary groups for every test user, including one in a nested group.
Configure the chosen federation provider in a test realm
In a non-production Keycloak realm, the administrator adds the federation provider you selected, either the SSSD provider or an LDAP user federation provider, and sets the connection details, bind identity and search base. Keep the realm separate from production so that misconfiguration cannot affect real sign-ins, and record each setting so it can be repeated during the production build. Validate every setting against the documentation for your Keycloak release, since provider options change between versions. The step is closed when the provider's connection test succeeds and a manual user sync finds the test accounts.
Set attribute and group import behavior
The administrator decides which FreeIPA attributes Keycloak imports, such as username, email, given name and surname, and whether group membership is imported as Keycloak groups, mapped to roles, or only read at token time. Document where each attribute is authoritative, because changes made in Keycloak do not flow back into FreeIPA, and confirm the import mode and any sync schedule in the Keycloak documentation. The step is closed when a test user's Keycloak profile shows the expected attributes and the expected group membership, and an edit made in FreeIPA appears after the configured sync.
Create a test OIDC client and confirm claims
The team creates a test OpenID Connect client in the test realm, configures its redirect URIs for a non-production application, and maps the imported attributes and groups into the ID token and access token. They then sign in as a test user and decode the tokens to confirm the claims are present and correct. Ask your application team which claim names and formats they expect, and confirm the mapper settings against the current Keycloak documentation. The step is closed when the decoded token contains the expected subject, email and group claims for the test user.
Create a test SAML client and confirm its assertion
Next, the administrator creates a test SAML 2.0 client with the service provider's entity ID and assertion consumer URL, then maps the same FreeIPA-backed attributes into the assertion. A tester signs in through the SAML flow and inspects the assertion to check the NameID format and attribute names against what the service provider requires. The step is closed when the assertion is accepted by the test service provider and carries the expected attributes.
Confirm login and logout across both clients
The team tests a full cycle: sign in through the OIDC client, sign in through the SAML client using the same Keycloak session, then log out from one application and check how the other responds. Record whether logout propagates to each client, and compare the results to the behavior your application owners need before any production change. Also confirm that a user disabled in FreeIPA loses access after the next sync and sign-in attempt. The step is closed when both clients sign in, log out as designed, and a disabled FreeIPA account is refused.
Which FreeIPA attributes and groups map to Keycloak claims
This table lists the FreeIPA data that can reach Keycloak, the Keycloak field it lands in, the claim or SAML attribute a web application receives, and who controls each value. Confirm each row against your Keycloak version and federation settings before you rely on it, because the import behavior depends on which provider you configure. The main takeaway is that identity data should be edited in FreeIPA, while host and sudo data stays out of web tokens.
| FreeIPA source | Keycloak attribute or group | Token claim or SAML attribute | Owner who decides the value |
|---|---|---|---|
| Login name (uid) | Username | preferred_username (OIDC); name identifier or username attribute (SAML, confirm mapper) | FreeIPA administrators, set when the account is created |
| Email (mail) | email claim (confirm the provider imports this attribute) | The user through FreeIPA self-service, or FreeIPA administrators | |
| Given name (givenName) | First name | given_name claim | FreeIPA administrators |
| Surname (sn) | Last name | family_name claim | FreeIPA administrators |
| Groups used for roles (memberOf) | Keycloak group or role mapping | groups or roles claim, through a mapper you configure | FreeIPA administrators own membership; Keycloak administrators own the role mapping |
| Host-based access and sudo rules | Not mapped | None; keep these out of web tokens | Security team, which decides what web apps may see |
| Kerberos keys and keytabs | Not mapped | None; these are credential material | Security team and service owners |
| Change propagation for the rows above | Imported copy in Keycloak | Shows the value present at the last import or login | Confirm whether changes sync at login or on a schedule, and the interval, in your version's documentation |
How to test attribute and group import before go-live
Test attribute and group import in a non-production copy of the integration before any real user signs in through Keycloak. Build a small set of FreeIPA test users that cover the cases your Keycloak mappers and role logic depend on: one user per group that grants access, a user nested two or more levels deep through a parent group, and users with optional attributes such as email, display name or department left empty. For each user, sign in through a Keycloak test client and record the resulting user record in the Keycloak admin console, confirming which attributes arrived, which groups were imported and whether the group names match what your realm roles and client scopes expect. Then decode the ID token and access token and check that each claim your applications rely on is present, correctly named and not empty. Where a claim is missing, decide whether the fix belongs in the FreeIPA attribute, the SSSD configuration or the Keycloak mapper, and retest.
Next, test the failure and change cases that operations teams will meet after go-live. Stop one FreeIPA replica that Keycloak's SSSD-based provider reaches during a login and confirm whether sign-in still succeeds through another server listed in the SSSD configuration, and how long the attempt takes to fail when none is reachable. Change a test user's password in FreeIPA and confirm whether the new password works through Keycloak and whether the old one stops working, noting any cached state that delays the change. Disable a test account in FreeIPA and check that Keycloak refuses new sign-ins and what happens to sessions already open. Record each result in a table with the exact FreeIPA and Keycloak versions under test. Confirm the current versions and the supported SSSD behavior with your platform team and the FreeIPA About page before you rely on any observed timing.
Finally, plan the upgrade test as part of the same exercise. The Keycloak Operator documentation strongly recommends manual approval mode for operator updates to avoid unintended automatic upgrades, so set the operator subscription to manual and apply each new Keycloak release first in the test environment. Re-run the full attribute, group and failure matrix after every upgrade, because a minor release can change claim defaults or mapper behavior, and check the Keycloak upgrading guide for breaking changes that apply to your configuration. Keep the test users, expected claim values and results in version control so the same checks can run again. Treat a passing matrix as the go-live gate, and do not promote a Keycloak or FreeIPA change to production until its results match the recorded baseline.
Security controls for the Keycloak and FreeIPA trust
Keycloak in front of FreeIPA gives web applications OIDC and SAML while Linux identities stay where they are managed. The trust between the two systems carries the directory credentials, the login traffic and the realm configuration, so each of these needs its own control. The cards below cover what to restrict, encrypt, monitor and keep current.
Dedicated low-privilege bind identity
Give Keycloak a separate FreeIPA account whose only job is reading the directory attributes needed for federation. Keep its password in a secrets manager rather than in realm configuration files, and rotate it on a schedule your team can actually follow. Confirm with your own FreeIPA administrators which attributes and groups that account can read, and avoid reusing an administrator account for convenience. Keep write access from Keycloak off unless your chosen design explicitly requires it.
TLS on every path
Encrypt the LDAP connection from Keycloak to FreeIPA and every HTTP path that carries login traffic, including the Keycloak endpoints that browsers and applications reach. Verify that Keycloak trusts the certificate chain issued for your FreeIPA servers, and check the hostname matches what Keycloak connects to. Review the production configuration guide before go-live so that no development setting, such as plain HTTP, carries into production.
Scoping realms and clients
Decide which Keycloak realms and clients may use the FreeIPA federation, and limit the rest from using it. A single realm that serves internal staff should not share a federation provider with a customer-facing realm without a deliberate reason. Review client redirect URIs and the attribute and group mappers that each client receives, because a broad mapper can expose more of the directory than the application needs.
Synchronously replicated Keycloak database
Keycloak's documented high availability designs both require a synchronously replicated database, so a failover should not lose or roll back session and configuration state. Confirm which database Keycloak uses from the supported list, and check how your replication and failover behave under load. Plan backups of the database separately from FreeIPA backups, since each system holds different state.
Monitoring failed binds and logins
Track failed LDAP binds, rejected logins and federation errors so that a broken bind account or a password spray attempt shows up quickly. Enable Keycloak's metrics and feed them into the monitoring stack your operations team already runs. Set alerts on a sustained rise in failures and on federation sync errors, and confirm that the logs keep the user and realm context needed for investigation.
Supported releases and upgrades
Keep Keycloak and FreeIPA on releases that still receive fixes, and plan upgrades as a process rather than an event. Keycloak's operator documentation recommends manual approval for operator updates, which keeps upgrades under your change control. Test each upgrade against a copy of your realm and federation settings, and confirm the FreeIPA server and client versions your environment runs before you change either side.
Common failures when Keycloak reads FreeIPA identities
This table pairs each common symptom with its likely cause and the first check to run when Keycloak reads identities from FreeIPA through SSSD. Work down the rows in order, because several symptoms share causes such as clock skew, DNS mismatches and cache state. Each first check points to a command or log to inspect in your own environment rather than a setting to change.
| Symptom | Likely cause | First check |
|---|---|---|
| Users log in to FreeIPA but not to Keycloak | The user is missing from the view Keycloak reads, the account is locked or expired, or the federation provider is bound to a different base DN | Confirm the user resolves on the Keycloak host with the id command, then review the federation provider's base DN and the Keycloak log for the bind and search results |
| Groups missing from tokens | Group membership is not mapped into the token claims, or the group is outside the search scope configured in the provider | Compare the group list returned by the id command on the host with the mapper configuration in the Keycloak client scope and the provider's group settings |
| Stale group membership after an admin change | Cached entries in SSSD or Keycloak still hold the previous membership | Check the cache timestamps with SSSD tooling on the Keycloak host, then compare the group in the FreeIPA web UI or ipa command output with what Keycloak returns after a fresh sign-in |
| Kerberos authentication fails with clock errors | Clock skew between the Keycloak host, the FreeIPA servers and the client exceeds the Kerberos tolerance | Compare the output of the time status check on each host and confirm all sync to the same NTP sources, including the FreeIPA NTP setting |
| Hostnames fail to resolve or Kerberos cannot find the KDC | The Keycloak host uses DNS servers or search domains that do not match the FreeIPA zones, or resolv.conf lists fewer than two DNS servers | Resolve the FreeIPA server and KDC service records from the Keycloak host and confirm the forward and reverse names match the realm |
| Certificate chain errors on LDAP over TLS | The Keycloak host does not trust the FreeIPA CA certificate, or the certificate name does not match the server name in the connection URL | Inspect the presented certificate chain with an OpenSSL client test against the FreeIPA server, then confirm the CA file in the SSSD and Keycloak trust store and the name in the URL |
| Old data returned after a directory change | The SSSD cache on the Keycloak host has not expired or been invalidated | Review the SSSD cache settings and logs on the host, then clear the cache for the affected user in a maintenance window and retry the lookup |
| Login outage when one FreeIPA replica is down | The SSSD configuration lists a single server, or the Keycloak provider points to one replica without a failover path | Verify that SSSD and the provider list more than one FreeIPA server or use service discovery, and confirm each replica answers LDAP and Kerberos checks |
Questions buyers ask before connecting Keycloak to FreeIPA
What drives the cost of a Keycloak and FreeIPA integration?
The main drivers are the number of realms and clients, how many groups and attribute mappings must reach each application, the high availability design, the testing scope, and whether SAML, OIDC or both apply. Each realm, client and protocol adds configuration, mapping and test cases. Cost also depends on who does the work: a partner is paid under a written, fixed scope, while your own team carries the time as internal effort. Ask any quote to itemize design, build, testing, documentation and knowledge transfer separately, and to state which items are one-time and which recur, such as upgrades or support.
How long does a Keycloak and FreeIPA integration take?
Duration follows the scope agreed in writing, so the same platform can take very different time depending on the number of clients, the protocols in use and the test coverage required. Most engagements are fixed-scope, which means the scope, deliverables and timeline are fixed before work starts. Ask for a schedule that lists the design sign-off, a test environment milestone, the client registration phase and the cutover window, and confirm which of those depend on your application owners or change approvals.
What must our team provide before the work starts?
You need to provide FreeIPA administrator access with a named account that can read the directory schema, a test environment that mirrors the production FreeIPA and Keycloak topology, and details of the certificate authority that issues the TLS certificates Keycloak will present. You also need named application owners who can confirm redirect URIs, required claims and group membership for each client. Without owners and test access, client registration stalls, so agree these contacts in the scope document.
Can our own team build this without a partner?
A capable team can build it alone if it has working knowledge of Linux, Kerberos, LDAP, SSSD and the Keycloak administration model, and if someone owns the FreeIPA side. The skills that are hardest to staff are Kerberos troubleshooting, certificate handling and SAML metadata exchange. Compare the internal hours against the work list in a written scope, and decide whether to bring in outside help for design review, testing or cutover rather than the whole build.
Does user management move from FreeIPA to Keycloak?
No. In this design, FreeIPA stays the system of record for users, groups and Linux identities, and Keycloak reads them through the SSSD federation provider. Creating, disabling and changing accounts happens in FreeIPA, so Linux logins and web sign-in stay consistent. Move user management into Keycloak only if your design deliberately changes that boundary, and record that decision in writing, because it changes ownership of joiners, movers and leavers processes.
What happens after go-live, and what does support cost?
After go-live, the recurring work is upgrades for both FreeIPA and Keycloak, regression testing of each client, monitoring and periodic review of group mappings. Keycloak now ships four minor releases a year, and its Operator documentation recommends manual approval for operator updates, so plan a test cycle for each upgrade. Ongoing support, upgrades and continuous testing are available as retainers, and the terms, response expectations and included testing should be written into the agreement before the handover.
What should we verify before accepting the handover?
Verify that a test user from each FreeIPA group receives the expected claims or assertions in every client, that disabled FreeIPA accounts lose web access after the agreed token lifetime, and that Linux login through SSSD still works after a Keycloak change. Confirm that the database and backup procedures for Keycloak are documented and tested, and that the team knows how to rotate client secrets and certificates. Ask for the test evidence as a deliverable, because it becomes the baseline for every later upgrade.
How DeployOpen works on this
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including the Keycloak and FreeIPA integration described here. We agree the scope in writing first, then build and hand over the working system with the documentation your team needs to run it.
How we scope
- Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
- The written scope names which FreeIPA users, groups and attributes Keycloak will read through SSSD and which applications will sign in through it.
- Scope also records where your Keycloak runs, which database and high availability design it uses, and who will manage users in FreeIPA.
How we build
- We configure the SSSD federation provider on the Keycloak host and set up the read-only D-Bus access that the provider depends on.
- We map user attributes and group membership into Keycloak, then test imports against sample accounts before any production user is involved.
- We register OIDC and SAML clients for each web application and test sign-in, token contents and logout behavior against each one.
How we hand over
- You receive configuration documentation covering SSSD settings, Keycloak realm and federation settings, and the attribute and group import rules.
- The handover documents the operating boundary: which changes are made in FreeIPA and which are made in Keycloak, so administrators know where to act.
- We walk your administrators through a runbook for adding applications, troubleshooting failed logins and checking that group changes reach Keycloak.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, so Keycloak and FreeIPA can be kept current after handover.
- Retainer scope is agreed in writing and can cover Keycloak release upgrades and FreeIPA 4.x updates in your environment.
- Before any upgrade, we agree the test plan, backup steps and rollback path with your team so the change is verified in a non-production copy first.
