Keycloak Identity Provider Federation
You set up keycloak identity provider federation by linking an external identity source to your realm. Then you map incoming group claims to local realm roles for your apps. Most teams connect corporate directories or cloud identity providers through standard protocols like SAML or OIDC. This setup centralizes user login across many internal tools. Still, teams often map external groups to broad admin roles to save time. When a role grants wide privileges, any user in that group can run risky co
Keycloak + Identity Federation: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
You set up keycloak identity provider federation by linking an external identity source to your realm. Then you map incoming group claims to local realm roles for your apps. Most teams connect corporate directories or cloud identity providers through standard protocols like SAML or OIDC. This setup centralizes user login across many internal tools. Still, teams often map external groups to broad admin roles to save time. When a role grants wide privileges, any user in that group can run risky commands.
How keycloak identity provider federation works
Keycloak acts as a central hub between your users and your internal apps. When a user tries to log in, the app sends them to Keycloak. Keycloak then redirects the user to the external identity provider for login checks. The external provider checks the user credentials and sends back a signed token. This token holds user details like email addresses and group memberships.
Once Keycloak receives the token, it checks the signature against a stored public key. If the signature is valid, Keycloak runs identity provider mappers on the token data. These mappers read claims from the external token and assign local roles to the user. You can create mappers that turn external department groups into specific app roles. Next, Keycloak runs a first login flow to create or link a local user account. Finally, Keycloak issues its own token to the app so the user can log in.
Choosing between SAML and OpenID Connect
You must pick a protocol when you link an external identity source. Most teams choose between SAML and OpenID Connect based on their upstream directory. OpenID Connect uses JSON web tokens and works well with modern web and mobile apps. It sends user profile details and group claims through standard endpoints. SAML uses XML messages to pass identity assertions between the provider and your realm. Legacy enterprise directories often rely on SAML for single sign-on workflows.
Both protocols need a shared trust setup between the two systems. You exchange redirect URLs, client identifiers, and signing certificates during the initial setup. You also need to set up token lifetimes that match your security rules. Short token lifetimes force frequent checks against the upstream identity source. When you disable a user in the upstream directory, short lifetimes cut off access fast.
Keycloak + Identity Federation: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What federation solves and what it leaves open
Federation solves the problem of managing separate passwords across dozens of internal tools. When a person leaves the team, you disable their account in one central directory. That single change blocks them from logging into any app linked to your realm. It also lets you enforce multi-factor login rules at the main identity provider. Your internal apps do not need to store passwords or handle complex login flows.
Still, federation only checks who a user is at the moment they log in. It does not inspect what that user does inside a database or server after login. A valid token grants the user a role, and that role stays active for the session. If a developer gets a write role, they can drop tables or read sensitive customer data. Standard role mappers cannot block a dangerous query or mask phone numbers and emails in results. To control actions in flight, you need controls that work at the command level.
Add runtime guardrails and masking beside your databases and APIs
Login rules, role grants, and CI checks govern who connects to your stack. Yet any allowed script, engineer, or AI agent still runs commands with the full scope of its role. For workloads on Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes, SSH, or internal HTTP services, hoop.dev sits inline in the protocol beside the service as an open-source proxy, a sidecar for your database or API. On every production query an agent or human runs, hoop.dev decides whether to pass, mask, block, or escalate it for review.
Before a query runs, hoop.dev guardrails check the statement against your rules, an AI Analyzer you configure can score intent or hold risky calls for human approval, and hoop.dev data masking rewrites sensitive fields in responses in memory. Explore the MIT-licensed project on GitHub.
Frequently asked questions
What is the difference between user storage federation and identity provider federation?
User storage federation links Keycloak directly to a backend database like LDAP to read user records. Identity provider federation redirects users to an external login page using protocols like OIDC or SAML.
How do you sync external groups to local roles during login?
You add an identity provider mapper inside your realm settings for that specific provider. The mapper reads the incoming group claim from the token and assigns the matching local role.
What happens when an external user logs in for the first time?
Keycloak runs a built-in first broker login flow to handle the new user profile. It can create a new local account or link the login to an existing account by email.