Social Login Implementation: Step-by-Step Guide (2026)

Last updated: July 2026

Social login lets users sign in to your app with an account they already have at Google, GitHub, or Microsoft instead of creating yet another password. Under the hood it runs on OAuth authentication: your identity provider (Keycloak in this guide) redirects the user to the social provider, verifies the identity that comes back, and then issues its own tokens to your applications. This guide walks both sides of that handshake: the provider consoles and the Keycloak broker config, plus the two parts most tutorials skip entirely, duplicate email account linking and claim mappers.

What is social login, really?

Social login is delegated sign-in. Instead of asking users to invent and remember a password for your app, you let them authenticate with a provider they already trust. Your app never sees their Google or GitHub password. It receives proof of identity after the provider has done the verifying.

The case for it is mostly about friction. Passwords are the single worst-performing input in web forms: Zuko’s form analytics found password fields have the highest mean abandonment rate of any form field, at 10.5% (Zuko). Every password field you remove is a drop-off point you no longer pay for.

Keycloak 26.x ships with built-in social providers for Bitbucket, Facebook, GitHub, GitLab, Google, Instagram, LinkedIn, Microsoft, OpenShift 4, PayPal, Stack Overflow, and Twitter (Keycloak Server Administration Guide). Anything not on that list can still be wired up as a generic OpenID Connect or SAML provider, because Keycloak treats social login as a special case of a more general mechanism: identity brokering.

New to Keycloak itself? Start with our complete guide to Keycloak, then come back. Everything below assumes you have a running realm.

How does OAuth authentication work with an identity broker?

Here’s the mental model that makes the rest of this guide click: Keycloak delegates authentication to the social provider, but remains the token issuer for your applications. Google confirms who the user is. Keycloak decides what tokens your apps get.

The flow, end to end:

1. The user clicks “Sign in with Google” on the Keycloak login page.
2. Keycloak redirects to Google’s authorization endpoint using its own client ID (the one you’ll register in Step 1).
3. The user authenticates with Google and approves the requested scopes.
4. Google redirects back to Keycloak’s broker endpoint with an authorization code.
5. Keycloak exchanges the code for tokens, validates them, and maps the identity onto a local user.
6. Keycloak issues its own tokens to your application, exactly as it would after a password login.

This is why brokering beats integrating each provider directly into your app. Your code trusts one issuer, Keycloak, and one token format. Adding LinkedIn or removing Twitter later is a console change, not a deploy. The full brokering model is documented in the Keycloak identity broker docs.

One design decision to make early: by default, Keycloak creates a local user record for every social user who signs in. Whether that local record should be your source of truth, or just a shadow of the provider’s, is a real architectural question. We wrote up the tradeoffs in Keycloak shadow accounts: broker vs identity store.

Step 1: Create OAuth credentials in each provider console

Every provider wants the same three things from you: an app registration, a redirect URI, and in return it hands you a client ID and secret. The redirect URI is the piece people get wrong, so let’s settle it now. Keycloak’s broker callback always follows this pattern:

https://<keycloak-host>/realms/<realm>/broker/<alias>/endpoint

The alias is whatever you name the provider inside Keycloak (typically google, github, microsoft). Keycloak displays the exact generated value when you add the provider in Step 2, but since the format is predictable, you can fill it in during provider setup and skip a round trip between consoles.

Google

1. In the Google Cloud Console, create OAuth credentials (an OAuth client ID) for your project.
2. Choose the Web application type.
3. Paste the Keycloak broker URI into Authorized redirect URIs.
4. Copy the client ID and client secret somewhere safe.

Google’s is the most standard setup of the three because it’s plain OpenID Connect. Keycloak’s Google provider requests openid profile email by default, which covers the identity claims you actually need.

GitHub

1. In GitHub, create a new OAuth App under Developer settings.
2. Paste the Keycloak broker URI into Authorization callback URL.
3. Generate a client secret and copy both values.

One honest wrinkle: GitHub itself recommends GitHub Apps over OAuth Apps, because GitHub Apps use fine-grained permissions and short-lived tokens, and only GitHub Apps can refresh user access tokens (GitHub Docs). For plain social sign-in, though, an OAuth App is the simpler default, and it’s what Keycloak’s built-in GitHub provider expects. The default scope is user:email, which lets Keycloak read the user’s email addresses.

Microsoft

1. Go to entra.microsoft.com, then App registrations, then New registration.
2. For supported account types, pick the option that covers any Entra ID tenant plus personal Microsoft accounts. That’s the one you want for consumer-facing login; the narrower options lock you to specific organizations.
3. Under platform, choose Web and paste the Keycloak broker URI.
4. Create a client secret under Certificates & secrets. Copy the secret Value, not the secret ID. Everyone confuses these exactly once.

Keycloak’s Microsoft provider talks to the login.microsoftonline.com/{tenant}/oauth2/v2.0/* endpoints, with the tenant defaulting to common, which accepts both organizational and personal accounts. The default scope is User.read, resolved through Microsoft Graph.

Step 2: Add the provider in Keycloak

Now the easy half. In the Admin Console, go to Identity Providers, click Add provider, and pick Google, GitHub, or Microsoft from the list.

Keycloak immediately shows the generated Redirect URI at the top of the form: /realms/{realm}/broker/{alias}/endpoint. If you guessed the alias correctly in Step 1, it matches what you already pasted into the provider console. If not, update the provider console now; a mismatched redirect URI is the number one cause of “this worked yesterday” broker errors.

Then:

1. Paste the Client ID and Client Secret from the provider console.
2. Save.

That’s genuinely it for the happy path. Here’s what each built-in provider requests by default:

Test it in a private browser window: your realm’s login page now shows a button per configured provider. Sign in through one, and Keycloak creates a local user linked to that provider identity.

If you’re on managed Keycloak, none of this changes. Skycloak’s social login and identity provider features are stock Keycloak brokering under the hood, so nothing in this guide is proprietary, and nothing you configure here locks you in.

Step 3: Handle duplicate emails and account linking

This is the step every quickstart skips, and it’s where production deployments actually break. The scenario: Jane registered with a password using [email protected] months ago. Today she clicks “Sign in with Google”, and her Google account uses the same address. One email, two identities. What should happen?

Keycloak’s default answer is deliberately cautious: it will not silently merge them. The First login flow (named “first broker login” by default) runs a chain of authenticators whenever a brokered user signs in for the first time:

When Create User If Unique finds a duplicate email, it hands off to the Handle Existing Account sub-flow: the user confirms they want to link, then proves they own the existing account, either by clicking an emailed link or by entering their existing password. Note the SMTP dependency: Verify Existing Account By Email requires a working SMTP setup in your realm, so configure email before you launch social login, or your users will only get the re-authentication path.

Want linking to happen silently, with no confirmation screens? That needs a custom first-login flow using the Automatically Set Existing User authenticator in place of the confirmation steps. Be careful with this one. Auto-linking on email match means anyone who can present a social identity carrying that email claim gets the existing local account. Only do it when you trust the provider to have verified email ownership. There’s a reason Keycloak doesn’t ship it as the default.

Step 4: Map claims with identity provider mappers

By default, Keycloak imports the basics: username, email, first and last name. Anything richer coming back from the provider gets dropped on the floor unless you tell Keycloak to keep it. That’s what identity provider mappers are for: they map the incoming tokens and assertions from the provider onto user and session attributes in Keycloak.

You’ll find them under Identity Providers, your provider, then the Mappers tab. Typical uses:

• Import a provider claim (an avatar URL, a locale, a GitHub username) into a Keycloak user attribute.
• Stamp brokered sessions with an attribute so your apps can tell social users from password users.

Remember the brokering model from earlier: your apps only ever see the tokens Keycloak issues. So after importing a claim into a user attribute, expose it to your applications through your client’s protocol mappers, or it stays internal to Keycloak.

Verifying the plumbing is easier with real tokens in front of you. Paste the access token your app receives into our JWT token analyzer and check that the claims you mapped actually arrived, with the values you expect.

How do you secure OAuth authentication in 2026?

The current baseline is the OAuth 2.1 draft plus the OAuth for browser-based apps draft. If your last serious look at OAuth security was the 2.0 era, here’s what changed:

• The implicit grant is gone. OAuth 2.1 removes it entirely. If a tutorial shows access tokens arriving in a URL fragment, close the tab.
• PKCE is required for the authorization code flow. Not recommended, required.
• Redirect URIs must match exactly. No wildcards, no prefix matching. This is why Keycloak gives you one precise broker endpoint per provider alias, and why you paste it verbatim.
• The state parameter must carry a CSRF-resistant value whenever you’re not already protected by PKCE or an OIDC nonce.
• Don’t keep tokens in JavaScript-accessible storage. The browser-based apps draft is blunt about why: “malicious JavaScript has the same privileges as the legitimate application code.” Its strong recommendation for SPAs is the backend-for-frontend (BFF) pattern, where a server-side component holds the tokens and the browser holds only a session cookie.

For social login specifically, the split of responsibility works in your favor. The provider leg (Keycloak talking to Google or Microsoft) is Keycloak’s job, server to server, secrets never touching the browser. The app leg (your SPA or native app talking to Keycloak) is where the rules above apply to code you own. That’s the leg to audit.

Two operational habits worth adopting: treat provider client secrets like any other production credential (rotate them, keep them out of git), and re-check your provider console’s redirect URI list whenever you change Keycloak hostnames. Stale callback URLs are both a breakage risk and a small attack surface.

Frequently asked questions

Is OAuth authentication or authorization?

Strictly, OAuth is an authorization framework: it governs what an app may access, not who the user is. Authentication comes from OpenID Connect, which layers identity on top of OAuth. When people say “OAuth authentication” they almost always mean login built on that combined stack, which is exactly what social login through a broker like Keycloak uses.

What redirect URI do I give Google or GitHub for Keycloak?

Always https://<keycloak-host>/realms/<realm>/broker/<alias>/endpoint, where the alias is the provider’s name in Keycloak. Keycloak shows the exact value when you add the provider. Paste it into “Authorized redirect URIs” in the Google Cloud Console, or “Authorization callback URL” in your GitHub OAuth App.

What happens if a social login email already exists in Keycloak?

Keycloak’s default first-login flow refuses to silently merge accounts. The Handle Existing Account sub-flow kicks in: the user confirms they want to link, then proves ownership of the existing account via an emailed verification link (SMTP must be configured) or by re-entering their existing password. Silent auto-linking requires a custom flow with the Automatically Set Existing User authenticator.

Should I use a GitHub App or an OAuth App for social login?

For plain sign-in, an OAuth App is the simpler default and works with Keycloak’s built-in GitHub provider. GitHub recommends GitHub Apps in general because they offer fine-grained permissions and short-lived tokens, and only GitHub Apps can refresh user access tokens. If all you need is “log in with GitHub”, the OAuth App is fine.

Is the OAuth implicit flow deprecated?

Yes, and it’s stronger than deprecated: the OAuth 2.1 draft removes the implicit grant entirely. Use the authorization code flow with PKCE instead, for every client type. Any guide still showing tokens returned directly from the authorization endpoint is describing a pattern the spec has abandoned.