Keycloak Social Login: Google, Apple, and GitHub Setup

Last updated: March 2026

Social login reduces friction for your users by letting them authenticate with accounts they already have. Instead of creating yet another username and password, users click “Sign in with Google” and they are in. Keycloak has built-in support for major social identity providers, making setup relatively straightforward.

This guide walks through configuring Google, Apple, and GitHub as social login providers in Keycloak, covering the provider-side credential setup, Keycloak admin console configuration, attribute mapping, and first-login flow customization.

Prerequisites

You need:

• A running Keycloak instance (version 24+) or a managed Keycloak cluster on Skycloak
• Admin access to the Keycloak admin console
• Developer accounts for Google Cloud Console, Apple Developer, and GitHub

All social login providers use OAuth 2.0 or OpenID Connect under the hood. If you want a deeper understanding of these protocols, our OAuth 2.0 visual guide covers the fundamentals.

Google OAuth Setup

Google is the most commonly configured social provider due to its large user base and straightforward setup process.

Step 1: Create Google OAuth Credentials

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Navigate to APIs & Services > Credentials
4. Click Create Credentials > OAuth client ID
5. If prompted, configure the OAuth consent screen first:
   • Choose External user type (unless this is for Google Workspace users only)
   • Fill in the application name, user support email, and developer contact email
   • Add scopes: openid, email, profile
   • Add test users if in testing mode
6. Back in Credentials, select Web application as the application type
7. Add the authorized redirect URI:

https://your-keycloak.example.com/realms/your-realm/broker/google/endpoint

Replace your-keycloak.example.com with your Keycloak hostname and your-realm with your realm name.

8. Copy the Client ID and Client Secret

Step 2: Configure Google in Keycloak

1. In the Keycloak admin console, go to your realm
2. Navigate to Identity Providers
3. Select Google from the provider list
4. Fill in the configuration:

Field	Value
Client ID	Your Google OAuth client ID
Client Secret	Your Google OAuth client secret
Enabled	ON
Trust Email	ON (Google verifies emails)
First Login Flow	first broker login
Sync Mode	import
Default Scopes	openid email profile

5. Click Save

Step 3: Verify the Redirect URI

The redirect URI shown in Keycloak should match what you configured in Google Cloud Console. The format is:

https://your-keycloak.example.com/realms/{realm}/broker/google/endpoint

Google-Specific Considerations

• Consent screen approval: For production use, you need to submit your OAuth consent screen for Google’s verification. Until approved, only test users can authenticate.
• Hosted domain restriction: If you want to limit Google login to users from a specific Google Workspace domain, add the hd parameter in the additional query parameters field:

hd=yourdomain.com

• Trust Email: Set this to ON for Google because Google verifies email addresses. This prevents users from needing to re-verify their email in Keycloak.

Apple Sign-In Setup

Apple Sign-In is more complex than other providers because Apple uses a different authentication approach with client secrets that are actually signed JWTs.

Step 1: Register with Apple Developer

1. Log in to your Apple Developer account
2. Navigate to Certificates, Identifiers & Profiles

Step 2: Register an App ID

1. Go to Identifiers and click the + button
2. Select App IDs and click Continue
3. Select App as the type
4. Enter a description and a Bundle ID (e.g., com.example.myapp)
5. Scroll down to Capabilities and check Sign In with Apple
6. Click Continue and then Register

Step 3: Create a Services ID

1. Go to Identifiers again and click +
2. Select Services IDs and click Continue
3. Enter a description and an identifier (e.g., com.example.myapp.auth)
4. Check Sign In with Apple and click Configure
5. In the configuration dialog:
   • Select your App ID as the Primary App ID
   • Add your domain (e.g., your-keycloak.example.com) to Domains and Subdomains
   • Add the return URL:

https://your-keycloak.example.com/realms/your-realm/broker/apple/endpoint

6. Click Save, then Continue, then Register

The Services ID identifier is your Client ID for Keycloak.

Step 4: Create a Key

1. Go to Keys and click +
2. Enter a name for the key
3. Check Sign In with Apple and click Configure
4. Select your App ID and click Save
5. Click Continue and then Register
6. Download the key file (.p8) immediately — Apple only lets you download it once
7. Note the Key ID shown on the page

Step 5: Configure Apple in Keycloak

Apple is available as a built-in identity provider in Keycloak 24+. Configure it in the admin console:

1. Go to Identity Providers and select Apple
2. Fill in the configuration:

Field	Value
Client ID	Your Services ID identifier (e.g., com.example.myapp.auth)
Client Secret	See below — Apple uses a signed JWT
Enabled	ON
Trust Email	OFF (Apple allows users to hide their email)
First Login Flow	first broker login
Default Scopes	name email

Step 6: Generate the Apple Client Secret

Apple does not use a static client secret. Instead, you generate a JWT signed with your private key. Here is a Node.js script to generate it:

const jwt = require("jsonwebtoken");
const fs = require("fs");

const privateKey = fs.readFileSync("AuthKey_XXXXXXXXXX.p8", "utf8");

const token = jwt.sign({}, privateKey, {
  algorithm: "ES256",
  expiresIn: "180d",
  audience: "https://appleid.apple.com",
  issuer: "YOUR_TEAM_ID",       // Found in Apple Developer account
  subject: "com.example.myapp.auth",  // Your Services ID
  keyid: "YOUR_KEY_ID",         // From Step 4
});

console.log(token);

This generates a client secret valid for 180 days. You will need to regenerate and update it before it expires.

Apple-Specific Considerations

• Email privacy: Apple allows users to hide their real email address and provides a relay address like [email protected]. Your application must be able to handle this.
• Name availability: Apple only sends the user’s name on the first authentication. If you miss capturing it, the user needs to revoke your app’s access in their Apple ID settings and re-authenticate.
• Secret rotation: Set a calendar reminder to regenerate the client secret before it expires (maximum 180 days).

GitHub OAuth Setup

GitHub OAuth is popular for developer-facing applications. The setup is straightforward.

Step 1: Create a GitHub OAuth App

1. Go to GitHub Developer Settings
2. Click OAuth Apps > New OAuth App
3. Fill in the registration form:

Field	Value
Application name	Your application name
Homepage URL	Your application’s URL
Authorization callback URL	https://your-keycloak.example.com/realms/your-realm/broker/github/endpoint

4. Click Register application
5. Copy the Client ID
6. Click Generate a new client secret and copy it

Step 2: Configure GitHub in Keycloak

1. In the admin console, go to Identity Providers and select GitHub
2. Fill in the configuration:

Field	Value
Client ID	Your GitHub OAuth App client ID
Client Secret	Your GitHub OAuth App client secret
Enabled	ON
Trust Email	ON (if you require email verification)
First Login Flow	first broker login
Default Scopes	user:email read:org

3. Click Save

GitHub-Specific Considerations

• Email visibility: Some GitHub users have their email set to private. Adding the user:email scope allows your app to access their primary email even when private. However, Keycloak may receive multiple email addresses from GitHub and will use the primary verified one.
• Organization access: If you want to restrict access to members of a specific GitHub organization, add the read:org scope and create a custom authenticator or first-login flow that checks organization membership.
• GitHub Apps vs. OAuth Apps: For more granular permissions and higher rate limits, consider using a GitHub App instead of an OAuth App. Keycloak works with both, but the configuration details differ slightly.

Attribute Mapping

Each social provider sends different attributes (claims) about the user. Keycloak maps these to its internal user model. You can customize these mappings.

Default Attribute Mappings

Keycloak Field	Google	Apple	GitHub
Username	Google ID	Apple ID	GitHub username
Email	email claim	email claim	Primary verified email
First Name	given_name	firstName (first login only)	name (parsed)
Last Name	family_name	lastName (first login only)	Not provided separately

Adding Custom Mappers

To map additional attributes, go to Identity Providers > [Provider] > Mappers and create new mappers:

1. Hardcoded Attribute Mapper: Set a fixed attribute value for all users from this provider (e.g., registration_source = google)

2. Attribute Importer: Map a claim from the provider’s token to a Keycloak user attribute

3. Hardcoded Role Mapper: Assign a default role to all users from this provider

Example: Map all Google users to a social-user role:

• Mapper Type: Hardcoded Role
• Role: social-user

For deeper coverage of attribute mapping patterns, see our guide on attribute mapping during OIDC identity brokering. For SAML-based identity providers, see the SAML attribute mapping guide.

Customizing the First-Login Flow

The first-login flow controls what happens when a user authenticates through a social provider for the first time. The default flow:

1. Reviews the profile information from the provider
2. Checks if a user with the same email already exists
3. If yes, links the social account to the existing user (after verification)
4. If no, creates a new user

Customizing the Flow

Navigate to Authentication > Flows and duplicate the “first broker login” flow to create a custom version. Common customizations include:

Skip the review profile page: If you trust the social provider’s data, you can remove the “Review Profile” execution to skip the profile confirmation step. This creates a smoother user experience.

Auto-link existing accounts: By default, Keycloak asks users to verify their identity before linking a social login to an existing account. If you trust email verification from the provider (like Google), you can configure automatic linking:

1. In your custom first-login flow, find the “Confirm Link Existing Account” and “Verify Existing Account by Re-authentication” executions
2. Replace them with “Automatically Set Existing User” set to ALTERNATIVE

Require email verification: For providers that do not verify emails, add a “Verify Email” execution to the flow.

After creating your custom flow, update the identity provider configuration to use it as the First Login Flow.

For more on building custom authentication flows, see our guide on building custom authentication flows.

Managing Multiple Social Providers

When you configure multiple social providers, the Keycloak login page shows buttons for each. Here are considerations for managing multiple providers:

Login Page Ordering

The order of identity provider buttons on the login page is controlled by the GUI Order field in each provider’s configuration. Set lower numbers to appear first.

Identity Provider Hints

You can bypass the login page entirely and send users directly to a specific provider using the kc_idp_hint parameter:

https://your-keycloak.example.com/realms/your-realm/protocol/openid-connect/auth
  ?client_id=your-client
  &response_type=code
  &scope=openid
  &redirect_uri=https://app.example.com/callback
  &kc_idp_hint=google

For more on using this parameter, see our post on using kc_idp_hint to choose identity providers.

Account Linking

Users should be able to link multiple social accounts to a single Keycloak account. Keycloak’s Account Management Console allows users to link and unlink social providers from their profile.

Testing Social Login

After configuring each provider, test the complete flow:

1. Open your application’s login page
2. Click the social login button
3. Authenticate with the social provider
4. Verify that the user is created in Keycloak with the correct attributes
5. Check that the JWT token contains the expected claims
6. Test the first-login flow by authenticating with a new account
7. Test account linking by authenticating with a social provider when a user with the same email already exists

Use the Skycloak JWT Token Analyzer to inspect the tokens issued after social login and verify that attribute mappings are correct.

Troubleshooting Common Issues

“Invalid redirect URI” Error

The redirect URI configured in the social provider must exactly match what Keycloak expects. Check:

• Protocol (https vs. http)
• Domain name
• Realm name in the path
• No trailing slash differences

Email Conflicts

If a user tries to log in with a social provider that returns an email already associated with another Keycloak account, the first-login flow determines the behavior. The default flow asks the user to link accounts, which may confuse users who do not realize they have an existing account.

Missing User Attributes

If user attributes are not populated after social login:

• Check the provider’s scopes (e.g., profile scope for Google)
• Verify attribute mappers are configured correctly
• For Apple, remember that name is only sent on the first authentication

Token Issues

If tokens do not contain expected claims after social login, verify that the identity provider mappers are configured to include the social provider’s attributes in the Keycloak token.

Security Considerations

When configuring social login, keep these security practices in mind:

• Always use HTTPS for your Keycloak instance and redirect URIs
• Enable PKCE on your OIDC clients to prevent authorization code interception
• Review default scopes and only request what you need from each provider
• Monitor authentication events through audit logs to detect unusual social login patterns
• Set up multi-factor authentication as an additional step after social login for sensitive applications
• Rotate client secrets regularly, especially for Apple Sign-In where secrets expire

For a comprehensive security posture, review our security practices page.

Conclusion

Social login with Google, Apple, and GitHub removes registration friction and leverages identity verification from trusted providers. Keycloak’s built-in support for these providers makes configuration relatively straightforward, though Apple requires extra steps due to its JWT-based client secret approach. The Keycloak identity broker documentation covers the full range of supported social providers and configuration options.

The key to a smooth social login experience is proper attribute mapping, a well-configured first-login flow, and thorough testing of edge cases like email conflicts and account linking.

If you want to get social login running quickly on a production-ready Keycloak cluster, Skycloak’s managed hosting provides pre-configured environments where you can focus on identity provider setup instead of infrastructure. Visit our pricing page to explore plans, or check the documentation for detailed configuration guides.