# Enabling Identity Federation in Keycloak

<span class="s2">**Identity federation**</span> 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)**

1. <span class="s1">Go to </span>**Identity Providers &gt; Add Provider**
2. <span class="s1">Choose an option like </span>Google<span class="s1">, </span>GitHub<span class="s1">, or </span>OpenID Connect v1.0
3. Fill in the following:
    
    
    - <span class="s1">**Alias**</span>: A unique name like <span class="s2">google</span> or <span class="s2">github</span>
    - <span class="s1">**Client ID**</span>: From the external IdP
    - <span class="s1">**Client Secret**</span>: From the external IdP
    - <span class="s1">**Authorization URL**</span>, <span class="s1">**Token URL**</span>, <span class="s1">**User Info URL**</span>: Auto-filled for well-known providers
4. Set <span class="s1">**Sync Mode**</span> (e.g., <span class="s2">IMPORT</span>, <span class="s2">FORCE</span>, or <span class="s2">LEGACY</span>)
5. Enable <span class="s1">**Store Tokens**</span> if you want offline access
6. Click <span class="s1">**Save**</span>

[![image.png](https://docs.elest.io/uploads/images/gallery/2025-06/scaled-1680-/ujPimage.png)](https://docs.elest.io/uploads/images/gallery/2025-06/ujPimage.png)

#### **Test the Identity Provider**

1. Go to the realm login page
2. You’ll now see a <span class="s1">**“Login with Google”**</span> or equivalent option

## **Adding LDAP or Active Directory** 

1. <span class="s1">Go to </span>**User Federation &gt; Add Provider → LDAP**
2. Fill in connection details:

<table id="bkmrk-field-example-connec"><thead><tr><th>**Field**

</th><th>**Example**

</th></tr></thead><tbody><tr><td>Connection URL

</td><td>ldap://ldap.mycompany.com

</td></tr><tr><td>Users DN

</td><td>ou=users,dc=mycompany,dc=com

</td></tr><tr><td>Bind DN

</td><td>cn=admin,dc=mycompany,dc=com

</td></tr><tr><td>Bind Credential

</td><td>Your LDAP password

</td></tr><tr><td>Vendor

</td><td>Active Directory<span class="s1">, </span>Other<span class="s1">, etc.</span>

</td></tr></tbody></table>

2. <span class="s1">Choose </span><span class="s2">**Edit Mode**</span><span class="s1">: </span>READ\_ONLY<span class="s1">, </span>WRITABLE<span class="s1">, or </span>UNSYNCED
3. Enable <span class="s1">**Periodic Sync**</span> if needed
4. Save and test the connection

[![image.png](https://docs.elest.io/uploads/images/gallery/2025-06/scaled-1680-/agpimage.png)](https://docs.elest.io/uploads/images/gallery/2025-06/agpimage.png)

## **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"
```

<span class="s1">Save the </span>access\_token<span class="s1">.</span>

#### **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 <span class="s1">manage-identity-providers</span> or <span class="s1">admin</span> 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 <span class="s2">**First Broker Login**</span> flow to prompt for email verification or account linking.
- **Map External Claims to Roles:** Use <span class="s2">**Identity Provider Mappers**</span> to assign roles or sync attributes (like <span class="s3">email</span>, <span class="s3">groups</span>, <span class="s3">org</span>) 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 <span class="s2">**Events &gt; Settings**</span> 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**

<table border="1" id="bkmrk-issue-possible-cause" style="border-collapse: collapse; border-color: rgb(0, 0, 0);"><thead><tr><th style="border-color: rgb(0, 0, 0);">**Issue**

</th><th style="border-color: rgb(0, 0, 0);">**Possible Cause**

</th><th style="border-color: rgb(0, 0, 0);">**Solution**

</th></tr></thead><tbody><tr><td style="border-color: rgb(0, 0, 0);">Login button not showing on login page

</td><td style="border-color: rgb(0, 0, 0);">Provider not enabled

</td><td style="border-color: rgb(0, 0, 0);">Ensure <span class="s1">enabled=true</span> and <span class="s1">alias</span> is correct

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Invalid client\_id<span class="s1"> error</span>

</td><td style="border-color: rgb(0, 0, 0);">Client ID mismatch

</td><td style="border-color: rgb(0, 0, 0);">Verify credentials from the IdP provider dashboard

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">User not found after login

</td><td style="border-color: rgb(0, 0, 0);">No email or username claim returned

</td><td style="border-color: rgb(0, 0, 0);">Check mappers and ensure <span class="s1">email</span> or <span class="s1">preferred\_username</span> is mapped

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">LDAP users not visible in UI

</td><td style="border-color: rgb(0, 0, 0);">Wrong base DN or invalid bind credentials

</td><td style="border-color: rgb(0, 0, 0);">Test connection under <span class="s1">**User Federation**</span> settings

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">403 Forbidden<span class="s1"> on REST call</span>

</td><td style="border-color: rgb(0, 0, 0);">Missing role or token scope

</td><td style="border-color: rgb(0, 0, 0);"><span class="s1">Ensure token has </span>manage-identity-providers

</td></tr></tbody></table>