#Configure Identity Providers

Keycloak can broker authentication to external Identity Providers (IdPs), allowing users to log in with their existing accounts from OIDC, SAML, or social identity providers.

For foundational concepts on identity federation, see Identity Federation.

#Add an OpenID Connect Identity Provider

Use this procedure to integrate any OIDC-compliant identity provider (for example, Microsoft Entra ID, Okta, or another Keycloak instance).

ACCESS_TOKEN=$(curl -s -X POST \
  "https://<keycloak-host>/realms/master/protocol/openid-connect/token" \
  -d "client_id=admin-cli" \
  -d "username=<admin-user>" \
  -d "password=<admin-password>" \
  -d "grant_type=password" | jq -r '.access_token')

curl -s -X POST \
  "https://<keycloak-host>/admin/realms/<realm>/identity-provider/instances" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "corporate-idp",
    "displayName": "Corporate SSO",
    "providerId": "oidc",
    "enabled": true,
    "config": {
      "authorizationUrl": "https://idp.example.com/authorize",
      "tokenUrl": "https://idp.example.com/token",
      "clientId": "<client-id>",
      "clientSecret": "<client-secret>",
      "defaultScope": "openid email profile"
    }
  }'

#Add a SAML Identity Provider

After creating the SAML IdP, download the Keycloak SP metadata to register with the external IdP:

https://<keycloak-host>/realms/<realm>/broker/<alias>/endpoint/descriptor

#Add a Social Identity Provider

Keycloak provides built-in templates for popular social identity providers. The configuration is similar for each; only the provider-specific client registration differs.

#Supported Social Providers

#Example: Add GitHub as an Identity Provider

1. Register a new OAuth App at GitHub:

   • Homepage URL: https://<keycloak-host>/realms/<realm>
   • Authorization callback URL: https://<keycloak-host>/realms/<realm>/broker/github/endpoint
   • Note the Client ID and Client Secret.

2. In the Keycloak Admin Console:

   • Go to Identity providers > Add provider > GitHub.
   • Enter the Client ID and Client Secret from the GitHub OAuth App.
   • Click Save.

3. The GitHub login button appears on the Realm login page.

#IdP Mappers

IdP Mappers control how user attributes and roles from the external IdP are mapped to Keycloak users.

#Add an IdP Mapper

1. In the IdP detail view, click the Mappers tab.
2. Click Add mapper.
3. Select a mapper type:

4. Configure the source (IdP claim or attribute) and target (Keycloak attribute or role).
5. Click Save.

#First Login Flow

When a user authenticates via an external IdP for the first time, Keycloak executes a First Login Flow to determine how to handle the new identity.

#Default First Login Flow Behavior

1. Review Profile — The user is prompted to review and complete their profile.
2. Create User — If no existing user matches, a new user is created.
3. Link Existing Account — If a user with the same email already exists, the user is prompted to link accounts.

#Customize the First Login Flow

1. Go to Authentication > Flows tab.
2. Duplicate the First broker login flow.
3. Modify the steps as needed:
   • Remove Review Profile to skip the profile review step.
   • Add conditions to automatically link accounts without user confirmation.
4. In the IdP configuration, set First login flow to your custom flow.

#Default Identity Provider

You can configure a default IdP so that the Keycloak login page automatically redirects to the external IdP without showing the local login form.

1. Go to Authentication > Flows > Browser flow.
2. Add an Identity Provider Redirector step.
3. Configure the Default Identity Provider in the step configuration.
4. Set the step requirement to Alternative.

Alternatively, applications can suggest an IdP by passing the kc_idp_hint query parameter in the authorization request:

https://<keycloak-host>/realms/<realm>/protocol/openid-connect/auth?
  client_id=my-app&
  redirect_uri=https://my-app.example.com/callback&
  response_type=code&
  kc_idp_hint=github

#Broker Logout

By default, when a user logs out of Keycloak, the session with the external IdP is not terminated. To enable cascading logout:

1. In the IdP configuration, enable Backchannel logout or Front-channel logout (depending on IdP support).
2. Ensure the external IdP is configured to accept logout requests from Keycloak.