Keycloak Social Login: Add Google and GitHub OAuth (2026)

Keycloak social login isn’t just about convenience; it’s a sophisticated delegation system where Keycloak acts as a trusted intermediary, allowing users to leverage existing credentials without exposing them.

Let’s see how this plays out with Google and GitHub. Imagine a user landing on your app. Instead of creating a new account, they see "Login with Google" or "Login with GitHub." Clicking "Login with Google" initiates a flow. Your app redirects the user to Google’s login page, where they authenticate. Google then sends a token back to Keycloak, confirming the user’s identity. Keycloak, in turn, creates or links a user account within its own system and issues a token to your application. Your app then uses this token to recognize the user.

Here’s a breakdown of the setup and the underlying mechanics:

1. Setting up Keycloak as an OAuth/OpenID Connect Provider

This is the foundation. Keycloak itself needs to be configured to speak the language of social logins.

Realm Creation: If you don’t have one, create a realm in Keycloak. This isolates your application’s users, clients, and configurations.
Client Configuration: For your application, you’ll create a "Client" within the realm. This client represents your application to Keycloak.
- Client ID: A unique identifier for your application (e.g., my-app-frontend).
- Access Type: Set to confidential for server-side applications or public for single-page applications (SPAs) or mobile apps.
- Valid Redirect URIs: Crucially, add the exact URIs where Keycloak should redirect the user after successful authentication. For example, http://localhost:3000/callback or https://myapp.com/auth/callback. This prevents token leakage.
- Web Origins: If using SPAs, add the origins from which your application will be accessed (e.g., http://localhost:3000).

2. Configuring Identity Providers (Google & GitHub)

This is where you tell Keycloak how to talk to Google and GitHub.

Navigate to Identity Providers: In your Keycloak realm, go to "Identity Providers" and click "Add provider."
Select "OpenID Connect v1.0" or "OAuth 2.0": Both Google and GitHub support these protocols. OpenID Connect (OIDC) is generally preferred as it adds an identity layer on top of OAuth 2.0, providing user profile information.

For Google:

Alias: A short, unique name (e.g., google).
Display Name: What the user sees on the login button (e.g., "Login with Google").
Client ID: Obtain this from the Google Cloud Console. You’ll need to create an OAuth 2.0 client ID for your web application.
Client Secret: Also obtained from the Google Cloud Console. Keep this confidential.
Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
Token URL: https://oauth2.googleapis.com/token
User Info URL: https://www.googleapis.com/oauth2/v3/userinfo
Scopes: Request necessary scopes, like openid email profile. This determines what user information Google shares.

For GitHub:

Alias: e.g., github.
Display Name: e.g., "Login with GitHub".
Client ID: Obtain this from GitHub’s OAuth Apps settings. You’ll register a new OAuth App for your application.
Client Secret: Also from GitHub’s OAuth Apps settings.
Authorization URL: https://github.com/login/oauth/authorize
Token URL: https://github.com/login/oauth/access_token
User Info URL: https://api.github.com/user
Scopes: Request read:user and user:email for basic user information.

3. The User Flow in Action

User Clicks Social Login: On your application’s login page, the user clicks "Login with Google."
Redirect to Social Provider: Your app redirects the user to Keycloak, specifying the desired identity provider (e.g., ?client_id=my-app-frontend&redirect_uri=...&scope=openid%20email%20profile&response_type=code&state=...&kc_idp_hint=google). Keycloak then redirects the user to Google’s authorization server.
User Authenticates with Google: The user logs into their Google account and approves the requested permissions.
Google Redirects to Keycloak: Google sends an authorization code back to Keycloak’s redirect URI.
Keycloak Exchanges Code for Tokens: Keycloak uses the authorization code, its client ID, and client secret to request an access token and ID token from Google’s token endpoint.
Keycloak Validates and Fetches User Info: Keycloak validates the ID token and uses the access token to fetch user information from Google’s user info endpoint.
Keycloak Creates/Links User: Based on the fetched user information (e.g., email, Google ID), Keycloak either creates a new user in its realm or links the social login to an existing user account.
Keycloak Issues its Own Token: Keycloak generates its own access token and ID token for your application, containing information about the authenticated user within your Keycloak realm.
Redirect Back to Your App: Keycloak redirects the user back to your application’s specified redirect URI, including the authorization code.
Your App Exchanges Code for Keycloak Tokens: Your application, using its client ID and secret, exchanges this code with Keycloak’s token endpoint to get the Keycloak access and ID tokens.
Application Grants Access: Your application validates the Keycloak token and logs the user in.

The Counterintuitive Truth: The "secret" in "client secret" for social providers is less about keeping your Keycloak configuration hidden and more about proving to the social provider (Google/GitHub) that Keycloak is a legitimate client authorized to act on behalf of your application. Keycloak uses this secret to exchange authorization codes for access tokens.

The next hurdle is managing user sessions across your application and Keycloak, often involving refresh tokens and single sign-out.