KeycloakPro

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.

Meta's developer portal changes often. The screens in this guide reflect the current portal as of mid-2026. If a button or page mentioned here doesn't match what you see, the underlying setting almost always still exists — just under a slightly different menu. We call out the trickiest of these below.

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. App details — you'll land here first:
    • App name: something that identifies your service to users (they see this on the authorization screen)
    • App contact email: your support email
    • Click Next
  3. Use cases — select Authenticate and request data from users with Facebook Login (Consumer apps), then click Next

The creation wizard will then walk you through a few extra screens — none of these need real answers yet, just click through them:

  • Business — select "I don't want to connect a business portfolio yet." A business portfolio is only required later if you need deeper data access. Basic Facebook Login doesn't need it.
  • Requirements — this screen just previews what you'd need if you later request extra permissions (Business Verification, App Review). You don't need to complete anything here. Click Next.
  • Overview — review the summary and click Create app / Go to dashboard.
This is the first screen of the wizard — name and contact email, then Next takes you to use case selection
Skip business portfolio connection for basic Facebook Login — you can always add one later if your needs grow
This link is the starting point for almost every Facebook Login setting — redirect URIs, permissions, and more all live behind it now

Step 2 — Configure the Facebook Login redirect URI

Meta no longer has a separate "Add Product" step for Facebook Login — it's included automatically because you selected that use case in Step 1. Instead, you configure it from the use case customization panel:

  1. On your app Dashboard, click "Customize the Authenticate and request data from users with Facebook Login use case"
  2. In the panel that opens, click Settings → Go to settings
  3. Find Valid OAuth Redirect URIs and add: 
    https://keycloak.example.com/realms/YOUR_REALM/broker/facebook/endpoint
  4. If you see an Enable Login with the JavaScript SDK toggle, you can leave it off — Keycloak doesn't need it
  5. Click Save changes
The redirect URI must match exactly — Meta checks path and scheme. Add the production URI here even if you're testing locally first

Step 3 — Add the App Domains

This step is easy to miss and causes a "Can't load URL" error during login if skipped.

  1. Go to App Settings → Basic
  2. Find App Domains and add your Keycloak domain, for example: 
    keycloak.example.com
  3. Click Save Changes
Without this, Facebook shows 'Can't load URL — domain not in app's domains' when it tries to close the login dialog and return to Keycloak

Step 4 — Add the email permission

New apps only come with public_profile by default. Without the email permission added explicitly, login fails with an "Invalid Scopes: email" error.

  1. In the left sidebar, go to Use cases
  2. Click Customize next to your Facebook Login use case (or use the same "Customize the Authenticate and request data..." link from Step 2)
  3. Open the Permissions and features tab
  4. Find email in the list and click + Add

public_profile is already listed as automatically granted — you don't need to touch it.

email is not granted automatically — this is the single most common reason Facebook Login fails on a freshly created app

Step 5 — 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

Keep this secret out of source control — paste it straight into Keycloak in the next step, or a password manager if you need to store it temporarily.

Step 6 — 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 5
  4. Client Secret: paste the App Secret from Step 5
  5. Leave Additional user's profile fields empty unless you specifically need extra Graph API fields (this is not a name or label field — don't type your own name in here)

Click Add.

The Redirect URI shown here should exactly match what you added to Meta in Step 2 — copy it directly from this page to be safe

Once saved, open the provider's settings page. Default Scopes will already show email public_profile — you don't need to change this.

Step 7 — 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. Social Profile JSON Field Path: first_name

    This field is labeled differently from OIDC-based providers (Nextcloud, Jenkins, Grafana), which use a field called "Claim." Facebook isn't OIDC — it returns plain JSON from the Graph API, not a JWT with claims — so Keycloak labels this field Social Profile JSON Field Path instead. It does the same job: it's the key to read from Facebook's response.

  5. User Attribute Name: firstName

  6. Save

Repeat for last_name → lastName.

Facebook's field names use underscores — first_name and last_name — while Keycloak's built-in attribute names use camelCase

Step 8 — 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 only
  • force — overwrite Keycloak attributes from Facebook on every login
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 9 — Test the login

You don't need to publish your Meta app to test this. While the app is in Development mode, any account with an Admin, Developer, or Tester role on the app (you, as the creator, already have this) can log in and complete the full flow.

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

The button text defaults to the provider display name — customizable in Identity Providers settings

Click it and log in with Facebook. You'll see one of two outcomes:

New Facebook identity, no matching Keycloak account: Keycloak creates a new user automatically and logs you in.

Facebook account's email matches an existing Keycloak user: you'll see an "Account already exists" screen with two options — Review profile or Add to existing account.

If you choose Add to existing account, Keycloak will ask you to sign in with that account's existing password before completing the link. This is a security check to confirm you actually own the account — someone shouldn't be able to hijack it just by knowing its email address and logging in via Facebook.

After authenticating, Keycloak sends you to your application. Verify the federated account: Keycloak admin → Users → find the user → Identity Provider Links tab.

Step 10 — Go live (do this last, when you're ready for real users)

While the app is in Development mode, only accounts listed in the app's Roles (Administrators, Developers, Testers) can log in — everyone else sees an error. You don't need to complete this step to build and test your integration; come back to it once you're ready to open login to the public.

Meta no longer has a simple "Go Live" toggle. Instead:

  1. Go to App Settings → Basic
  2. Fill in the fields Meta flags as missing for publishing, typically:
    • App icon (1024×1024 image)
    • Privacy Policy URL — a real, reachable page describing what data you collect (e.g. name and email via Facebook Login) and why. A free generator like termly.io or freeprivacypolicy.com works if you don't want to write one from scratch, or add a /privacy page to your own site.
    • User data deletion — a URL or instructions explaining how a user can request their data be deleted
    • Category — pick the closest fit for your app
  3. Click Save Changes
  4. Go to Publish in the left sidebar and complete that flow
Meta lists exactly what's missing before you can publish — fill each of these in, then use Publish in the sidebar

For apps that only request email and public_profile, Meta typically doesn't require a full App Review to publish.

Troubleshooting common issues

"Invalid Scopes: email" from Facebook

The email permission hasn't been added to the app. This is not automatic — see Step 4. Go to Use cases → Customize → Permissions and features and click Add next to email.

"Can't load URL — domain not in app's domains"

Your Keycloak domain isn't listed in the app's App Domains field. See Step 3 — add it under App Settings → Basic.

"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 → App roles, or complete Step 10 to go live.

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

The exact redirect URI in your Facebook Login settings 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 at the top of the settings page.

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 7. 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

  • email permission added under Use cases → Customize → Permissions and features
  • App Domains set to your Keycloak domain
  • App in Live mode (Publish flow completed) — Development mode blocks all non-team users
  • App Secret stored outside source control
  • Privacy policy URL configured in the Meta app (required to publish)
  • 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