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.
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)
Step 1 — Configure the OAuth consent screen
Before creating credentials, Google requires an OAuth consent screen. This is what users see when they authorize your app.
In the Google Cloud Console:
- APIs & Services → OAuth consent screen
- User Type: External (anyone with a Google account) or Internal (Workspace users only)
- App name: your application name
- User support email: your support address
- Developer contact information: your email
- Click Save and Continue

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.

Step 2 — Create the OAuth 2.0 Client ID
- APIs & Services → Credentials → Create Credentials → OAuth client ID
- Application type: Web application
- Name:
keycloak - 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 shows the Client ID and Client Secret in a popup. Copy both — you need them in the next step.

Step 3 — Add Google as an Identity Provider in Keycloak
In the Keycloak admin console:
- Select your realm
- Identity Providers → Add provider → Google
- Client ID: paste from Step 2
- Client Secret: paste from Step 2
- Default Scopes: leave as
openid profile email(Keycloak sets this for the Google provider)
Click Add.

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.

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 claim | Keycloak user attribute |
|---|---|
sub | External user ID (identity link) |
email | |
given_name | firstName |
family_name | lastName |
picture | picture |
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:
- Mappers → Add mapper
- Mapper type: Attribute Importer
- Name:
picture - Claim:
picture - User Attribute Name:
picture - Save

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 → Settings → First 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 onlyforce— 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.

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.

After completing Google's login:
- Google returns to Keycloak's broker endpoint
- Keycloak shows the review profile page (first login only)
- 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.

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:
importfor Keycloak as source of truth,forcefor Google as source of truth - First Login Flow tested: new user, existing user with matching email, user without email
- App review not required for
emailandprofilescopes — 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.