Learn Keycloak - Social Login & Identity Brokering

#Introduction

In episode 15 you connected Keycloak to external directories such as LDAP and Active Directory. Episode 16 adds a different entrance: social login through identity brokering. You'll let users sign in with Google, GitHub, Facebook, and other accounts — while Keycloak remains the center that holds the session, links external accounts to internal identities, and enriches the user profile from provider claims.

#What Is Identity Brokering

Identity brokering is a pattern where Keycloak plays the intermediary: it doesn't hold user credentials, but receives identity from an external provider (the broker) and forwards it to the application. Unlike user federation, which reads directly from a directory, here authentication happens at the provider's side, then the result is handed to Keycloak.

Technically, each external provider is an identity provider registered in the realm via the Identity Providers tab in the admin console. Keycloak becomes a brokered IdP for its applications: applications still talk to Keycloak (OIDC or SAML), never knowing the user actually logged in at Google.

#Common Social Identity Providers

Redirect URI in the last column is the address you must register in each provider's developer portal. Without registering it, the provider will reject the callback with a redirect_uri_mismatch error.

#Setting Up the OAuth App on the Provider Side

The steps always begin at the provider's developer portal:

1. Open the provider's developer portal (Google Cloud, GitHub, etc.)
2. Create a new application or OAuth client
3. Note the client ID and client secret you receive
4. Register the Keycloak redirect URI for that broker
5. Choose the scopes to request (email, profile)
6. Save and note the credentials

Example list of redirect URIs registered in the developer portal:

https://keycloak.example.com/realms/demo/broker/google/endpoint
https://keycloak.example.com/realms/demo/broker/github/endpoint
https://keycloak.example.com/realms/demo/broker/facebook/endpoint

client_id and client_secret are then entered into Keycloak on the Identity Providers tab for the relevant provider.

#Scopes and Attribute Mapping

Scopes determine what data is requested from the provider — the most basic are email and profile. In Keycloak, the received claims can be mapped to user profile attributes through mappers. For example, the email claim from Google becomes the Keycloak user's email value, and the name from profile is used to fill in the first and last names.

The rule of thumb: request as few scopes as possible. Every piece of data not requested won't be received, and every piece received is your responsibility to protect.

#The First Broker Login Flow

When a user first logs in through an external provider, Keycloak runs the first broker login flow — a special flow for linking the external identity to an internal account:

1. The user clicks the Google or GitHub login button.
2. The user is authenticated at the provider and redirected back to Keycloak.
3. Keycloak looks for a matching local account (for example via email).
4. If there's none, Keycloak can create a new account or ask the user to choose a follow-up flow.
5. If there is one, the user is guided to link the external account with their local account.

#Account Linking

Account linking is the process of merging an external identity with a Keycloak account. There are two approaches:

• Automatic — Keycloak matches claims such as email with an existing account, then links them directly.
• Manual — the user is asked to log in to their local account first before the two accounts are linked, preventing account hijacking via a forged email address.

For security, the manual mechanism is stronger: without it, anyone controlling a Google account with another user's email address could hijack that account.

#User Profile Enrichment

Claims from the provider aren't only used to sign in — they can also enrich the user profile. Mappers fill attributes such as location, language, or avatar from provider data. But also pay attention to trust levels: data claimed by the provider isn't always verified. A email_verified claim from the provider must be treated differently from an email verified by Keycloak itself.

#Custom Identity Providers

Besides social providers, Keycloak supports custom identity providers:

• Generic OIDC provider — any provider implementing OpenID Connect; just fill in the authorization, token, and JWKS endpoints.
• Generic SAML provider — an external SAML IdP registered as a broker, flipping the roles from episode 13.
• Corporate IdP — a corporate identity portal only accessible from the internal network, connected as an authorization source.

This lets Keycloak become a federation hub: applications talk to a single Keycloak, while behind it Keycloak talks to Google, GitHub, corporate IdPs, and LDAP all at once.

#Aliases and Provider Keys

Every identity provider uses an alias that becomes part of the broker redirect URI, for example google, github, or corporate. This alias is also the identity Keycloak uses to link accounts: when a user is connected to more than one provider, Keycloak records each combination of alias and external identity.

For security, there are several habits to maintain:

• Store client_secret in a safe place — it's the credential linking Keycloak to the provider, equivalent to a password.
• Rotate credentials in the developer portal when there's an indication of a leak.
• Enable PKCE on providers that support it (e.g. OIDC) so the authorization code flow is more resistant to code misuse.
• Limit the providers allowed in production environments to business needs — not every realm needs Twitter.

client_id and client_secret entered into Keycloak should be taken directly from the developer portal, not copied through email or messages that could be intercepted.

#Closing

In this episode 16, you opened social login through identity brokering: the broker concept and the Identity Providers tab; Google, GitHub, Facebook, Microsoft, LinkedIn, and Twitter providers; creating an OAuth app with client ID, client secret, and redirect URIs; mapping scopes and attributes; the first broker login flow, account linking, and profile enrichment; plus custom OIDC and SAML identity providers.

Key takeaways:

• Brokering hands authentication to the provider while Keycloak still holds the session and profile.
• Redirect URIs must be exact — a single character difference triggers a redirect_uri_mismatch error.
• Automatic account linking needs care — verify email ownership before linking accounts.
• Custom OIDC and SAML providers make Keycloak a federation hub for all identity sources.

In the next episode (episode 17), we complete identity management from the provisioning side: SCIM — the REST protocol for creating, updating, and deleting users across systems automatically.