Identity Brokeringbeginner12 min readJune 12, 2026

Keycloak Facebook Identity Provider: Social Login Setup

Add Facebook as an identity provider in Keycloak so users can sign in with their Facebook account. Covers Meta app creation, Facebook Login product configuration, Keycloak IDP setup, attribute mappers, and first login flow.

KT

KeycloakPro Team

KeycloakPro Team

Introduction

Facebook uses OAuth 2.0, not OIDC. There's no id_token, and profile data comes from the Graph API rather than a standard userinfo endpoint. Keycloak's built-in Facebook provider handles these differences for you — you provide the App ID and App Secret, and Keycloak takes care of the rest.

Users see a "Continue with Facebook" button on your Keycloak login page. After they authenticate with Facebook, Keycloak creates a local account on their first login and links it to their Facebook identity.

How identity brokering works

The login flow goes: user clicks "Continue with Facebook" → Keycloak redirects to Facebook → user authorizes your app → Facebook sends an authorization code to Keycloak's broker endpoint → Keycloak fetches profile data from the Graph API → Keycloak creates or links the user → user lands in your application.

Your application only talks to Keycloak. The Facebook access token stays inside Keycloak. The redirect URI you register in the Meta app is:

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

Prerequisites

  • Keycloak 24+ running on HTTPS
  • A Keycloak realm with admin access
  • A Meta developer account at developers.facebook.com
  • A Facebook Business or personal account to own the app

Step 1 — Create a Meta app

In the Meta Developer Portal:

  1. My Apps → Create App
  2. Use case: Authenticate and request data from users with Facebook Login (Consumer apps)
  3. App name: something that identifies your service to users (they see this on the authorization screen)
  4. App contact email: your support email
  5. Business account: optional for social login, required for some permissions

Click Create app.

Meta Developer Portal Create App page showing Use case options with the Authenticate and request data option selected, an App name field, and App contact email field
The use case you pick here determines which products are pre-added to the app — Consumer apps include Facebook Login by default

Step 2 — Add the Facebook Login product

If Facebook Login isn't already listed under Add products to your app:

  1. On the app dashboard, click Add Product
  2. Find Facebook Login → click Set up
  3. Platform: Web
  4. Site URL: https://keycloak.example.com → click Save
Meta Developer Portal app dashboard showing Facebook Login as an installed product in the left sidebar with a checkmark
Facebook Login must be an installed product before you can configure redirect URIs

Step 3 — Configure Valid OAuth redirect URIs

In the left sidebar:

  1. Facebook Login → Settings
  2. Valid OAuth Redirect URIs → add: https://keycloak.example.com/realms/YOUR_REALM/broker/facebook/endpoint
  3. Click Save changes
Meta Facebook Login Settings page showing the Valid OAuth Redirect URIs field with the Keycloak broker endpoint URL added
The redirect URI must match exactly — Meta checks path and scheme. Add the production URI here even if you're testing locally first

Step 4 — Copy the App ID and App Secret

In the app settings:

  1. App settings → Basic
  2. Copy the App ID (shown at the top)
  3. Click Show next to App Secret, confirm with your Facebook password, then copy
Meta App Settings Basic page showing the App ID field at the top and the App Secret field with a Show button
The App Secret is hidden by default — you need to reauthenticate to view it

Step 5 — Add Facebook as an Identity Provider in Keycloak

In the Keycloak admin console:

  1. Select your realm
  2. Identity Providers → Add provider → Facebook
  3. Client ID: paste the App ID from Step 4
  4. Client Secret: paste the App Secret from Step 4
  5. Default Scopes: email public_profile (Keycloak sets this for the Facebook provider)

Click Add.

Keycloak admin console Identity Providers page showing the Facebook provider configuration with Client ID set to the Meta App ID and Client Secret set to the App Secret
The built-in Facebook provider handles the Graph API call automatically — you don't need to set up userinfo URLs manually

Step 6 — Configure attribute mappers

Open Identity Providers → Facebook → Mappers. Keycloak's built-in Facebook provider creates default mappers:

Facebook fieldKeycloak user attribute
idExternal user ID (identity link)
emailemail
namefull name

Facebook's first_name and last_name fields are available from the Graph API response. To populate Keycloak's firstName and lastName attributes, add mappers manually:

  1. Mappers → Add mapper
  2. Mapper type: Attribute Importer
  3. Name: first_name
  4. Claim: first_name
  5. User Attribute Name: firstName
  6. Save

Repeat for last_namelastName.

Keycloak Identity Provider Mapper creation form showing Attribute Importer type with Claim set to first_name and User Attribute Name set to firstName
Facebook's field names use underscores — first_name and last_name — while Keycloak's built-in attribute names use camelCase

Step 7 — Configure the First Login Flow

In Identity Providers → Facebook → SettingsFirst Login Flow, the default first broker login flow:

  • Shows the user a profile review page (name, email) on first login
  • Checks if a Keycloak account already exists with the same email
  • If a match exists, offers account linking
  • If no match, creates a new Keycloak user

Important note on Facebook emails: Not all Facebook accounts have a verified email address. If a user's Facebook account has no email, the email attribute will be blank in Keycloak. The first broker login flow prompts the user to enter an email in that case.

Set Sync Mode:

  • import — copy Facebook attributes on first login only
  • force — overwrite Keycloak attributes from Facebook on every login
Keycloak Facebook Identity Provider Settings showing First Login Flow set to first broker login and Sync Mode set to import
The first broker login flow handles the case where a user already has a Keycloak account with the same email — they're prompted to link the accounts

Step 8 — Switch the app to Live mode

While the app is in Development mode, only accounts listed in the app's Roles (Administrators, Developers, Testers) can log in. External users see an error.

To allow any Facebook user:

  1. App Settings → Basic → scroll to App Mode
  2. Click Go Live (or toggle the switch in the header)
  3. You need a privacy policy URL and (for some apps) an icon
Meta app header showing the App Mode switch in the off position with a Go Live button and a note that the app is currently in development mode
Development mode restricts login to app team members only — switch to Live before opening to users

For apps that only request email and public_profile, Meta typically approves Go Live without additional review.

Step 9 — Test the login

Open a private browser window and go to your Keycloak realm login page. A Continue with Facebook button appears.

Keycloak login page showing the username and password form with a Continue with Facebook button below
The button text defaults to the provider display name — customizable in Identity Providers settings

After authenticating with Facebook, Keycloak shows the review profile page on first login, then sends the user to your application. Verify the federated account: Keycloak admin → Users → find the user → Identity Provider Links tab.

Keycloak User detail page Identity Provider Links tab showing a Facebook row with the provider alias facebook and the Facebook user ID as the external user ID
The external user ID is the Facebook numeric user ID — unique per user and never reused

Troubleshooting common issues

"App Not Set Up" from Facebook

The app is in Development mode and the login attempt is from an account that isn't an app administrator, developer, or tester. Either add the account to the app's roles in Meta Developer Portal → Roles, or switch the app to Live mode.

"URL Blocked: This redirect failed because the redirect URI is not whitelisted"

The exact redirect URI in Facebook Login → Settings → Valid OAuth Redirect URIs doesn't match what Keycloak sends. The correct URI format is:

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

Copy this directly from Keycloak: Identity Providers → Facebook → Redirect URI field in the settings panel.

User can log in but email is blank

Facebook accounts don't require a verified email address. If the user's Facebook account has no email, the email claim won't be in the response. The first broker login flow will prompt for an email. You cannot force Facebook to provide an email.

Login works but firstName and lastName are blank

You need the attribute mappers from Step 6. The default mappers don't include first_name and last_name. Add the two Attribute Importer mappers and test with a new login (or force a profile sync by setting Sync Mode to force).

"permissions" error from Facebook

If you added non-default permissions to your app (beyond email and public_profile), Meta requires app review for those permissions before they work for Live mode users. Remove additional permissions if you don't need them, or complete the Meta app review process.

Production checklist

  • App in Live mode — Development mode blocks all non-team users
  • App Secret stored outside source control
  • Privacy policy URL configured in the Meta app (required for Go Live)
  • Redirect URI in Meta matches Keycloak's broker endpoint exactly
  • Handling for accounts without a Facebook email (first broker login flow prompts for it)
  • first_name and last_name mappers added if your application uses these attributes
  • Sync Mode chosen deliberately: import or force
  • App review not required for email and public_profile — only for additional permissions

Need help integrating Facebook with Keycloak?

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

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

See integration packages