Tutorials
Setting Up Social Login

Setting Up Social Login

Social login lets your users sign in with accounts they already have (like Google or GitHub) instead of creating new passwords. This guide shows you how to add Google login to your application - it’s the most popular choice and works great for most applications.

What You’ll Learn

  • How to set up Google OAuth for your application
  • How to configure Keycloak to use Google as an identity provider
  • How to test social login
  • Best practices for social authentication

Why Use Social Login?

Benefits for your users:

  • No new passwords to remember
  • Faster registration and login
  • Trust in familiar login screens
  • Automatic profile information

Benefits for you:

  • Reduced support requests (“I forgot my password”)
  • Higher conversion rates
  • Less user data to manage and secure
  • Built-in email verification

Prerequisites

  • A working Keycloak cluster (see First Application Setup)
  • A Google account
  • Basic understanding of Keycloak realms and clients

Step 1: Create Google OAuth Credentials

Go to Google Cloud Console

  1. Visit Google Cloud Console
  2. Sign in with your Google account
  3. Create a new project (or select existing one):
    • Click the project dropdown (top left)
    • Click “New Project”
    • Name it “My App Authentication” (or similar)
    • Click “Create”

Enable Google+ API

  1. Go to “APIs & Services” > “Library” (left sidebar)
  2. Search for “Google+ API”
  3. Click on it and click “Enable”
ℹ️
Note: Even though Google+ is discontinued, the API is still used for authentication and profile information.

Create OAuth 2.0 Credentials

  1. Go to “APIs & Services” > “Credentials”

  2. Click “Create Credentials” > “OAuth 2.0 Client ID”

  3. Configure the consent screen (if prompted):

    • Choose “External” for most applications
    • Fill in required fields:
      • App name: “My Application”
      • User support email: Your email
      • Developer contact: Your email
    • Click “Save and Continue”
    • Skip scopes for now
    • Add test users if needed
    • Click “Save and Continue”

  4. Create the OAuth client:

    • Application type: “Web application”
    • Name: “My App Keycloak”
    • Authorized redirect URIs: We’ll add this in a moment
    • Click “Create”

Get Your Credentials

After creating the client, you’ll see:

  • Client ID: Something like 123456789-abc123.apps.googleusercontent.com
  • Client Secret: A random string like ABC123-def456

Keep these safe! You’ll need them for Keycloak configuration.

Step 2: Configure Keycloak Identity Provider

Add Google Identity Provider

  1. Open your Keycloak admin console
  2. Make sure you’re in the correct realm (not “master”)
  3. Go to “Identity Providers” (left sidebar)
  4. Click “Google” from the list of providers

Configure Google Settings

Fill in the configuration form:

Basic Settings:

  • Alias: google (this creates the URL path)
  • Display Name: Google (what users see on the login page)
  • Client ID: Paste your Google Client ID
  • Client Secret: Paste your Google Client Secret

Advanced Settings (recommended):

  • Default Scopes: openid profile email
  • Store Tokens: ON (allows users to link/unlink accounts later)
  • Trust Email: ON (trusts that Google has verified the email)

Click “Save”

Copy the Redirect URI

After saving, you’ll see a “Redirect URI” field with a URL like:

https://your-cluster.skycloak.io/realms/your-realm/broker/google/endpoint

Copy this URL - you need to add it to Google.

Step 3: Update Google Configuration

Add Redirect URI to Google

  1. Go back to Google Cloud Console
  2. Navigate to “APIs & Services” > “Credentials”
  3. Click on your OAuth 2.0 Client
  4. Add the Keycloak redirect URI to “Authorized redirect URIs”
  5. Click “Save”
⚠️
Important: The redirect URI must match exactly. Make sure there are no extra spaces or characters.

Step 4: Test Social Login

Create a Test Application

If you haven’t already, create a simple test application (you can use the one from the First Application Setup guide).

Test the Login Flow

  1. Open your application

  2. Click the login button

  3. You should now see two options:

    • Username/password form
    • “Google” button

  4. Click “Google”

  5. You’ll be redirected to Google’s login page

  6. Sign in with your Google account

  7. Grant permissions when prompted

  8. You should be redirected back to your application, now logged in!

What Happens Behind the Scenes

  1. User clicks “Google” in your app
  2. Keycloak redirects to Google’s authorization server
  3. User signs in to Google and grants permissions
  4. Google redirects back to Keycloak with an authorization code
  5. Keycloak exchanges the code for tokens from Google
  6. Keycloak creates a local user account (if first time)
  7. Keycloak issues its own tokens and redirects to your app
  8. Your app receives the tokens and logs the user in

Step 5: Customize the Social Login Experience

Customize the Login Page

Add a Logo:

  1. Go to “Realm Settings” > “Themes”
  2. Upload a custom logo or use Skycloak’s branding features
  3. The Google button will appear with your custom styling

Customize Button Text:

  1. Go to “Identity Providers” > “Google”
  2. Change “Display Name” to customize the button text
  3. Examples: “Sign in with Google”, “Continue with Google”

Configure User Information

Map Google Profile to Keycloak:

  1. Go to “Identity Providers” > “Google” > “Mappers”
  2. Add built-in mappers for common fields:
    • First Name: given_name
    • Last Name: family_name
    • Email: email
    • Profile Picture: picture

Create Custom Mappers:

Mapper Type: Attribute Importer
Name: Google Profile Picture
Social Profile JSON Field Path: picture
User Attribute Name: picture_url

Step 6: Handle User Account Linking

Account Linking Strategies

Automatic Linking (Recommended):

  • Links accounts with the same email address automatically
  • Enabled by default when “Trust Email” is ON
  • Works well for most applications

Manual Linking:

  • Users can link accounts in their account console
  • More control but requires user action
  • Good for high-security applications

Configure Account Linking

  1. Go to “Identity Providers” > “Google”
  2. Set “Link Only”: OFF (allows new account creation)
  3. Set “Trust Email”: ON (enables automatic linking)
  4. Set “First Login Flow”: Review the flow settings

Advanced Configuration

Add Multiple Social Providers

You can add multiple social login options:

GitHub (Great for Developer Tools):

  1. Create OAuth app at github.com/settings/developers
  2. Add GitHub identity provider in Keycloak
  3. Configure redirect URI

Microsoft (Good for Business Apps):

  1. Register app in Azure AD
  2. Add Microsoft identity provider
  3. Configure enterprise features

Facebook (For Consumer Apps):

  1. Create app at developers.facebook.com
  2. Add Facebook identity provider
  3. Configure app review for production

Security Considerations

Email Verification:

  • Social providers usually verify emails
  • Set “Trust Email” to ON for major providers
  • Consider additional verification for sensitive apps

Account Protection:

  • Enable account linking protection
  • Consider requiring additional authentication for sensitive actions
  • Monitor for suspicious login patterns

Data Privacy:

  • Review what data you request from social providers
  • Only request necessary permissions
  • Comply with privacy regulations (GDPR, CCPA)

Troubleshooting

Common Issues

“Invalid Redirect URI” Error:

  • Check that the redirect URI in Google matches exactly
  • Make sure your Keycloak URL is correct
  • Verify HTTPS is used in production

“Client ID Not Found” Error:

  • Double-check the Client ID in Keycloak
  • Make sure the Google project is enabled
  • Verify the Google+ API is enabled

Users Can’t Link Accounts:

  • Check “Trust Email” setting
  • Verify email addresses match between accounts
  • Review first login flow configuration

Social Login Button Doesn’t Appear:

  • Make sure the identity provider is enabled
  • Check that it’s configured for the correct realm
  • Verify your application is using the correct realm

Testing Tips

Use Different Browsers:

  • Test with different Google accounts
  • Clear cookies between tests
  • Try both new user registration and existing user login

Check Logs:

  • Review Keycloak server logs for detailed error messages
  • Use browser developer tools to see network requests
  • Enable debug logging for identity providers

Production Considerations

Google OAuth Verification

For production applications, you may need to verify your OAuth app with Google:

  1. Complete the OAuth consent screen with all required information
  2. Add privacy policy and terms of service URLs
  3. Submit for verification if you request sensitive scopes
  4. This can take several days, so plan accordingly

Rate Limits and Quotas

  • Google has rate limits on OAuth requests
  • Monitor your usage in Google Cloud Console
  • Consider caching user profile information
  • Implement proper error handling for rate limit responses

Monitoring and Analytics

  • Track social login adoption rates in the Insights dashboard
  • Monitor conversion rates compared to email/password
  • Use Skycloak’s analytics to understand user behavior

Best Practices

User Experience

Clear Communication:

  • Explain what data you’ll access from their Google account
  • Show privacy policy and terms of service
  • Provide alternative login methods

Smooth Onboarding:

  • Pre-fill forms with social profile data
  • Skip email verification if email is trusted
  • Guide users through any required additional setup

Technical Implementation

Error Handling:

  • Handle cases where users deny permissions
  • Provide fallback options for authentication failures
  • Show clear error messages for configuration issues

Testing:

  • Test with multiple Google accounts
  • Verify account linking works correctly
  • Test both new user registration and returning user login

Next Steps

Now that you have Google login working:

  1. Add more providers: Try GitHub, Microsoft, or Facebook
  2. Customize the experience: Brand your login pages
  3. Secure your application: Set up multi-factor authentication
  4. Monitor usage: Use Skycloak’s analytics to track adoption

Related Guides

Remember: Social login is about making things easier for your users while maintaining security. Start with one provider (Google is usually the best choice) and add more based on your users’ needs!

Understanding Keycloak BasicsEmail Theme Customization Guide