#Identity Federation

#What Is Identity Federation

Identity Federation allows Keycloak to delegate user authentication to an external identity source rather than managing credentials internally. Keycloak acts as a broker: it authenticates users against an external system and then issues its own tokens to client applications.

This enables organizations to:

• Reuse existing corporate identity stores (LDAP, Active Directory) without migrating users to Keycloak.
• Allow users to log in with social accounts (Google, GitHub, Microsoft) or enterprise SSO systems.
• Connect multiple identity domains under a single Keycloak Realm.

#User Federation (LDAP / Active Directory)

User Federation connects Keycloak to an existing user directory such as LDAP or Microsoft Active Directory. Users are stored in the external directory; Keycloak reads and (optionally) writes user data from that directory.

#How It Works

1. Keycloak queries the LDAP/AD server to authenticate a user when they log in.
2. Keycloak caches user attributes locally for performance.
3. User data (username, email, group memberships) is synchronized from the directory to Keycloak on demand or via periodic full synchronization.

#Key Configuration Options

#LDAP Mappers

LDAP Mappers define how LDAP attributes are mapped to Keycloak user attributes and roles. Common mappers include:

• User Attribute Mapper: Maps an LDAP attribute (for example, mail) to a Keycloak user attribute (for example, email).
• Group Mapper: Maps LDAP group memberships to Keycloak groups or roles.
• Role Mapper: Maps LDAP groups to Keycloak Realm or client roles.

#Identity Providers (External IdP Brokering)

Identity Provider (IdP) Brokering connects Keycloak to external OIDC or SAML-based identity providers. Keycloak acts as a Service Provider (SP) to the external IdP and as an Identity Provider to its own clients.

#Supported External IdP Types

#Brokering Flow

1. The user clicks "Login with Google" (or another external IdP) on the Keycloak login page.
2. Keycloak redirects the user to the external IdP for authentication.
3. The external IdP authenticates the user and redirects back to Keycloak with an assertion (OIDC ID token or SAML assertion).
4. Keycloak validates the assertion, creates or links a local user account, and issues its own tokens to the client application.

#First Login Flow

When a user authenticates through an external IdP for the first time, Keycloak runs a First Login Flow to determine how to handle the new user:

• Create a new local user: A new Keycloak user is automatically created and linked to the external identity.
• Link to an existing user: If a local user with the same email already exists, Keycloak can prompt the user to confirm and link the accounts.
• Require profile review: The user is prompted to review or complete their profile before proceeding.

The First Login Flow is fully customizable per identity provider.

#Choosing Between User Federation and IdP Brokering