Better Auth · Const

genericOAuth

genericOAuth registers custom OAuth 2.0 or OIDC providers in Better Auth. It supports provider-specific discovery, endpoints, profile mapping, and the standard social sign-in flow.

How it works

genericOAuth creates a configurable OAuth integration for providers that are not built in. You supply one or more provider configurations, including an identifier, credentials, and usually a discovery URL; the plugin then exposes the provider through Better Auth's social-provider flow, with PKCE and issuer validation enabled by default.

Syntax

genericOAuth({ config: GenericOAuthConfig[] })

Parameters

Name	Type	Description
`options.config`	`GenericOAuthConfig[]`	An array of generic OAuth provider configurations, each containing provider-specific credentials and discovery or endpoint settings.
`config[].providerId`	`string`	The provider's stable identifier, used by the social sign-in flow and callback URL.
`config[].clientId / config[].clientSecret`	`string`	OAuth client credentials issued by the provider.
`config[].discoveryUrl`	`string`	The provider's OpenID Connect discovery document URL.

Returns

A Better Auth plugin configuration that registers the supplied generic OAuth providers.

Key points

Use this plugin when the provider implements OAuth 2.0 or OIDC but lacks a dedicated Better Auth integration.
After registration, authentication follows Better Auth's normal social sign-in interface rather than a separate legacy OAuth API.
The default flow includes PKCE and issuer checking, reducing the need for manual security configuration.
A helper can replace repetitive manual endpoint and profile configuration for supported providers.
Use mapProfileToUser when the provider's profile shape does not directly match Better Auth's user fields.
Use getToken when the provider's token exchange differs from the usual request format.

Common mistakes

The callback URL must contain the configured provider identifier; it is not optional.

Example: Register a generic OAuth provider

import { betterAuth } from "better-auth";
import { genericOAuth } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [
    genericOAuth({
      config: [{
        providerId: "acme",
        clientId: process.env.ACME_CLIENT_ID!,
        clientSecret: process.env.ACME_CLIENT_SECRET!,
        discoveryUrl: "https://auth.example.com/.well-known/openid-configuration",
      }],
    }),
  ],
});

Registers a custom OAuth or OIDC provider using its discovery document and credentials.

When to use it

Add a custom identity provider

A provider supports OAuth 2.0 or OIDC but has no built-in Better Auth integration.

Adapt non-standard provider responses

A provider exposes unusual token or profile APIs.

Register multiple providers

Several providers share the same authentication setup pattern.

Map external profiles

A provider's profile fields use names or shapes that differ from the user model.

Interview questions

QWhat problem does genericOAuth solve?

It is the Better Auth plugin for adding OAuth 2.0 or OIDC providers that are not built in. A configuration identifies the provider and supplies credentials plus discovery or endpoint information.

Follow-up: How does a provider enter the sign-in flow? It is registered as a social provider and used with the standard signIn.social API.

QHow should the OAuth callback URL be configured?

The provider callback uses Better Auth's core callback route, /api/auth/callback/:providerId by default. The provider ID in that route must equal the configured providerId.

Follow-up: What changed from the older route? Older configurations used /api/auth/oauth2/callback/:id; current configurations use /api/auth/callback/:id.

QWhich security behaviors are enabled by default?

PKCE is enabled by default, and issuer validation is automatic in the current implementation. This improves protection against authorization-code interception and responses from an unintended issuer.

Follow-up: When should PKCE be disabled? Only when the provider rejects PKCE, by setting pkce: false.

GenericOAuthConfig
signIn.social
linkSocial
getToken
getUserInfo
mapProfileToUser
authorizationUrlParams
tokenUrlParams

Source: Other Provider Configurations | Better Auth. Checked 2026-10-15.