Not enough information about custom OAuth providers in next-auth-v5

[sukalov]

What is the improvement or update you wish to see?

I couldn't find what exactly changed considering custom built OAuth providers. But the problem is — i had a custom Lichess provider, that worked in next-auth-v4, and doesn't work in v5. I've described it in detail here (both provider source code, and error details). Duplicating only the original provider source code here:

import { Provider } from 'next-auth/providers'

export default function LichessProvider(options: any): Provider {
	return {
		id: 'lichess',
		name: 'Lichess',
		type: 'oauth',
		version: '2.0',
		authorization: {
			url: 'https://lichess.org/oauth/',
			params: {
				scope: 'email:read',
			},
		},
		token: {
			url: 'https://lichess.org/api/token',

			async request({ client, params, checks, provider }) {
				const response = await client.oauthCallback(provider.callbackUrl, params, checks, {
					exchangeBody: {
						client_id: options.clientId,
					},
				})
				return {
					tokens: response,
				}
			},
		},
		userinfo: {
			url: 'https://lichess.org/api/account',
			params: {
				scope: 'email:read',
			},
		},

		profile(data: any) {
			return {
				id: data.id,
				username: data.username,
				name: `${data.profile.firstName} ${data.profile.lastName}`,
			}
		},

		checks: ['pkce', 'state'],
		options,
	}
}

Is there any context that might help us understand?

here is the most common error I received while playing around with provider configuration:

error {
  error: 'invalid_request',
  error_description: 'client_id required (choose any)'
}
[auth][error] CallbackRouteError: Read more at https://errors.authjs.dev#callbackrouteerror
[auth][cause]: Error: TODO: Handle OAuth 2.0 response body error
    at handleOAuth (webpack-internal:///(rsc)/./node_modules/next-auth/node_modules/@auth/core/lib/actions/callback/oauth/callback.js:88:19)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async Module.callback (webpack-internal:///(rsc)/./node_modules/next-auth/node_modules/@auth/core/lib/actions/callback/index.js:33:41)
    at async AuthInternal (webpack-internal:///(rsc)/./node_modules/next-auth/node_modules/@auth/core/lib/index.js:42:24)
    at async Auth (webpack-internal:///(rsc)/./node_modules/next-auth/node_modules/@auth/core/index.js:123:29)
    at async /Users/matvey/Documents/mktour/node_modules/next/dist/compiled/next-server/app-route.runtime.dev.js:6:63251
[auth][details]: {
  "provider": "lichess"
}

Does the docs page already exist? Please link to it.

No response

[Hannah-goodridge]

Would be really great to be able to see this documentation for custom oauth providers.

[ndom91]

Hey folks, we recently shipped a new docs site which includes a guides page on customizing existing providers and writing new ones for v5: https://authjs.dev/guides/configuring-oauth-providers

I hope this and the other info in the new docs site is enough :pray:

If you need some additional help, feel free to open a new issue.