Configuring an OAuth provider
Override default provider config
For built-in providers, usually you only need to specify a client id and client secret, and in case of OIDC (OpenID Connect), an issuer as well. We can infer these from environment variables.
If you need to override any of the defaults provider config options, you can add them in the provider’s function call and they will be deeply-merged with our defaults.
That means you only have to override part of the options that you need to be different. For example if you want different scopes, overriding authorization.params.scope is enough, instead of the whole authorization option.
For example, to override a provider’s default scopes, you can do the following:
import NextAuth from "next-auth";
import Auth0 from "next-auth/providers/auth0";
export const { handlers, auth } = NextAuth({
providers: [
Auth0({ authorization: { params: { scope: "openid custom_scope" } } }),
],
});Another example, the profile callback will return name, email and picture by default, but you might want to return more information from the provider. What you return will be used to create the user object in the database.
import NextAuth from "next-auth";
import Auth0 from "next-auth/providers/auth0";
export const { handlers, auth } = NextAuth({
providers: [
Auth0({
// You can also make calls to external resources if necessary.
async profile(profile) {
return {};
},
}),
],
});Use your own provider
Check our built-in OAuth providers first, before creating one from scratch.
We support any OAuth or OIDC compliant provider.
Start by passing an object to the providers list:
import NextAuth from "next-auth";
export const { handlers, auth } = NextAuth({
providers: [{
id: "my-provider", // signIn("my-provider") and will be part of the callback URL
name: "My Provider", // optional, used on the default login page as the button text.
type: "oidc", // or "oauth" for OAuth 2 providers
issuer: "https://my.oidc-provider.com", // to infer the .well-known/openid-configuration URL
clientId: process.env.AUTH_CLIENT_ID, // from the provider's dashboard
clientSecret: process.env.AUTH_CLIENT_SECRET, // from the provider's dashboard
}],
});Then, set the callback URL in your provider’s dashboard to https://app.com/{basePath}/callback/{id}.
By default, basePath is /api/auth for Next.js, and /auth in all other
integrations. See basePath.
That’s it! 🎉
Adding a new built-in provider
If you think your custom provider might be useful to others, we encourage you to open a PR and add it to the built-in list.
Creating the provider’s file
Create a new {provider}.ts file under the packages/core/src/providers directory.
Adhere to our code conventions
Use the built-in providers as a guide, make sure your provider adheres to the same code conventions, .i.e:
- Use TypeScript
- Use a named default export:
export default function YourProvider - Export the TypeScript
interfacethat defines the provider’s available user info properties - Add the necessary JSDoc comments/documentation. For example, the Auth0 provider is a good example for OIDC and the GitHub Provider is an OAuth provider.)
- Add links to the provider’s API reference/documentation so others can understand how to set up this provider
Add your provider in the GitHub issues dropdown
Add the new provider name to the Provider type dropdown options in the provider issue template
Add a logo
Add a logo {provider}.svg to the
docs/static/img/providers directory.
Once the PR is merged, others will also be able to discover and use this provider with any of our integrations. That’s it! 🎉