# LinkedIn

## Implemented flow

The mock implements **Sign In with LinkedIn using OpenID Connect** through the
web authorization code flow: authorization, code exchange, signed ID tokens,
discovery, keys and `/v2/userinfo`.

The shared client models self-serve sign-in products. Approved Marketing partner
refresh tokens, native PKCE authorization and LinkedIn's broader APIs are not
implemented. `w_member_social` can be requested, but publishing posts is not served.

Sources: [Sign In with LinkedIn using OIDC](https://learn.microsoft.com/en-us/linkedin/consumer/integrations/self-serve/sign-in-with-linkedin-v2),
[authorization code flow](https://learn.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow),
[partner refresh tokens](https://learn.microsoft.com/en-us/linkedin/shared/authentication/programmatic-refresh-tokens).

## OpenID Connect (OIDC)

This provider supports OpenID Connect (OIDC), which adds signed ID tokens to OAuth
2.0 so your app can verify the signed-in user's identity. Mockatoo publishes OIDC
discovery and signing keys for this provider. See the
[Hono + oauth4webapi example](https://github.com/mockatoo/examples/blob/main/oauth4webapi-hono/src/app.tsx)
for a minimal authorization code flow with discovery and ID-token validation,
including this provider's differences, without an auth abstraction.

## Using the connector

```ts
// Better Auth: pass the same options you give socialProviders.linkedin
import { mockLinkedIn } from "@mockatoo/connect-better-auth";
const linkedin = { clientId: process.env.LINKEDIN_CLIENT_ID!,
                   clientSecret: process.env.LINKEDIN_CLIENT_SECRET! };
export const auth = betterAuth({
  socialProviders: process.env.NODE_ENV === "production" ? { linkedin } : {},
  plugins: process.env.NODE_ENV === "production" ? [] : [mockLinkedIn(linkedin)],
});

// Auth.js
import LinkedIn from "next-auth/providers/linkedin";
import { MockLinkedIn } from "@mockatoo/connect-authjs";
providers: [process.env.NODE_ENV === "production" ? LinkedIn() : MockLinkedIn()],
```

- The shared client accepts `openid`, `profile`, `email` and `w_member_social`.
  This does not validate the products approved for your real application.
- There are no refresh tokens. Plan for another sign-in when access expires.
- The web flow ignores `nonce` and `prompt`. A PKCE challenge is accepted, but
  sending a `code_verifier` makes token exchange fail; do not enable PKCE for
  this connector.
- Email can be absent. `email_verified` is a string in the ID token and a
  boolean in userinfo; account linking must handle those representations.
- The mock always shows consent. Photos use mock URLs, while real LinkedIn photo URLs expire. Use `you+nophoto@example.com` to test a member whose ID token and userinfo omit `picture`.

## 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.linkedin.com` and `api.linkedin.com`, so `mockLinkedIn()` contains a copy of Better Auth's `/v2/userinfo` lookup with the URL changed. | Hides changes in a newer Better Auth until the copy is updated. |
| No refresh tokens are ever issued, as for a self-serve app. LinkedIn issues them (with `refresh_token_expires_in`, one year) to apps of approved Marketing Developer Platform partners. | Hides refresh handling in a partner app. |
| The shared client has the self-serve products, so it may ask for `openid`, `profile`, `email` and `w_member_social`; the other permissions the mock knows get `unauthorized_scope_error`. A real app's permissions depend on the products it was approved for, and LinkedIn knows more permissions than the mock lists, so a real one the mock doesn't list gets `invalid_scope_error`. | Hides an app that asks for a permission it wasn't approved for, if it's one of the four; breaks an approved app that asks for an unlisted one. |
| Profile photos are served by the mock as SVGs. At LinkedIn, `picture` is a signed `media.licdn.com` URL that eventually expires. Use `+nophoto` for a member without a photo. | Hides apps that store an expiring photo URL. |
| As for a LinkedIn web app, a PKCE challenge is accepted and any `code_verifier` is refused (`invalid_client`). LinkedIn's native-app flow (`/oauth/native-pkce/authorization`, enabled per app by LinkedIn) isn't modeled. | Breaks native apps that use LinkedIn's PKCE flow. |

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