Skip to content
Migrating from NextAuth.js v4? Read our migration guide.
GuidesConfiguring OAuth providers

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:

./auth.ts
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.

./auth.ts
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:

./auth.ts
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 interface that 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 {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! 🎉

Auth.js © Balázs Orbán and Team - 2024