Identity Brokeringbeginner12 min readJune 12, 2026

Keycloak Google Identity Provider: Social Login Setup

Add Google as an identity provider in Keycloak so users can sign in with their Google account. Covers OAuth consent screen setup, client creation in Google Cloud Console, Keycloak IDP configuration, attribute mappers, and the first login flow.

KT

KeycloakPro Team

KeycloakPro Team

Introduction

When you add Google as an identity provider in Keycloak, users see a "Sign in with Google" button on your login page. They authenticate with Google, and Keycloak creates a federated account on their first login. Your application talks to Keycloak — Google stays behind the scenes.

Keycloak has a built-in Google provider type. You do not need a generic OIDC setup. Configuration takes about 10 minutes once you have a Google Cloud project.

How identity brokering works

The login flow goes: user clicks "Sign in with Google" → Keycloak redirects to Google → user authenticates → Google sends an authorization code back to Keycloak → Keycloak exchanges it for tokens → Keycloak creates or links a user account → user lands in your application.

Your application only ever talks to Keycloak. Google tokens stay inside Keycloak. The redirect URI you register in Google Cloud is Keycloak's broker endpoint:

https://keycloak.example.com/realms/YOUR_REALM/broker/google/endpoint

Prerequisites

  • Keycloak 24+ running on HTTPS
  • A Keycloak realm with admin access
  • A Google Cloud project (free to create at console.cloud.google.com)

Before creating credentials, Google requires an OAuth consent screen. This is what users see when they authorize your app.

In the Google Cloud Console:

  1. APIs & Services → OAuth consent screen
  2. User Type: External (anyone with a Google account) or Internal (Workspace users only)
  3. App name: your application name
  4. User support email: your support address
  5. Developer contact information: your email
  6. Click Save and Continue
Google Cloud Console OAuth consent screen configuration page showing User Type selection between Internal and External, App name field, and User support email field
External user type allows any Google account — Internal restricts to your Google Workspace organization

On the Scopes page, no additional scopes are needed. The email and profile scopes Keycloak requests are non-sensitive and don't require verification. Click through to the Summary.

1.1 — Add test users (External apps in Testing)

If you selected External and your app status is Testing, only users in the test user list can log in. Add any accounts you want to test with now.

Google Cloud Console OAuth consent screen Test users section showing an Add Users button and a text field for entering test user email addresses
In Testing mode, only these accounts can complete the Google login — move to Production when ready to accept all users

Step 2 — Create the OAuth 2.0 Client ID

  1. APIs & Services → Credentials → Create Credentials → OAuth client ID
  2. Application type: Web application
  3. Name: keycloak
  4. Authorized redirect URIs → Add URI: https://keycloak.example.com/realms/YOUR_REALM/broker/google/endpoint

Replace keycloak.example.com and YOUR_REALM with your values.

Click Create.

Google Cloud Console Create OAuth client ID page showing Web application type selected, a name field set to keycloak, and an Authorized redirect URIs field containing the Keycloak broker endpoint URL
The redirect URI must match exactly — no trailing slash, no HTTP if Keycloak runs on HTTPS

Google shows the Client ID and Client Secret in a popup. Copy both — you need them in the next step.

Google Cloud Console popup showing the newly created OAuth client ID and Client Secret with copy buttons next to each value
Copy these now — the secret is not shown again after you close this dialog

Step 3 — Add Google as an Identity Provider in Keycloak

In the Keycloak admin console:

  1. Select your realm
  2. Identity Providers → Add provider → Google
  3. Client ID: paste from Step 2
  4. Client Secret: paste from Step 2
  5. Default Scopes: leave as openid profile email (Keycloak sets this for the Google provider)

Click Add.

Keycloak admin console Identity Providers page showing the Google provider configuration with Client ID and Client Secret fields filled in and Default Scopes set to openid profile email
The built-in Google provider pre-fills the correct authorization, token, and userinfo URLs — no manual URL entry needed

3.1 — Optional: restrict to a Google Workspace domain

To allow only users from a specific Google Workspace domain (e.g., yourcompany.com), set the Hosted Domain field. Keycloak passes this as the hd parameter to Google, which rejects accounts from other domains.

Keycloak Google Identity Provider Advanced settings showing the Hosted Domain field set to yourcompany.com
Hosted Domain restricts login to one Google Workspace organization — leave blank to allow all Google accounts

Step 4 — Configure attribute mappers

Keycloak's built-in Google provider includes default mappers for the most common claims. Open Identity Providers → Google → Mappers to see them:

Google claimKeycloak user attribute
subExternal user ID (identity link)
emailemail
given_namefirstName
family_namelastName
picturepicture

These default mappers are active out of the box. If your application needs the user's picture URL stored in Keycloak's user attributes, add a mapper manually:

  1. Mappers → Add mapper
  2. Mapper type: Attribute Importer
  3. Name: picture
  4. Claim: picture
  5. User Attribute Name: picture
  6. Save
Keycloak Identity Provider Mapper creation form showing Attribute Importer type selected with Claim set to picture and User Attribute Name set to picture
Add this mapper only if your application uses the picture URL — most apps don't need it stored in Keycloak

Step 5 — Configure the First Login Flow

The First Login Flow controls what Keycloak does the first time a user logs in with Google.

In Identity Providers → Google → SettingsFirst Login Flow, the default is first broker login.

What the default flow does:

  • Prompts the user to review their profile (name, email) once
  • Checks if a Keycloak account already exists with the same email
  • If a match exists, offers account linking (user must verify the existing password)
  • If no match, creates a new Keycloak user linked to the Google identity

Sync Mode controls how Keycloak updates user attributes on subsequent logins:

  • import — copy attributes on first login only
  • force — overwrite Keycloak attributes with Google's values on every login

Use force if you want Google to stay the source of truth for name and email.

Keycloak Google Identity Provider Settings tab showing the First Login Flow dropdown set to first broker login and the Sync Mode dropdown set to import
The first broker login flow is the correct default — only change it if you have specific account-linking requirements

Step 6 — Test the login

Open a private browser window and go to your Keycloak realm login page or directly to your application. You should see a Sign in with Google button.

Keycloak login page showing the standard username and password form with a Sign in with Google button below
The Google button appears automatically after adding the identity provider — no template changes required

After completing Google's login:

  1. Google returns to Keycloak's broker endpoint
  2. Keycloak shows the review profile page (first login only)
  3. User lands in your application

Verify the federated account: Keycloak admin → Users → find the user → Identity Provider Links tab. You should see a Google entry with the user's sub as the external user ID.

Keycloak User detail page Identity Provider Links tab showing a Google row with the provider, provider username, and a Remove link button
The Identity Provider Links tab shows every external identity linked to this Keycloak account

Troubleshooting common issues

"redirect_uri_mismatch" from Google

The redirect URI Google received doesn't match any authorized URI in the OAuth client. Check the exact URI Keycloak sends — it is case-sensitive and path-sensitive. The correct format is:

https://keycloak.example.com/realms/YOUR_REALM/broker/google/endpoint

Copy this from Keycloak: Identity Providers → Google → Redirect URI field (shown in the settings panel).

"Access blocked: Authorization Error" from Google (app in Testing)

Your app's OAuth consent screen is in Testing mode and the Google account attempting login is not in the test users list. Add the account in APIs & Services → OAuth consent screen → Test users, or publish the app.

Users can log in but name and email are blank

The profile and email scopes are not being returned. Check that Default Scopes in Keycloak's Google IDP settings includes openid profile email. Also confirm the OAuth consent screen is configured — Google requires it before issuing profile claims.

Account linking dialog blocks first-time users

This appears when a Keycloak account already exists with the same email and account linking is configured in the first broker login flow. If you don't want users to link accounts, set the Review Profile authenticator to disabled and remove the Detect Existing Broker User step. For most setups, keeping the default is correct.

Login works in dev but fails in production

You added http://localhost:* to the redirect URIs during testing. Google's OAuth requires the production redirect URI to be explicitly listed. Add https://your-production-domain.com/realms/REALM/broker/google/endpoint to the client's authorized redirect URIs.

Production checklist

  • OAuth consent screen published (not in Testing mode) — required for external users
  • Production redirect URI registered in Google Cloud credentials
  • Client secret stored outside source control
  • Hosted Domain set if login should be restricted to a Workspace organization
  • Sync Mode chosen deliberately: import for Keycloak as source of truth, force for Google as source of truth
  • First Login Flow tested: new user, existing user with matching email, user without email
  • App review not required for email and profile scopes — only required for sensitive/restricted scopes

Need help integrating Google with Keycloak?

We deliver production-ready Google + Keycloak integrations in 1–3 weeks.

Fixed-price, zero vendor lock-in, full source code ownership.

See integration packages