Implemented flow
The mock implements classic Facebook Login's web authorization code flow:
authorization, code exchange, /me profile lookup, debug_token inspection and
permission revocation.
It does not issue ID tokens, including when openid is requested. Limited Login,
implicit login, long-lived token exchange and app access tokens are not
implemented. Graph API support is limited to the endpoints used for sign-in;
other profile fields and broader Graph features are not served.
Sources: manual web login flow, Limited Login, long-lived tokens.
Using the connector
// Better Auth: pass the same options you give socialProviders.facebookimport { mockFacebook } from "@mockatoo/connect-better-auth";const facebook = { clientId: process.env.FACEBOOK_CLIENT_ID!, clientSecret: process.env.FACEBOOK_CLIENT_SECRET! };export const auth = betterAuth({ socialProviders: process.env.NODE_ENV === "production" ? { facebook } : {}, plugins: process.env.NODE_ENV === "production" ? [] : [mockFacebook(facebook)],});// Auth.jsimport Facebook from "next-auth/providers/facebook";import { MockFacebook } from "@mockatoo/connect-authjs";providers: [process.env.NODE_ENV === "production" ? Facebook() : MockFacebook()],- No refresh token is issued. Token exchange for long-lived access is also unavailable, so test that path separately against Facebook.
/mesupplies ID, name, email and picture. It has noemail_verified, so neither connector marks email verified.+noemailexercises a user declining the email permission.- Known permissions are granted without App Review, but granting them does not add unsupported fields or API features. This cannot validate your app approval.
- Photos use mock URLs, while real Facebook photo URLs expire. Use
you+nophoto@example.comto test a user whose picture is a silhouette (is_silhouette: true). - Facebook's callback includes the
#_=_fragment. The mock preserves it.
Special test addresses
Log in as you+<tag>@example.com with your own account's password to get a distinct, stable test user. Tags combine with dots, such as you+hd.unverified@example.com. Any other tag, such as you+1@example.com, is just another user; see Email tags.
| Tag | Behavior | |
|---|---|---|
unverified | email_verified: false (GitHub: primary email verified: false; Discord: verified: false; LinkedIn: "false" in the ID token) | Example |
renamed | Same user ID (sub, Microsoft oid, GitHub, Discord, X and Facebook id) as the address without +renamed, different email | Example |
noname | No name (Google: also no given_name/family_name; GitHub: name: null; Discord: global_name: null) | Example |
noemail | No email claim, like an account without a mailbox (Discord: email: null and verified: false; LinkedIn: a member who signed up with a phone number; X: no confirmed_email; Facebook: the user declines the email permission, which debug_token's scopes then leave out) | Example |
nophoto | No profile photo. LinkedIn omits picture from the ID token and userinfo; Facebook returns a silhouette with is_silhouette: true | Example |
badcode | The code exchange fails (invalid_grant; GitHub: bad_verification_code; LinkedIn and X: invalid_request; Facebook: Invalid verification code format.) | Example |
down | The token endpoint returns 503 | Example |
flaky | The first exchange of each code returns 503; a retry succeeds | Example |
slow | Token responses are delayed (10 seconds) | Example |
Known differences
This provider
| Difference | Effect |
|---|---|
Better Auth hardcodes www.facebook.com and graph.facebook.com, so mockFacebook() contains a copy of Better Auth's debug_token check and /me lookup with the URLs changed, and its token URL with Better Auth's Graph API version (v24.0). | Hides changes in a newer Better Auth until the copy is updated. |
| An unknown permission always stops at Facebook's page "Invalid Scope: emial (Please check lower letter case or delimiter)", as it does for the app's admin. Older reports say Facebook shows such a page only to the app's developers and testers, and drops the unknown permission for everyone else. | Breaks sign-in with a misspelled or retired permission that a live app's users get through (without that permission). |
Every known permission the app asks for is granted, as for the app's developers, and the user declines none, except that a +noemail user declines email. But the mock only has a user's id, name, email and picture: other User fields (birthday, gender, friends, …) are left out of /me, as if not granted. Real Facebook grants permissions beyond public_profile and email to other users only after App Review, and users can decline email. | Hides a missing App Review and a user who declines a permission; breaks features that read other User fields. |
Profile photos are served by the mock as SVGs. At Facebook, picture.data.url is a signed scontent…fbcdn.net URL that expires (its oe parameter). Use +nophoto for a silhouette (is_silhouette: true). | Hides apps that store an expiring photo URL. |
No ID token is ever issued. Facebook returns one from the classic code flow once the user has granted openid (RS256, iss https://www.facebook.com/ or, once, without the slash, a 90-day exp, nonce, at_hash, name, given_name, family_name, picture), and then on every later sign-in, even ones that don't ask for openid (with an empty nonce). Limited Login (iOS), its discovery and its keys at limited.facebook.com aren't served either. | Breaks apps that read Facebook's ID token. Hides an app that receives one it didn't ask for: Better Auth then takes the profile from the ID token instead of /me. |
Only the authorization code grant is modeled. response_type=token, long-lived token exchange (grant_type=fb_exchange_token) and app access tokens (client_credentials) are refused. | Breaks apps that exchange tokens or call the Graph API as the app. |
appsecret_proof is ignored. An app with "Require App Secret" turned on gets an error from Facebook for every Graph call without a correct proof. | Hides a missing or wrong appsecret_proof. |
Shared mock limits
| Difference | Effect |
|---|---|
| ID tokens are issued to the shared mock client. Native bundle IDs and native client registrations are not modeled. | Hides a native audience setting that does not match your production registration. |
Refresh tokens do not expire from age or inactivity, even when a response advertises refresh_token_expires_in. Rotation and revocation still apply where supported; +revoked forces refresh failure. | Hides failures after long periods without sign-in. Use +revoked to exercise expired or revoked grant handling. |
Any http/https callback URL is accepted, including localhost. Apple refuses http and localhost, and Microsoft refuses http except for localhost, whatever the app registered. | Hides a callback URL the real provider refuses outright. |
Everyone uses one shared client (mockatoo / mockatoo-secret). The connectors replace your production client ID and secret, Apple's signed client secret, and Microsoft's client assertion. | Hides wrong production credentials or a broken client-secret setup. |
The login form and the consent screen appear on every sign-in; there is no remembered session. prompt=none fails for Google (interaction_required) and Microsoft (login_required), and Discord and LinkedIn, which skip consent for a returning user (LinkedIn even with prompt=consent), always ask again. | Breaks silent sign-in that works with a real signed-in user. |
Issuers and signing keys are the mock's (for example https://app.mockatoo.globalunderdog.com/google, not https://accounts.google.com). Discord's authorization responses carry iss=https://app.mockatoo.globalunderdog.com/discord, not https://discord.com. | Breaks code that hardcodes a real issuer or key URL. |
Tokens are only valid at the mock. Real provider APIs (Google APIs, Microsoft Graph, GitHub's api.github.com, Discord's discord.com/api, LinkedIn's api.linkedin.com, X's api.x.com, Facebook's graph.facebook.com) reject them, and the mock doesn't serve those APIs beyond what sign-in needs. | Breaks app features that call the provider's API after sign-in. |
A special address (you+tag@…) is a different test user with the same password. Apps that strip +tags from emails will merge them into one user. | Breaks special addresses in such apps. |