Enable sign-in with GitHub, Google, or another supported provider.
OAuth login
Better Auth · Pipe
socialProviders
socialProviders configures social login providers in Better Auth. Each provider entry supplies OAuth credentials and can optionally customize redirects, scopes, and profile mapping.
How it works
socialProviders is an authentication configuration map whose keys identify providers such as Google or GitHub. Each provider entry supplies OAuth credentials and may also customize callback routing, requested scopes, or profile-to-user mapping.
Syntax
betterAuth({ socialProviders: { [provider]: { clientId, clientSecret, ...options } } })Parameters
| Name | Type | Description |
|---|---|---|
socialProviders | Record<string, SocialProviderConfig> | Map of provider names to OAuth configuration objects. |
Returns
No standalone return value; this option configures Better Auth's social login providers.
Key points
- Add providers under the
socialProvidersoption in the Better Auth configuration. clientIdidentifies the OAuth application registered with the social provider.clientSecretauthenticates the server-side application to the OAuth provider.- Some providers use
clientKeyrather than the usualclientIdfield. - Use
scopeto request additional permissions beyond the provider’s defaults. - Use
mapProfileToUserwhen the provider profile needs custom conversion into a Better Auth user.
Common mistakes
- Set a custom callback URI only when the provider configuration and registered OAuth redirect address require one.
Example: Configure GitHub login
import { betterAuth } from "better-auth";
export const auth = betterAuth({
socialProviders: {
github: {
clientId: process.env.GITHUB_CLIENT_ID!,
clientSecret: process.env.GITHUB_CLIENT_SECRET!,
},
},
});Registers GitHub as an OAuth social provider using credentials supplied through environment variables.
When to use it
Set a provider-specific OAuth callback URI with `redirectURI`.
Callback customization
Request additional provider permissions using `scope`.
Permission requests
Transform a provider profile into a Better Auth user with `mapProfileToUser`.
User normalization
Interview questions
QWhat is the purpose of socialProviders?
socialProviders is an option on the object passed to betterAuth. Its nested keys name providers, and each provider configuration commonly contains clientId and clientSecret.
Follow-up: How can a provider’s OAuth behavior be customized? Add optional settings such as redirectURI, extra scope values, or mapProfileToUser.
QHow is a GitHub provider configured?
The provider key selects the social provider, while the nested values configure that provider. For example, github can contain the GitHub OAuth client ID and secret.
Follow-up: What should be checked if login fails after configuration? Verify the credentials and ensure the callback URI matches the provider registration.
QHow does an application use a configured social provider?
After configuration, the client can invoke signIn.social to begin social authentication. Better Auth also supports authenticating with a provider idToken or accessToken instead of redirecting to the provider.
Follow-up: When might token-based sign-in be useful? It can be used when the application already obtained a provider token and does not need a browser redirect.
Related
signIn.socialclientIdclientSecretclientKeyredirectURIscopemapProfileToUserGeneric OAuth Plugin