# Facebook

## 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](https://developers.facebook.com/docs/facebook-login/guides/advanced/manual-flow/),
[Limited Login](https://developers.facebook.com/docs/facebook-login/limited-login/),
[long-lived tokens](https://developers.facebook.com/docs/facebook-login/guides/access-tokens/get-long-lived/).

## Using the connector

```ts
// Better Auth: pass the same options you give socialProviders.facebook
import { 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.js
import 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.
- `/me` supplies ID, name, email and picture. It has no `email_verified`, so
  neither connector marks email verified. `+noemail` exercises 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.com` to 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](../email-tags.md).

| Tag | Behavior | |
| --- | --- | --- |
| `unverified` | `email_verified: false` (GitHub: primary email `verified: false`; Discord: `verified: false`; LinkedIn: `"false"` in the ID token) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/unverified.spec.ts) |
| `renamed` | Same user ID (`sub`, Microsoft `oid`, GitHub, Discord, X and Facebook `id`) as the address without `+renamed`, different email | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/renamed.spec.ts) |
| `noname` | No name (Google: also no `given_name`/`family_name`; GitHub: `name: null`; Discord: `global_name: null`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/noname.spec.ts) |
| `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](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/noemail.spec.ts) |
| `nophoto` | No profile photo. LinkedIn omits `picture` from the ID token and userinfo; Facebook returns a silhouette with `is_silhouette: true` | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/nophoto.spec.ts) |
| `badcode` | The code exchange fails (`invalid_grant`; GitHub: `bad_verification_code`; LinkedIn and X: `invalid_request`; Facebook: `Invalid verification code format.`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/badcode.spec.ts) |
| `down` | The token endpoint returns 503 | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/down.spec.ts) |
| `flaky` | The first exchange of each code returns 503; a retry succeeds | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/flaky.spec.ts) |
| `slow` | Token responses are delayed (10 seconds) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/slow.spec.ts) |

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