Facebook OAuth2 Configuration

1. Overview

This guide explains how to configure the Registration Portal to authenticate users via Facebook Login. Facebook uses OAuth2 but does not fully implement OIDC — it lacks OIDC Discovery and issues opaque access tokens rather than JWTs.

2. Prerequisites

3. Facebook App Setup

3.1. Create or Configure App

  1. Navigate to My Apps

  2. Click Create App or select an existing app

  3. Choose app type: Consumer (for public login)

3.2. Add Facebook Login Product

  1. In the app dashboard, click + Add Product

  2. Select Facebook Login for Business or Facebook Login

  3. Choose Web as the platform

3.3. Configure OAuth Settings

Navigate to Facebook Login > Settings and configure:

Field Value

Valid OAuth Redirect URIs

https://<tenant-domain>/login/oauth2/code/facebook

Client OAuth Login

Enabled

Web OAuth Login

Enabled

Enforce HTTPS

Yes (production)

Login with the JavaScript SDK

No (server-side flow)

Each tenant domain requires its own redirect URI entry. For example:

3.4. App Credentials

Note the following from Settings > Basic:

  • App ID — used as client_id

  • App Secret — used as client_secret

4. Registration Portal Configuration

Create a TenantIdentityProvider record with the following values:

Field Value

provider_type

FACEBOOK

display_name

"Sign in with Facebook"

client_id

App ID from Facebook Developer Portal

client_secret

App Secret (encrypted at rest)

issuer_uri

(leave null — Facebook does not support OIDC Discovery)

authorization_uri

https://www.facebook.com/v21.0/dialog/oauth

token_uri

https://graph.facebook.com/v21.0/oauth/access_token

user_info_uri

https://graph.facebook.com/v21.0/me?fields=id,name,email,first_name,last_name

jwks_uri

(leave null — Facebook uses opaque tokens)

scopes

public_profile,email

user_name_attribute

id

enabled

true

Facebook does not support OIDC Discovery. All endpoint URIs must be configured explicitly via override fields. The issuer_uri and jwks_uri fields should be left null.

5. Facebook-Specific Behaviour

Characteristic Detail

OIDC Compliance

Not OIDC — standard OAuth2 only

Token Type

Opaque access token (not JWT)

No ID Token

Facebook does not issue ID tokens; user info is fetched via the Graph API

Subject Identifier

Numeric string (id field), unique per app, stable

User Info

Fetched via GET /me endpoint on the Graph API

Token Validation

Opaque tokens cannot be validated via JWKS; use Facebook’s debug_token API for server-side validation

PKCE

Not supported by Facebook

API Versioning

Facebook API is versioned (e.g., v21.0); update endpoints when upgrading

6. Token Exchange Considerations

Since Facebook issues opaque access tokens (not JWTs), the Gateway’s BackendTokenExchangeSuccessHandler extracts user identity from the OAuth2User principal (populated by Spring Security’s userInfo call) rather than from a JWT ID token.

The validated claims (sub, email, name) sent to the admin-service token exchange endpoint are the same regardless of provider — the admin-service does not need to know whether the user logged in via Facebook or Google.

7. App Review

For production use beyond app administrators and testers:

  1. Submit the app for App Review in the Facebook Developer Portal

  2. Request the email permission (requires justification)

  3. public_profile is granted by default

Until approved, only users listed in Roles > Test Users or Roles > Administrators can log in.

8. Related Documentation