Social Login
What is social login?
Section titled “What is social login?”Social login lets your users authenticate with a provider they already have an account with — Google, GitHub, Facebook, Apple, and many others — instead of creating a new username and password in your realm. Under the hood, Keycloak acts as an identity broker: it redirects the user to the chosen provider, the provider authenticates them, and Keycloak accepts the resulting token. Your application never interacts with the external provider directly.
Keycloak ships with built-in connectors for the most common social providers. Each connector is called an identity provider (IdP) in the admin console.
Step 1 — obtain credentials from the provider
Section titled “Step 1 — obtain credentials from the provider”Before you configure anything in Keycloak you need an OAuth2 client registered at the provider. The exact steps differ by provider, but the pattern is always the same.
For Google:
- Go to console.cloud.google.com and create or select a project.
- Navigate to APIs & Services → Credentials → Create Credentials → OAuth client ID.
- Set the application type to Web application.
- In the Authorised redirect URIs field, enter Keycloak’s broker endpoint for your realm (see Step 2 below).
- Click Create. Note the Client ID and Client secret.
For GitHub:
- Go to GitHub → Settings → Developer settings → OAuth Apps → New OAuth App.
- Set the Authorization callback URL to Keycloak’s broker endpoint (see Step 2 below).
- Click Register application. Note the Client ID and generate a Client secret.
Step 2 — find the redirect URI to register with the provider
Section titled “Step 2 — find the redirect URI to register with the provider”Keycloak exposes a fixed broker endpoint for each identity provider alias. You must register this URI with the external provider — it is where the provider sends the user back after authentication.
The URI follows this pattern:
https://<keycloak-host>/realms/<realm>/broker/<alias>/endpointFor example, if your Keycloak runs at https://auth.example.com, your realm is my-app, and you will use the alias google, the redirect URI is:
https://auth.example.com/realms/my-app/broker/google/endpointRegister this URI exactly as shown in the provider’s developer console. A mismatch — even a trailing slash difference — will cause the social login to fail with a redirect URI mismatch error.
Step 3 — add the identity provider in Keycloak
Section titled “Step 3 — add the identity provider in Keycloak”- Open the Keycloak admin console and switch to your target realm.
- Click Identity providers in the left sidebar.
- Click Add provider and select Google (or GitHub, or any other listed provider).
- Keycloak pre-fills the Alias (e.g.,
google). Leave it unless you have a naming reason to change it. - Paste the Client ID from Step 1 into the Client ID field.
- Paste the Client secret from Step 1 into the Client secret field.
- Leave all other settings at their defaults for now.
- Click Save.
Step 4 — test the social login
Section titled “Step 4 — test the social login”- Open your realm’s login page:
https://<keycloak-host>/realms/<realm>/account. - You should see a new button — “Log in with Google” or “Sign in with GitHub” — below the username/password form.
- Click the button. You will be redirected to the external provider’s login page.
- Authenticate with the external provider. You will be redirected back to Keycloak, and Keycloak will create a federated user in your realm (or link to an existing one via the first-login flow).
Provider alias and the login button
Section titled “Provider alias and the login button”The alias you set in Step 3 appears in the broker endpoint URI and also controls the display on the login page. Keycloak uses the alias to route the callback back to the correct IdP configuration. If you rename or delete an IdP, existing federated user links that reference the old alias will break — users will not be able to log in via that provider until the link is updated.
Trade-offs
Section titled “Trade-offs”| Option | Benefit | Cost |
|---|---|---|
| Identity brokering as a central hub (Keycloak manages all social login) | Manages credentials, redirect URIs, and token exchange in one place; adding a new provider needs no application change | You must maintain each IdP’s configuration in Keycloak, and every app depends on Keycloak as a single point of failure |
| Each app embeds its own social-login SDK (e.g. the Google Sign-In SDK directly in each app) | Finer control over the login button’s UX, with no dependency on Keycloak | The team must maintain the OAuth client and SDK separately in every app; changing provider means changing many places |
Common mistakes
Section titled “Common mistakes”- Using the same Google OAuth client across dev/staging/prod — create a separate OAuth client per environment, because redirect URIs differ, and if the same client leaks in a less-secure environment (e.g. dev) it affects prod too.
- Forgetting to set the redirect URI to match exactly what Keycloak exposes — even an extra trailing slash makes social login fail with a redirect URI mismatch; copy the pattern from the setup step directly.
- Not checking the first-login flow before enabling social login for real — if account linking isn’t configured correctly, a user who already has an account may unknowingly end up with a duplicate.
Real-world example
An app with a “Log in with Google” or “Log in with GitHub” button — this is identity brokering running in production right now: the app never sees the Google or GitHub credential at all, it only receives the token Keycloak issues after brokering completes.
A startup that grew from one app to many — each app originally embedded its own Google SDK; after moving to Keycloak as a central broker, adding a new provider (e.g. Sign in with Apple) is a one-time change in Keycloak, and every app gets it immediately with no redeploy.