Payload OAuth2

https://github.com/wilsonle/payload-oauth2
Admin
A Payload CMS plugin that configures OAuth2 with any provider, offering zero dependencies and high...
Tokens:38,627
Snippets:253
Trust Score:8.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Development Setup

Source: https://github.com/wilsonle/payload-oauth2/blob/main/README.md

Commands to set up the project for local development.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Install payload-oauth2

Source: https://github.com/wilsonle/payload-oauth2/blob/main/README.md

Commands to install the package using npm, yarn, or pnpm.

```bash
npm install payload-oauth2
yarn install payload-oauth2
pnpm install payload-oauth2
```

--------------------------------

### Basic usage (GET callback)

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-callback-extract-token.md

Extracts the authorization code from a GET request's query parameters. Expects req.method === 'GET' and req.query to contain a 'code' property. Returns the code as a string.

```TypeScript
import { defaultCallbackExtractToken } from "payload-oauth2/dist/default-callback-extract-token.js";

// Google-style callback: GET /api/users/oauth/google/callback?code=4/0AX...
// req.method === "GET", req.query === { code: "4/0AX..." }
const code = await defaultCallbackExtractToken(req);
console.log(code); // "4/0AX..."
```

--------------------------------

### Create Google Login Button

Source: https://github.com/wilsonle/payload-oauth2/blob/main/README.md

Example of a React component that initiates the OAuth flow by navigating to the authorize endpoint.

```tsx
export function GoogleLoginButton() {
  return <a href="/api/users/oauth/google">Continue with Google</a>
}
```

--------------------------------

### Custom getPkceCodes through PluginOptions

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-get-pkce-codes.md

Shows how to provide a custom getPkceCodes function through PluginOptions. The function must return an object with verifier, challenge, and challengeMethod. This example uses a custom challenge string instead of the default SHA-256 digest.

```ts
import { OAuth2Plugin } from "payload-oauth2";

OAuth2Plugin({
  // ...options
  pkceEnabled: true,
  getPkceCodes: () => ({
    verifier: crypto.randomBytes(32).toString("base64url"),
    challenge: "my-custom-challenge",
    challengeMethod: "S256",
  }),
});
```

--------------------------------

### GET /api/users/oauth/authorize

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/endpoints.md

Starts the OAuth authorization flow. A logged-out browser navigates to this endpoint to begin the OAuth dance with the configured provider.

```APIDOC
## GET /api/users/oauth/authorize

### Description
Starts the OAuth authorization flow. A logged-out browser navigates to this endpoint to begin the OAuth dance with the configured provider.

### Method
GET

### Endpoint
/api/<authCollection><authorizePath> — default /api/users/oauth/authorize

### Parameters
#### Query Parameters
- **state** (string) - Optional - Forwarded verbatim to the provider as the `state` parameter.

#### Headers (optional)
- **RSC** (string) - Optional - Triggers the RSC probe branch when set to `1`.
- **Next-Router-State-Tree** (string) - Optional - Triggers the RSC probe branch.
- **Next-Router-Prefetch** (string) - Optional - Triggers the RSC probe branch.
- **_rsc** (query param) - Optional - Triggers the RSC probe branch.

### Response
#### Success Response (204 No Content)
- **Body** - none
- **Headers** - none

#### Success Response (302 Found)
- **Headers** - `Location: <providerAuthorizationUrl>?<params>`
- **Body** - none
- **Location query params** - `client_id`, `redirect_uri` (default `serverURL + "/api/<authCollection>" + callbackPath`, unless `authorizeRedirectUri` set), `scope` (scopes joined with `" "`), `response_type=code`, `access_type=offline`, optional `prompt`, optional `response_mode`, optional `auth_type`, optional `state` (forwarded), `nonce` (16 random bytes hex)

#### Success Response (302 Found with PKCE)
- **Headers** - `Location: <providerAuthorizationUrl>?...&code_challenge=<challenge>&code_challenge_method=<method>` and `Set-Cookie: pkce_verifier=<verifier>; Max-Age=600; SameSite=Lax`
- **Body** - none

### Notes
- No authentication required.
- The `pkce_verifier` cookie is generated via payload `generateCookie` with `maxAge: 10 * 60` (10 minutes), `sameSite: "Lax"`.
- The verifier is later consumed by `defaultGetToken` as `code_verifier`.
```

--------------------------------

### GET /api/users/oauth/callback

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/endpoints.md

Handles the OAuth callback from the provider. The provider redirects the user to this endpoint after authorization.

```APIDOC
## GET /api/users/oauth/callback

### Description
Handles the OAuth callback from the provider. The provider redirects the user to this endpoint after authorization.

### Method
GET

### Endpoint
/api/<authCollection><callbackPath> — default /api/users/oauth/callback

### Parameters
#### Query Parameters
- **code** (string) - Required - The authorization code returned by the provider.
- **state** (string) - Optional - The state parameter that was sent in the authorization request.

### Response
#### Success Response (302 Found)
- **Headers** - `Location: <redirectUrl>`
- **Body** - none

#### Error Response (400 Bad Request)
- **Body** - JSON error message

### Notes
- No authentication required.
- The callback handler operates on `req.payload` directly (no `req.user` checks) and issues its own JWT.
```

--------------------------------

### Basic usage of createCallbackEndpoint

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/callback-endpoint.md

Basic usage of createCallbackEndpoint to set up OAuth callback handlers. Configure serverURL, authCollection, callbackPath, tokenEndpoint, clientId, clientSecret, and strategyName. The returned getEndpoint and postEndpoint have method "get" and "post" respectively, both with path "/oauth/callback".

```ts
import { createCallbackEndpoint } from "payload-oauth2/dist/callback-endpoint.js";

const [getEndpoint, postEndpoint] = createCallbackEndpoint({
  serverURL: "http://localhost:3000",
  authCollection: "users",
  callbackPath: "/oauth/google/callback",
  tokenEndpoint: "https://oauth2.googleapis.com/token",
  clientId: "my-client",
  clientSecret: "my-secret",
  useEmailAsIdentity: true,
  strategyName: "google",
  onUserNotFoundBehavior: "create",
  successRedirect: (req, accessToken) => "/admin",
  failureRedirect: (req, err) => {
    req.payload.logger.error(err);
    return "/admin/login";
  },
  getUserInfo: async (accessToken) => ({ email: "user@example.com", sub: "sub-123" }),
});

// getEndpoint.method === "get"; postEndpoint.method === "post";
// both .path === "/oauth/callback"
```

--------------------------------

### createCallbackEndpoint

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/callback-endpoint.md

Documentation for the createCallbackEndpoint function, which creates GET and POST endpoints for handling OAuth2 callbacks.

```APIDOC
## createCallbackEndpoint

### Description
Creates a pair of GET and POST endpoints for handling OAuth2 callback requests. The GET endpoint typically initiates the OAuth flow, while the POST endpoint handles the callback with the authorization code.

### Method
- GET
- POST

### Endpoint
- `/oauth/callback` (customizable via `callbackPath`)

### Parameters
#### Configuration Options
- **serverURL** (string) - Required - The base URL of the server.
- **authCollection** (string) - Required - The name of the auth collection in Payload.
- **callbackPath** (string) - Required - The path for the callback endpoint.
- **tokenEndpoint** (string) - Required - The OAuth2 token endpoint URL.
- **clientId** (string) - Required - The OAuth2 client ID.
- **clientSecret** (string) - Required - The OAuth2 client secret.
- **useEmailAsIdentity** (boolean) - Required - Whether to use email as the user identity.
- **strategyName** (string) - Required - The name of the OAuth2 strategy.
- **onUserNotFoundBehavior** (string) - Required - Behavior when user is not found: `"create"` or `"error"`.
- **successRedirect** (function) - Required - Function that returns the redirect URL on success. Receives `(req, accessToken)`.
- **failureRedirect** (function) - Required - Function that returns the redirect URL on failure. Receives `(req, err)`.
- **getUserInfo** (function) - Required - Async function that fetches user info using the access token. Receives `(accessToken)` and returns user info object.

### Request Example
```ts
import { createCallbackEndpoint } from "payload-oauth2/dist/callback-endpoint.js";

const [getEndpoint, postEndpoint] = createCallbackEndpoint({
  serverURL: "http://localhost:3000",
  authCollection: "users",
  callbackPath: "/oauth/google/callback",
  tokenEndpoint: "https://oauth2.googleapis.com/token",
  clientId: "my-client",
  clientSecret: "my-secret",
  useEmailAsIdentity: true,
  strategyName: "google",
  onUserNotFoundBehavior: "create",
  successRedirect: (req, accessToken) => "/admin",
  failureRedirect: (req, err) => {
    req.payload.logger.error(err);
    return "/admin/login";
  },
  getUserInfo: async (accessToken) => ({ email: "user@example.com", sub: "sub-123" }),
});

// getEndpoint.method === "get"; postEndpoint.method === "post";
// both .path === "/oauth/callback"
```

### Response
#### Success Response (302)
- Redirects to the URL returned by `successRedirect`.

#### Error Response (302)
- Redirects to the URL returned by `failureRedirect` with an `error` query parameter.
- Response headers include `Content-Type: application/json`.

#### Response Example
```ts
const response = await postEndpoint.handler(fakeReq); // some PayloadRequest
// response.status === 302
// response.headers.get("Location") === "/admin/login?error=..."
// response.headers.get("Content-Type") === "application/json"
```

### Error Handling
- All errors thrown inside the handler are caught and routed to `failureRedirect`; the handler never rejects.
- Error messages are cataloged in [errors.md](../errors.md).
```

--------------------------------

### Basic usage of createAuthorizeEndpoint

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/authorize-endpoint.md

Creates the authorize endpoint with basic OAuth2 configuration. The endpoint method is "get" and path is "/oauth/authorize". Navigating to "/api/users/oauth/authorize" returns a 302 redirect to the provider authorization URL with the specified parameters.

```ts
import { createAuthorizeEndpoint } from "payload-oauth2/dist/authorize-endpoint.js";

const endpoint = createAuthorizeEndpoint({
  clientId: "my-client",
  serverURL: "http://localhost:3000",
  authCollection: "users",
  callbackPath: "/oauth/google/callback",
  scopes: ["openid", "email"],
  providerAuthorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
  // ... other required PluginOptions fields
});
// endpoint.method === "get"
// endpoint.path === "/oauth/authorize"

// Browser navigation to "/api/users/oauth/authorize" produces:
// 302, Location: "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fapi%2Fusers%2Foauth%2Fgoogle%2Fcallback&scope=openid email&response_type=code&access_type=offline&nonce=..."
```

--------------------------------

### GET|POST /api/users/oauth/callback

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/endpoints.md

This endpoint is the OAuth provider redirect target. It handles both GET and POST requests from different provider types, extracting the authorization code and performing the OAuth callback flow.

```APIDOC
## GET|POST /api/users/oauth/callback

### Description
This endpoint is the OAuth provider redirect target. It handles both GET requests from query-based providers (e.g., Google) and POST requests from form_post providers (e.g., Apple). Both methods map to the same handler.

### Method
GET or POST

### Endpoint
/api/users/oauth/callback

### Parameters
#### Query Parameters (GET)
- **code** (string) - Required - The authorization code returned by the provider.

#### Request Body (POST form)
- **code** (string) - Required - The authorization code in application/x-www-form-urlencoded format.

#### Request Body (POST JSON)
- **code** (string) - Required - The authorization code in JSON format.

### Request Example
GET: /api/users/oauth/callback?code=abc123
POST (form): code=abc123
POST (JSON): {"code":"abc123"}

### Response
#### Success Response (302)
- **Set-Cookie** (string) - The payload token cookie.
- **Location** (string) - The success redirect URL.
- **Body** - None.

#### Response Example
HTTP/1.1 302 Found
Set-Cookie: payload-token=<jwt>; ...
Location: /success

#### Failure Response (302)
- **Content-Type** (string) - application/json
- **Location** (string) - The failure redirect URL.
- **Body** - None.

#### Response Example
HTTP/1.1 302 Found
Content-Type: application/json
Location: /error
```

--------------------------------

### createCallbackEndpoint(pluginOptions) → Endpoint[]

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/callback-endpoint.md

Factory function that returns two Payload Endpoints (GET and POST) for the OAuth2 callback path. The handler exchanges the authorization code for a token, resolves/creates the user, runs collection hooks, issues a Payload JWT, and redirects.

```APIDOC
## createCallbackEndpoint(pluginOptions) → Endpoint[]

### Description
Builds the two Payload Endpoints (GET and POST) that finish the OAuth2 flow: exchanging the authorization code for a token, resolving/creating the user, running collection hooks, issuing a Payload JWT, and redirecting.

### Method
- GET
- POST

### Endpoint
- `pluginOptions.callbackPath || "/oauth/callback"`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Request Example
- No request body required.

### Response
#### Success Response (200)
- Redirect response (302) to the `successRedirect` URL.

#### Response Example
- Redirect to the URL returned by `successRedirect`.

### Error Handling
- On failure, redirects to `failureRedirect` URL.

### Notes
- The same handler is used for both GET and POST requests.
- The `pluginOptions` object is resolved at build time into local shorthands used by the handler.

### Source
- `src/callback-endpoint.ts`, lines 20–266.
```

--------------------------------

### createCallbackEndpoint function signature

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/callback-endpoint.md

Defines the createCallbackEndpoint factory that returns an array of two Payload endpoints (GET and POST) sharing the same handler. The path defaults to '/oauth/callback' unless overridden by pluginOptions.callbackPath.

```typescript
export const createCallbackEndpoint = (
  pluginOptions: PluginOptions,
): Endpoint[] => {
  const handler: PayloadHandler = async (req: PayloadRequest) => {
    // ... see Behavior
  };

  const path = pluginOptions.callbackPath || "/oauth/callback";

  return [
    { method: "get", path, handler },
    { method: "post", path, handler },
  ];
};
```

--------------------------------

### Apple form_post callback and error handling

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-callback-extract-token.md

Handles Apple's POST callback with application/x-www-form-urlencoded content type. The code is parsed from the URLSearchParams of the raw body. Errors are thrown with messages starting with 'Code not found in POST form data:' or 'Unsupported content-type: ...' when the code is missing or the content type is unsupported.

```TypeScript
import { defaultCallbackExtractToken } from "payload-oauth2/dist/default-callback-extract-token.js";

// Apple sends POST application/x-www-form-urlencoded with code=...&state=...

try {
  const code = await defaultCallbackExtractToken(req);
  // code parsed from the URLSearchParams of the raw body
} catch (e) {
  // e.message starts with "Code not found in POST form data:" when code is missing
  // or "Unsupported content-type: ..." when the provider used another content type
}

// Supplying a custom extractor through PluginOptions:
// callbackExtractToken: (req) => req.query.get("code") || ""
```

--------------------------------

### Error handling and custom expiration with generateAppleClientSecret

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/generate-apple-client-secret.md

Error handling and custom expiration. The exp option sets the JWT expiration in seconds since epoch; the example uses 30 days. Missing parameters throw 'Missing required parameters: teamId, clientId, keyId, privateKey' and exp beyond 180 days throws 'exp may not exceed 180 days from iat per Apple policy'.

```ts
import { generateAppleClientSecret } from "payload-oauth2/dist/generate-apple-client-secret.js";

try {
  const jwt = await generateAppleClientSecret({
    teamId: "4659F6UUC3",
    clientId: "com.example.app.sso",
    keyId: "XXXXXXXXXX",
    authKeyContent: p8Content,
    exp: Math.floor(Date.now() / 1000) + 86400 * 30, // 30 days
  });
} catch (e) {
  // missing params → 'Missing required parameters: teamId, clientId, keyId, privateKey'
  // exp too far → 'exp may not exceed 180 days from iat per Apple policy'
}
```

--------------------------------

### Basic usage of defaultGetPkceCodes with token exchange

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-get-pkce-codes.md

Shows basic usage: generate PKCE codes, store the verifier in a cookie named 'pkce_verifier' with a 10-minute maxAge, then on the callback pass the verifier to defaultGetToken which appends it as code_verifier. The verifier must be kept and replayed in the token exchange.

```ts
import { defaultGetPkceCodes } from "payload-oauth2/dist/default-get-pkce-codes.js";
import { defaultGetToken } from "payload-oauth2";

// Steps across two requests:
const codes = defaultGetPkceCodes();
setCookie("pkce_verifier", codes.verifier, { maxAge: 600, sameSite: "Lax" });
// ... user authorizes at the provider with code_challenge=codes.challenge ...

// On the callback, defaultGetToken reads the cookie and appends:
//   code_verifier=codes.verifier
await defaultGetToken(tokenEndpoint, clientId, clientSecret, redirectUri, code, true, req);
```

--------------------------------

### encodeBase64Url and defaultGetPkceCodes implementation

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-get-pkce-codes.md

Defines the two exported helpers: encodeBase64Url converts a Buffer to base64url by replacing '+' with '-', '/' with '_', and stripping trailing '=' padding; defaultGetPkceCodes generates a 32-byte random verifier, its SHA-256 digest as the challenge, and returns the object with challengeMethod 'S256'.

```ts
export const encodeBase64Url = (buffer: Buffer) => {
  return buffer.toString('base64')
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/g, '')
}

export const defaultGetPkceCodes = () => {
  const verifier = encodeBase64Url(crypto.randomBytes(32))
  const challenge = encodeBase64Url(crypto.createHash('sha256').update(verifier).digest())
  return { verifier, challenge, challengeMethod: 'S256' };
}
```

--------------------------------

### CLI wrapper usage for generate-apple-client-secret

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/generate-apple-client-secret.md

CLI wrapper usage. The command reads the key file, calls generateAppleClientSecret, prints the JWT to stdout, and exits 1 with a stderr message on failure. Options: --team-id, --client-id, --key-id, --private-key-path (all required), and --exp (optional, seconds since epoch). Note: package.json restricts published files to dist while bin points to ./bin/generate-apple-client-secret.mjs, so CLI entry depends on the bin directory being present.

```sh
pnpm payload-oauth2:generate-apple-client-secret \
  --team-id 4659F6UUC3 \
  --client-id com.example.app.sso \
  --key-id XXXXXXXXXX \
  --private-key-path AuthKey_XXXXXXXXXX.p8
```

--------------------------------

### Import top-level exports from payload-oauth2

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/index.md

Import the three top-level exports from the package entry point. Use this to access the plugin factory, the default token exchange helper, and the type alias for plugin options.

```ts
import { OAuth2Plugin, defaultGetToken, PluginTypes } from "payload-oauth2";
```

--------------------------------

### defaultCallbackExtractToken function implementation

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-callback-extract-token.md

Extracts the OAuth authorization code from a PayloadRequest. Handles POST with form-urlencoded, POST with JSON, and GET query parameters. Throws errors when the code is missing or the content type is unsupported.

```TypeScript
export const defaultCallbackExtractToken = async (
  req: PayloadRequest,
): Promise<string> => {
  if (req.method === "POST") {
    // Handle form data from POST request (used by Apple OAuth)
    const contentType = req.headers.get("content-type");
    if (contentType?.includes("application/x-www-form-urlencoded")) {
      const text = await (req as unknown as Request).text();
      const formData = new URLSearchParams(text);
      const code = formData.get("code");
      if (typeof code === "string") {
        return code;
      } else {
        throw new Error(`Code not found in POST form data: ${text}`);
      }
    } else if (contentType?.includes("application/json")) {
      if (typeof req.json === "function") {
        const body = await req.json();
        if (typeof body.code === "string") {
          return body.code;
        } else {
          throw new Error(
            `Code not found in POST request body: ${JSON.stringify(body)}`,
          );
        }
      }
    } else {
      throw new Error(
        `Unsupported content-type: ${contentType} received in POST callback endpoint`,
      );
    }
  } else if (req.method === "GET") {
    // Handle query parameters (used by Google OAuth)
    if (typeof req.query === "object" && typeof req.query.code === "string") {
      return req.query.code;
    } else {
      throw new Error(
        `Code not found in GET request query param: ${JSON.stringify(req.query)}`,
      );
    }
  }
  throw new Error("Authorization code not found in callback request");
};
```

--------------------------------

### Catch errors from standalone helpers (defaultGetToken, generateAppleClientSecret)

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/errors.md

Wrap standalone helper calls in try/catch because they reject normally. defaultGetToken throws with message 'No access token: {"error":"invalid_grant",...}' on failure. generateAppleClientSecret throws for missing required parameters or when exp exceeds 180 days from iat per Apple policy.

```ts
import { defaultGetToken } from "payload-oauth2";

try {
  await defaultGetToken(tokenEndpoint, clientId, clientSecret, redirectUri, code);
} catch (e) {
  // e.message === 'No access token: {"error":"invalid_grant",...}'
}
```

```ts
import { generateAppleClientSecret } from "payload-oauth2/dist/generate-apple-client-secret.js";

try {
  await generateAppleClientSecret({ teamId, clientId, keyId, authKeyContent, exp });
} catch (e) {
  // e.message === "Missing required parameters: teamId, clientId, keyId, privateKey"
  //        or  "exp may not exceed 180 days from iat per Apple policy"
}
```

--------------------------------

### Google OAuth2 authorize request (non-PKCE)

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/endpoints.md

Request the browser sends to Google when using the `examples/google.ts` configuration without PKCE. The query includes `client_id`, `redirect_uri`, `scope`, `response_type=code`, `access_type=offline`, and a `nonce`.

```http
GET https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fapi%2Fusers%2Foauth%2Fgoogle%2Fcallback&scope=openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile&response_type=code&access_type=offline&nonce=...
```

--------------------------------

### createAuthorizeEndpoint factory

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/authorize-endpoint.md

Factory that returns a Payload Endpoint for the OAuth2 authorization flow. The endpoint uses GET, defaults the path to "/oauth/authorize" unless pluginOptions.authorizePath is set, and its handler redirects the browser to the provider authorization URL (302) or answers Next.js RSC probe requests with 204.

```ts
export const createAuthorizeEndpoint = (
  pluginOptions: PluginOptions,
): Endpoint => ({
  method: "get",
  path: pluginOptions.authorizePath || "/oauth/authorize",
  handler: async (req: PayloadRequest) => {
    // ... see Behavior
  },
});
```

--------------------------------

### PKCE codes object contract

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-get-pkce-codes.md

The exact object contract returned by defaultGetPkceCodes and expected by PluginOptions.getPkceCodes. The verifier is a 43-character base64url string, the challenge is the SHA-256 digest of the verifier, and challengeMethod is the plain-text string 'S256'.

```ts
{ verifier: string, challenge: string, challengeMethod: string }
```

--------------------------------

### POST /api/users/oauth/callback

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/endpoints.md

Handles the OAuth callback via POST. The provider may send the callback as a POST request.

```APIDOC
## POST /api/users/oauth/callback

### Description
Handles the OAuth callback via POST. The provider may send the callback as a POST request.

### Method
POST

### Endpoint
/api/<authCollection><callbackPath> — default /api/users/oauth/callback

### Parameters
#### Request Body
- **code** (string) - Required - The authorization code returned by the provider.
- **state** (string) - Optional - The state parameter that was sent in the authorization request.

### Response
#### Success Response (302 Found)
- **Headers** - `Location: <redirectUrl>`
- **Body** - none

#### Error Response (400 Bad Request)
- **Body** - JSON error message

### Notes
- No authentication required.
- The callback handler operates on `req.payload` directly (no `req.user` checks) and issues its own JWT.
```

--------------------------------

### Configure OAuth2Plugin in payload.config.ts

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/configuration.md

Reference configuration for wiring the OAuth2Plugin into a Payload config. Requires a Users collection with slug "users" and auth.disableLocalStrategy set to true. Uses Google as the provider, with environment variables for secrets and URLs, and defines custom success/failure redirects.

```ts
// payload.config.ts
import { buildConfig } from "payload";
import { OAuth2Plugin } from "payload-oauth2";

export default buildConfig({
  secret: process.env.PAYLOAD_SECRET || "super-secret",
  collections: [Users], // Users: { slug: "users", auth: { disableLocalStrategy: true }, ... }
  plugins: [
    OAuth2Plugin({
      enabled: true,
      strategyName: "google",
      useEmailAsIdentity: true,
      serverURL: process.env.NEXT_PUBLIC_URL || "http://localhost:3000",
      clientId: process.env.GOOGLE_CLIENT_ID || "",
      clientSecret: process.env.GOOGLE_CLIENT_SECRET || "",
      authorizePath: "/oauth/google",
      callbackPath: "/oauth/google/callback",
      authCollection: "users",
      onUserNotFoundBehavior: "create",
      tokenEndpoint: "https://oauth2.googleapis.com/token",
      providerAuthorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
      scopes: ["openid", "https://www.googleapis.com/auth/userinfo.email"],
      getUserInfo: async (accessToken) => {
        const res = await fetch("https://www.googleapis.com/oauth2/v3/userinfo", {
          headers: { Authorization: `Bearer ${accessToken}` },
        });
        const user = await res.json();
        return { email: user.email, sub: user.sub };
      },
      successRedirect: () => "/admin",
      failureRedirect: (req, err) => {
        req.payload.logger.error(err);
        return "/admin/login";
      },
    }),
  ],
});
```

--------------------------------

### PluginOptions interface

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/authorize-endpoint.md

Type definition for the plugin options consumed by createAuthorizeEndpoint. Fields read at endpoint-build time include authorizePath, clientId, authCollection, callbackPath, authorizeRedirectUri, scopes, providerAuthorizationUrl, prompt, responseMode, authType, pkceEnabled, getPkceCodes, and serverURL. The serverURL is used to build the default redirect_uri, and scopes are joined with spaces into the scope parameter.

```ts
interface PluginOptions {
  enabled?: boolean;
  strategyName: string;
  useEmailAsIdentity?: boolean;
  excludeEmailFromJwtToken?: boolean;
  serverURL: string;                       // used to build the default redirect_uri
  responseMode?: string;                   // forwarded as response_mode param
  authCollection?: string;                 // default "users", part of redirect_uri
  subFieldName?: string;
  subField?: TextField;
  clientId: string;                        // forwarded as client_id
  clientSecret: string;
  tokenEndpoint: string;
  providerAuthorizationUrl: string;        // base URL the redirect points to
  authorizeRedirectUri?: string;           // overrides the default redirect_uri
  getUserInfo: (accessToken: string, req: PayloadRequest) => Promise<Record<string, unknown>>;
  callbackExtractToken?: (req: PayloadRequest) => Promise<string>;
  onUserNotFoundBehavior?: "create" | "error";
  scopes: string[];                        // joined with " " into the scope param
  authorizePath?: string;                  // endpoint path
  prompt?: string;                         // forwarded as prompt param
  authType?: string;                       // forwarded as auth_type param
  callbackPath?: string;                   // default "/oauth/callback", part of redirect_uri
  getToken?: (code: string, req: PayloadRequest) => Promise<string>;
  successRedirect(req: PayloadRequest): string | Promise<string>;
  successRedirect(req: PayloadRequest, accessToken: string): string | Promise<string>;
  failureRedirect: (req: PayloadRequest, error?: unknown) => string | Promise<string>;
  pkceEnabled?: boolean;                   // enables PKCE challenge + verifier cookie
  getPkceCodes?: () => { verifier: string, challenge: string, challengeMethod: string };
}
```

--------------------------------

### generateAppleClientSecret: Create Apple client_secret JWT

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/generate-apple-client-secret.md

Generates a signed JWT for use as the Apple `client_secret` in `PluginOptions`. Requires `teamId`, `clientId`, `keyId`, and `authKeyContent`; missing values throw an error. The `exp` parameter defaults to 180 days from now and must not exceed 180 days from `iat`, otherwise an error is thrown. The function replaces literal `\n` escapes in the private key content with real newlines and trims it before signing.

```ts
export async function generateAppleClientSecret({
  teamId,
  clientId,
  keyId,
  authKeyContent,
  exp,
}: AppleClientSecretParams) {
  if (!teamId || !clientId || !keyId || !authKeyContent) {
    throw new Error(
      "Missing required parameters: teamId, clientId, keyId, privateKey",
    );
  }
  const _authKeyContent = authKeyContent.replace(/\n/g, "\n").trim();
  const now = Math.floor(Date.now() / 1000);
  const alg = "ES256";
  const expiresAt = exp ?? now + 86400 * 180; // default 6 months

  if (expiresAt - now > 60 * 60 * 24 * 180) {
    throw new Error("exp may not exceed 180 days from iat per Apple policy");
  }
  const cryptoKey = await importPKCS8(_authKeyContent.trim(), alg);
  const jwt = await new SignJWT({})
    .setProtectedHeader({ alg, kid: keyId, typ: "JWT" })
    .setIssuer(teamId)
    .setSubject(clientId)
    .setAudience("https://appleid.apple.com")
    .setIssuedAt()
    .setExpirationTime(expiresAt)
    .sign(cryptoKey);
  return jwt;
}
```

--------------------------------

### Catch config-build failure for missing collection

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/errors.md

Config-build failure aborts Payload startup when the required collection is missing. Payload calls plugin(config) during buildConfig and throws Error: The collection with the slug "users" was not found.

```ts
import { OAuth2Plugin } from "payload-oauth2";

const plugin = OAuth2Plugin({ enabled: true, /* ... */ });
// Payload calls plugin(config) during buildConfig:
// throws  Error: The collection with the slug "users" was not found.
```

--------------------------------

### PluginOptions interface (inline expansion)

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/auth-strategy.md

Inline expansion of the PluginOptions type used by createAuthStrategy. Only strategyName, useEmailAsIdentity, subFieldName (via pluginOptions.subField?.name), and authCollection are read by the factory. Includes required fields like clientId, clientSecret, tokenEndpoint, providerAuthorizationUrl, getUserInfo, scopes, successRedirect, and failureRedirect.

```ts
interface PluginOptions {
  enabled?: boolean; accessType?: undefined;
  strategyName: string;
  useEmailAsIdentity?: boolean;
  excludeEmailFromJwtToken?: boolean;
  serverURL: string;
  responseMode?: string;
  authCollection?: string;
  subFieldName?: string;
  subField?: TextField;
  clientId: string;
  clientSecret: string;
  tokenEndpoint: string;
  providerAuthorizationUrl: string;
  authorizeRedirectUri?: string;
  getUserInfo: (accessToken: string, req: PayloadRequest) => Promise<Record<string, unknown>>;
  callbackExtract?: (req: PayloadRequest) => Promise<string>;
  onUserNotFoundBehavior?: "create" | "error";
  scopes: string[];
  authorizePath?: string;
  prompt?: string;
  authType?: string;
  callbackPath?: string;
  getToken?: (code: string, req: PayloadRequest) => Promise<string>;
  successRedirect(req: PayloadRequest): string | Promise<string>;
  successRedirect(req: PayloadRequest, accessToken: string): string | Promise<string>;
  failureRedirect: (req: PayloadRequest, error?: unknown) => string | Promise<string>;
  pkceEnabled?: boolean;
  getPkceCodes?: () => { verifier: string, challenge: string, challengeMethod: string };
}
```

--------------------------------

### PKCE + error handling with defaultGetToken

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-get-token.md

Usage with PKCE enabled and error handling. Pass true for pkceEnabled so the function reads the pkce_verifier cookie from req, and pass the PayloadRequest from the callback. On failure, the catch block receives an Error whose message is 'No access token: {"error":"invalid_grant",...}' (the JSON stringified token data).

```ts
import { defaultGetToken } from "payload-oauth2";

try {
  const token = await defaultGetToken(
    "https://provider.example.com/token",
    "spa-client-id",
    "spa-client-secret",
    "https://app.example.com/api/users/oauth/callback",
    code,
    true,   // pkceEnabled — reads the "pkce_verifier" cookie from req
    req,    // the PayloadRequest from the callback
  );
} catch (e) {
  // e.message === 'No access token: {"error":"invalid_grant",...}'
}
```

--------------------------------

### Handle authenticate() failures returning { user: null }

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/auth-strategy.md

Shows the error-handling behavior of `authenticate()`: it never rejects and returns `{ user: null }` on any failure. All errors are logged via `payload.logger.warn` or `payload.logger.error`. When `auth.useSessions` is enabled, a valid `sid` claim matching `user.sessions` is required; otherwise the user is never authenticated. User creation from JWT authentication does not happen automatically when sessions are active.

```ts
// authenticate() returns { user: null } on every failure instead of rejecting:
const result = await strategy.authenticate({ headers: { authorization: "Bearer bogus" }, payload: { secret: "x" } });
if (result.user === null) {
  // expired token, missing/unknown user, missing email/sub claim, revoked session, or any error
  // (all were logged via payload.logger.warn / payload.logger.error)
}
```

--------------------------------

### Import generateAppleClientSecret and AppleClientSecretParams

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/generate-apple-client-secret.md

Import these symbols from the compiled module path, as they are not re-exported from the top-level entry point.

```TypeScript
import {
  generateAppleClientSecret,
  AppleClientSecretParams,
} from "payload-oauth2/dist/generate-apple-client-secret.js";
```

--------------------------------

### Basic usage of generateAppleClientSecret

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/generate-apple-client-secret.md

Basic usage of generateAppleClientSecret. Requires teamId, clientId, keyId, and authKeyContent (the .p8 file content). Returns a signed JWT usable as PluginOptions.clientSecret for Apple.

```ts
import { generateAppleClientSecret } from "payload-oauth2/dist/generate-apple-client-secret.js";

const clientSecret = await generateAppleClientSecret({
  teamId: "4659F6UUC3",
  clientId: "com.example.app.sso",
  keyId: "XXXXXXXXXX",
  authKeyContent: fs.readFileSync("AuthKey_XXXXXXXXXX.p8", "utf8"),
});
// clientSecret — a signed JWT usable as PluginOptions.clientSecret for Apple
```

--------------------------------

### Import session helpers from payload-oauth2

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/auth-sessions.md

Import the four exported session helpers from the payload-oauth2 package. Use this import when you need to bridge OAuth2 logins with Payload v3's session-backed auth.

```ts
import {
  shouldUsePayloadSessions,
  removeExpiredPayloadSessions,
  userHasPayloadSession,
  addPayloadSessionToUser,
} from "payload-oauth2/dist/auth-sessions.js";
```

--------------------------------

### Basic usage of defaultGetToken

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-get-token.md

Basic usage of defaultGetToken with a Google token endpoint. It passes the provider token URL, client ID, client secret, redirect URI, and the authorization code, then logs the returned access token (e.g. "ya29....").

```ts
import { defaultGetToken } from "payload-oauth2";

const accessToken = await defaultGetToken(
  "https://oauth2.googleapis.com/token",
  "google-client-id",
  "google-client-secret",
  "http://localhost:3000/api/users/oauth/google/callback",
  "auth-code-from-provider",
);

console.log(accessToken); // e.g. "ya29...."
```

--------------------------------

### PKCE with custom code generator

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/authorize-endpoint.md

Enables PKCE with a custom code generator. The default generator is defaultGetPkceCodes() following RFC 7636 S256. The response sets a pkce_verifier cookie with Max-Age=600 and SameSite=Lax, and the verifier is later used by defaultGetToken to send code_verifier.

```ts
import { createAuthorizeEndpoint } from "payload-oauth2/dist/authorize-endpoint.js";

const endpoint = createAuthorizeEndpoint({
  clientId: "spa-client",
  serverURL: "https://app.example.com",
  scopes: ["openid"],
  providerAuthorizationUrl: "https://provider.example.com/authorize",
  pkceEnabled: true,
  getPkceCodes: () => {
    // custom generator; default is defaultGetPkceCodes() (RFC 7636 S256)
    return {
      verifier: "custom-verifier-value",
      challenge: "custom-challenge-value",
      challengeMethod: "S256",
    };
  },
  // ... other required PluginOptions fields
});

// Response: 302, Set-Cookie: pkce_verifier=custom-verifier-value; Max-Age=600; SameSite=Lax; Path=/
// Location: "...&code_challenge=custom-challenge-value&code_challenge_method=S256"
// The verifier cookie is later read by defaultGetToken during the callback to send code_verifier.
```

--------------------------------

### Basic usage of OAuth2Plugin in Payload config

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/plugin.md

Configures the OAuth2Plugin with Google OAuth2 settings, including strategy name, endpoints, scopes, and user info retrieval. Requires a Payload config with a Users collection and environment variables for client ID and secret.

```ts
import { buildConfig } from "payload";
import { OAuth2Plugin } from "payload-oauth2";

export default buildConfig({
  secret: process.env.PAYLOAD_SECRET || "super-secret",
  collections: [Users],
  plugins: [
    OAuth2Plugin({
      enabled: true,
      strategyName: "google",
      useEmailAsIdentity: true,
      serverURL: "http://localhost:3000",
      clientId: process.env.GOOGLE_CLIENT_ID || "",
      clientSecret: process.env.GOOGLE_CLIENT_SECRET || "",
      authorizePath: "/oauth/google",
      callbackPath: "/oauth/google/callback",
      authCollection: "users",
      tokenEndpoint: "https://oauth2.googleapis.com/token",
      providerAuthorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
      scopes: ["openid", "https://www.googleapis.com/auth/userinfo.email"],
      getUserInfo: async (accessToken) => {
        const res = await fetch("https://www.googleapis.com/oauth2/v3/userinfo", {
          headers: { Authorization: `Bearer ${accessToken}` },
        });
        const user = await res.json();
        return { email: user.email, sub: user.sub };
      },
      successRedirect: () => "/admin",
      failureRedirect: (req, err) => {
        req.payload.logger.error(err);
        return "/admin/login";
      },
    }),
  ],
});
```

--------------------------------

### Apple OAuth2 callback request (form_post)

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/endpoints.md

Callback request from Apple when `responseMode: "form_post"` is used. The body is `application/x-www-form-urlencoded` and contains `code` and `state`.

```http
POST /api/users/oauth/apple/callback HTTP/1.1
Content-Type: application/x-www-form-urlencoded

code=...&state=...
```

--------------------------------

### Custom extraction via PluginOptions

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/default-callback-extract-token.md

Shows how to provide a custom callbackExtractToken function to the OAuth2Plugin. The function receives the request and must return the authorization code. Throws an error if the code is missing.

```TypeScript
import { OAuth2Plugin } from "payload-oauth2";

OAuth2Plugin({
  // ...options
  callbackExtractToken: async (req) => {
    const code = req.searchParams.get("code");
    if (!code) throw new Error("My provider always sends ?code=");
    return code;
  },
});
```

--------------------------------

### Error handling / failing flow

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/callback-endpoint.md

Error handling flow when getUserInfo throws, the code is missing, or onUserNotFoundBehavior is "error" with an unknown user. The handler returns a 302 redirect to "/admin/login?error=..." with Content-Type "application/json". The handler never rejects; custom diagnostics belong in failureRedirect.

```ts
// When getUserInfo throws (e.g. provider error), or the code is missing, or
// onUserNotFoundBehavior is "error" and the user is unknown:
const response = await postEndpoint.handler(fakeReq); // some PayloadRequest
// response.status === 302
// response.headers.get("Location") === "/admin/login?error=..."
// response.headers.get("Content-Type") === "application/json"
// The callback handler itself never rejects; put any custom diagnostics in failureRedirect.
```

--------------------------------

### Register OAuth2 strategy with createAuthStrategy

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/auth-strategy.md

Use to register the OAuth2 strategy directly into an existing collection config. Requires the `payload-oauth2` package and the `createAuthStrategy` function from `payload-oauth2/dist/auth-strategy.js`. The strategy name is set to `"google"` and the identity is derived from the `"sub"` claim.

```ts
import { createAuthStrategy } from "payload-oauth2/dist/auth-strategy.js";
import { OAuth2Plugin } from "payload-oauth2";

// Normally reached via the plugin factory; direct use is for
// embedding the strategy into an existing collection config.
const opts = {
  strategyName: "google",
  useEmailAsIdentity: true,
  authCollection: "users",
  // ... other required PluginOptions fields
};
const strategy = createAuthStrategy(opts, "sub");
// strategy.name === "google"
```

--------------------------------

### PluginOptions interface definition

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/plugin.md

The inline expansion of the PluginOptions interface, showing all configuration fields with their types, defaults, and required status. This is the complete set of options accepted by the OAuth2Plugin factory.

```typescript
interface PluginOptions {
  enabled?: boolean;                    // @default false
  strategyName: string;                 // required
  useEmailAsIdentity?: boolean;         // @default false
  excludeEmailFromJwtToken?: boolean;   // @default false
  serverURL: string;                    // required
  responseMode?: string;                // @default undefined
  authCollection?: string;              // @default "users"
  subFieldName?: string;                // @default "sub"
  subField?: TextField;                 // overrides subFieldName if both given
  clientId: string;                     // required
  clientSecret: string;                 // required
  tokenEndpoint: string;                // required
  providerAuthorizationUrl: string;     // required
  authorizeRedirectUri?: string;
  getUserInfo: (accessToken: string, req: PayloadRequest) => Promise<Record<string, unknown>>; // required
  callbackExtractToken?: (req: PayloadRequest) => Promise<string>;
  onUserNotFoundBehavior?: "create" | "error"; // @default "create"
  scopes: string[];                     // required
  authorizePath?: string;               // @default "/oauth/authorize"
  prompt?: string;
  authType?: string;
  callbackPath?: string;                // @default "/oauth/callback"
  getToken?: (code: string, req: PayloadRequest) => Promise<string>;
  successRedirect(req: PayloadRequest): string | Promise<string>;                // overload 1 (deprecated)
  successRedirect(req: PayloadRequest, accessToken: string): string | Promise<string>; // overload 2
  failureRedirect: (req: PayloadRequest, error?: unknown) => string | Promise<string>;  // required
  pkceEnabled?: boolean;                // @default false
  getPkceCodes?: () => { verifier: string, challenge: string, challengeMethod: string };
}
```

--------------------------------

### OAuth2Plugin factory implementation

Source: https://github.com/wilsonle/payload-oauth2/blob/main/_autodocs/api-reference/plugin.md

The main plugin factory function. It returns a Payload Plugin that modifies the config by replacing the auth collection with a modified version. If pluginOptions.enabled is false, it returns the config unchanged. Throws an error if the auth collection is not found.

```typescript
export const OAuth2Plugin =
  (pluginOptions: PluginOptions): Plugin =>
  (incomingConfig) => {
    let config = { ...incomingConfig };

    if (pluginOptions.enabled === false) {
      return config;
    }

    // /////////////////////////////////////
    // Modify auth collection
    // /////////////////////////////////////
    const authCollectionSlug = pluginOptions.authCollection || "users";
    const subFieldName =
      pluginOptions.subField?.name || pluginOptions.subFieldName || "sub";
    const authCollection = config.collections?.find(
      (collection) => collection.slug === authCollectionSlug,
    );
    if (!authCollection) {
      throw new Error(
        `The collection with the slug "${authCollectionSlug}" was not found.`,
      );
    }
    const modifiedAuthCollection = modifyAuthCollection(
      pluginOptions,
      authCollection,
      subFieldName,
    );

    config.collections = [
      ...(config.collections?.filter(
        (collection) => collection.slug !== authCollectionSlug,
      ) || []),
      modifiedAuthCollection,
    ];

    return config;
  };
```
Tokens:
Raw