Enabling Identity Federation in Keycloak

Identity federation allows you to delegate authentication to external identity providers (IdPs) like Google, GitHub, Facebook, or enterprise systems such as LDAP and Active Directory. This guide explains how to integrate identity providers using the Keycloak Admin Console, REST API, and Docker CLI (kcadm.sh). It includes configuration examples, permission requirements, best practices, and common issues.
Adding Identity Providers via Keycloak Admin Console
This method supports most popular providers like Google, GitHub, Facebook, and SAML/LDAP.
Access the Admin Console
Log in to your Keycloak Admin Console:
http://<your-keycloak-domain>/admin/
Select the realm where you want to add the identity provider.
Add an Identity Provider (OIDC-based)
Go to Identity Providers > Add Provider
Choose an option like Google, GitHub, or OpenID Connect v1.0
Fill in the following:
 
Alias: A unique name like google or github
Client ID: From the external IdP
Client Secret: From the external IdP
Authorization URL, Token URL, User Info URL: Auto-filled for well-known providers
 
Set Sync Mode (e.g., IMPORT, FORCE, or LEGACY)
Enable Store Tokens if you want offline access
Click Save
Test the Identity Provider
Go to the realm login page
You’ll now see a “Login with Google” or equivalent option
Adding LDAP or Active Directory 
Go to User Federation > Add Provider → LDAP
Fill in connection details:
Field
Example
Connection URL
ldap://ldap.mycompany.com
Users DN
ou=users,dc=mycompany,dc=com
Bind DN
cn=admin,dc=mycompany,dc=com
Bind Credential
Your LDAP password
Vendor
Active Directory, Other, etc.
 
Choose Edit Mode: READ_ONLY, WRITABLE, or UNSYNCED
Enable Periodic Sync if needed
Save and test the connection
Adding Identity Providers via REST API
Get Access Token
curl -X POST "https://<keycloak-domain>/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin" \
  -d "password=admin-password" \
  -d "grant_type=password" \
  -d "client_id=admin-cli"
Save the access_token.
Add OIDC Identity Provider
curl -X POST "https://<keycloak-domain>/admin/realms/<realm>/identity-provider/instances" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "google",
    "providerId": "google",
    "enabled": true,
    "trustEmail": true,
    "storeToken": false,
    "addReadTokenRoleOnCreate": false,
    "firstBrokerLoginFlowAlias": "first broker login",
    "config": {
      "clientId": "GOOGLE_CLIENT_ID",
      "clientSecret": "GOOGLE_CLIENT_SECRET"
    }
  }'
Adding Identity Providers via Docker CLI 
Access the Container
docker exec -it keycloak bash
Add Provider
/opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master --user admin --password admin
/opt/keycloak/bin/kcadm.sh create identity-provider/instances -r <realm> \
  -s alias=github -s providerId=github \
  -s enabled=true \
  -s config.clientId=GITHUB_CLIENT_ID \
  -s config.clientSecret=GITHUB_CLIENT_SECRET
Required Permissions for Identity Federation
Requires manage-identity-providers or admin role in the target realm
REST tokens must come from a user with these privileges
To assign via Admin Console:
Users > [admin-user] > Role Mappings > Realm Roles > Add 'manage-identity-providers'
Best Practices for Identity Federation
Use Standard Broker Flows: Leverage First Broker Login flow to prompt for email verification or account linking.
Map External Claims to Roles: Use Identity Provider Mappers to assign roles or sync attributes (like email, groups, org) automatically.
Avoid Using Public Client IDs in Backend: Always use confidential clients when configuring from the backend or REST API.
Enable Logging During Setup: Use Keycloak’s Events > Settings to track login attempts and errors for debugging.
Test With Separate Test Realm First: Validate your configuration in a dev/test realm before enabling in production.
Common Issues and Troubleshooting
Issue
Possible Cause
Solution
Login button not showing on login page
Provider not enabled
Ensure enabled=true and alias is correct
Invalid client_id error
Client ID mismatch
Verify credentials from the IdP provider dashboard
User not found after login
No email or username claim returned
Check mappers and ensure email or preferred_username is mapped
LDAP users not visible in UI
Wrong base DN or invalid bind credentials
Test connection under User Federation settings
403 Forbidden on REST call
Missing role or token scope
Ensure token has manage-identity-providers