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.
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:
- My Apps → Create App
- Use case: Authenticate and request data from users with Facebook Login (Consumer apps)
- App name: something that identifies your service to users (they see this on the authorization screen)
- App contact email: your support email
- Business account: optional for social login, required for some permissions
Click Create app.

Step 2 — Add the Facebook Login product
If Facebook Login isn't already listed under Add products to your app:
- On the app dashboard, click Add Product
- Find Facebook Login → click Set up
- Platform: Web
- Site URL:
https://keycloak.example.com→ click Save

Step 3 — Configure Valid OAuth redirect URIs
In the left sidebar:
- Facebook Login → Settings
- Valid OAuth Redirect URIs → add:
https://keycloak.example.com/realms/YOUR_REALM/broker/facebook/endpoint - Click Save changes

Step 4 — Copy the App ID and App Secret
In the app settings:
- App settings → Basic
- Copy the App ID (shown at the top)
- Click Show next to App Secret, confirm with your Facebook password, then copy

Step 5 — Add Facebook as an Identity Provider in Keycloak
In the Keycloak admin console:
- Select your realm
- Identity Providers → Add provider → Facebook
- Client ID: paste the App ID from Step 4
- Client Secret: paste the App Secret from Step 4
- Default Scopes:
email public_profile(Keycloak sets this for the Facebook provider)
Click Add.

Step 6 — Configure attribute mappers
Open Identity Providers → Facebook → Mappers. Keycloak's built-in Facebook provider creates default mappers:
| Facebook field | Keycloak user attribute |
|---|---|
id | External user ID (identity link) |
email | |
name | full 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:
- Mappers → Add mapper
- Mapper type: Attribute Importer
- Name:
first_name - Claim:
first_name - User Attribute Name:
firstName - Save
Repeat for last_name → lastName.

Step 7 — Configure the First Login Flow
In Identity Providers → Facebook → Settings → First 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 onlyforce— overwrite Keycloak attributes from Facebook on every login

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:
- App Settings → Basic → scroll to App Mode
- Click Go Live (or toggle the switch in the header)
- You need a privacy policy URL and (for some apps) an icon

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.

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.

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_nameandlast_namemappers added if your application uses these attributes - Sync Mode chosen deliberately:
importorforce - App review not required for
emailandpublic_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.