Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Identity Brokering and Social Login

Social Login with Google and GitHub

Set up Google and GitHub social login in Keycloak: create the OAuth app, copy the redirect URI, enter client ID and secret, map attributes, and debug failures.

Social login lets visitors sign in with an account they already own. In Keycloak it is the simplest form of identity brokering: the provider type already knows the endpoints, so you only supply a client ID and secret. This lesson walks through Google and GitHub, the two most common choices, and then covers the settings and failure modes that apply to every social provider.

Provider consoles change their layout often. The steps below name the fields you need, not exact button positions. Keycloak itself cannot run on this site, so the code samples are stand-ins that illustrate the checks involved.

The recipe for any social provider

Every social login follows the same four steps:

  1. In the provider's developer console, create an OAuth application (a client).
  2. Copy the redirect URI from Keycloak and paste it into the provider.
  3. Copy the provider's client ID and client secret into Keycloak.
  4. Test with a real account and adjust mappers and flows.

In Keycloak, open your realm, choose Identity providers in the left menu, and click the provider card (Google, GitHub, Facebook, Microsoft, and others are built in). The add form shows a read-only Redirect URI field, for example https://auth.example.com/realms/demo/broker/google/endpoint. Copy it before you leave the page.

Google

In Google Cloud Console, you configure the OAuth consent screen, then create credentials of type OAuth client ID with application type Web application. Add the Keycloak redirect URI under Authorized redirect URIs. Google then shows a client ID and a client secret. Back in Keycloak, paste both into the Google provider form and save.

Practical notes:

  • Google only accepts redirect URIs that use https, apart from localhost during development. A plain-HTTP staging server will fail.
  • An unverified consent screen limits how many users can sign in; plan for the review if you go public.
  • Google returns a verified email (email_verified), so Trust Email is reasonable here. Even so, decide deliberately.
  • The Hosted domain option restricts logins to one Google Workspace domain, for example example.com.

GitHub

In GitHub, open Settings, Developer settings, OAuth Apps, and register a new application. The Authorization callback URL is the Keycloak redirect URI. After creating it, generate a client secret. GitHub shows the client ID and the secret on the app page.

Notes specific to GitHub:

  • GitHub is OAuth 2.0 with its own user API rather than full OIDC. Keycloak's built-in provider handles that for you.
  • A GitHub account can have several emails and any of them may be unverified, so be careful with Trust Email and automatic linking.
  • The default scope is user:email. Add more scopes only if you really need them.
  • Each OAuth app takes one callback URL. Use separate apps for development and production.

Inspect the redirect

The provider will reject a callback that does not match exactly what you registered. This stand-in lets you test candidate URIs against the registered list, which is the same exact-match rule providers apply:

JS Stand-in: exact-match redirect URI check

Press Run (or Ctrl + Enter) to see the console output here.

No output.

State: protection against forged callbacks

When Keycloak redirects the user to Google, it includes a random state value and remembers it. When the callback arrives, Keycloak checks that the returned state matches the one it created for that browser session. This blocks attackers from pushing a forged callback onto a victim's browser (a login CSRF). You do not configure this: it is built in. But the same pattern is what your own app should do when it talks to Keycloak.

JS Stand-in: state generation and verification

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Attribute import and mappers

After the first login, Keycloak creates a user from the provider's profile. Built-in mappers copy common attributes: email, first name, last name, and username. You can add more under the provider's Mappers tab, with types such as Attribute Importer, Hardcoded Role, Hardcoded Attribute, and Username Template Importer. The next lessons show mappers in detail for generic OIDC and SAML providers.

The default username for GitHub users is the GitHub login. Because usernames must be unique inside a realm, two providers can clash. A Username Template Importer such as ${ALIAS}.${CLAIM.preferred_username} avoids that.

Showing and ordering buttons

Under the provider's Settings you can set a Display order and a Display name. The login theme draws one button per enabled provider, with the icon matching the alias if the theme has one. Hiding a button (Hide on login page) is useful when you only want the provider available through kc_idp_hint.

Troubleshooting

Symptom Likely cause
"redirect_uri_mismatch" at the provider Registered URI differs by scheme, host, path, or trailing slash
"Invalid client secret" or 401 from the token endpoint Secret was regenerated, copied with whitespace, or belongs to another app
Loop back to the login page Cookies blocked, or Keycloak behind a proxy that rewrites the host
"Unexpected error when authenticating with identity provider" Keycloak log shows the real reason: raise the log level of org.keycloak.broker temporarily
Duplicate account prompt for every user First login flow is verifying existing accounts, as designed

Never commit provider client secrets to a repository. In production, store them in the Keycloak vault or inject them through your secrets manager, and rotate them when staff leave.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where do you get the redirect URI to register at Google or GitHub?

    Keycloak shows the broker endpoint URI for each provider alias; copy it exactly into the provider's OAuth app.
  2. 2. A provider answers redirect_uri_mismatch. What should you check first?

    Providers use strict comparison, so any difference in scheme, host, path, or trailing slash causes the error.
  3. 3. What is the purpose of the state parameter?

    Keycloak compares the returned state with the stored one to reject forged or replayed callbacks.
  4. 4. Why use a Username Template Importer mapper?

    Prefixing the provider alias keeps usernames unique when different providers can return the same login name.

Summary

  • Social login needs an OAuth app at the provider, the Keycloak redirect URI, and the client ID and secret.
  • Google gives a verified email; GitHub emails need care.
  • Redirect URIs match exactly; state protects the callback.
  • Mappers and templates control which attributes and usernames end up in Keycloak.
  • Keep secrets out of source control.

Next: External OIDC and SAML Providers