RFC: Improve OAuth provider configuration

[balazsorban44]

Summary of proposed feature
Introducing a new way of configuring OAuth providers. With this proposal, we can provide granular control from basic (with the best defaults we can think of) to completely controlled hooks into the login flow. (The user would be able to do the actual fetch calls themselves. Hopefully, this will almost never would be necessary)

Here is an example:

export default function Auth0(options) {
  return {
    id: "auth0",
    name: "Auth0",
    authorization: `https://${options.domain}/authorize?grant_type=authorization_code&response_type=code&scope=openid%20email%20profile`,
    // Alternatively, you could pass an url and params
    // which will be combined for you for convinience.
    // authorization: {
    //   url: `https://${options.domain}/authorize`,
    //   params: {
    //     grant_type: "authorization_code",
    //     response_type: "code",
    //     scope: "openid email profile",
    //   },
    // },
    // Skips fetching user data. In some rare situations, you may not need this. See #1065
    userinfo: null,
    token: {
      url: `https://${options.domain}/oauth/token`,
      method: "POST",
      via: "header",
      // Complete control over how to get the userinfo.
      async request({ tokens }) {
        const response = await fetch("custom/endpoint/token", {
          headers: {
            Authorization: `Bearer ${tokens.access_token}`,
          },
        })
        return await response.json()
      },
    },
    profile(profile) {
      return {
        id: profile.sub,
        name: profile.nickname,
        email: profile.email,
        image: profile.picture,
      }
    },
    ...options,
  }
}

Purpose of proposed feature
To simplify the configuration by reducing the number of required fields, but give full control at the same time, for advanced use cases.

Detail about proposed feature

So to sum it up, 3 new methods could be introduced, using a similar shape:

/** Any contextual information that makes the request useful, eg.: tokens in case of the token endpoint */
type RequestContext = any

type OAuthEndpoint = string | null | {
  url?: string
  method?: "POST" | "GET"
  /** How to pass the access token */
  via?: "header" | "body" | "query"
  /** Will be used as URL params if method is GET, or the body as x-url-form-encoded if POST*/
  params?: URLSearchParams | Record<string, unknown>
  request(context: RequestContext)?: Promise<any>
}

Potential problems
As there are no conflicting configuration options, this could be implemented in a non-breaking way, meaning in theory we don't have to wait until the next major version.

Describe any alternatives you've considered
The current configuration is fragile since the OAuth spec can be interpreted differently, which often ends up with slightly too specific implementations, which has been hard to handle until now. The best solution was one-off configuration flags for certain providers, but in the long term, it introduced bloat in the code.

Additional context

Please indicate if you are willing and able to help implement the proposed feature.
Could fit neatly into #1698, or a follow-up PR.

Related: #1065, #1642, #1605, #1607, #1756, #950

Please share your opinions!

[Fronix]

I feel this would make next-auth a lot more flexible and allow support for pretty much any provider. It is usually the get token part that differs between providers with some using POST other GET, some using pkce and so on. This would make it much easier to let users customize every provider!

If I'm understanding correct parts like this wouldn't be needed for providers that haven't been added to next-auth?
src/server/lib/oauth/client.js

  if (provider.id === 'reddit') {
    headers.Authorization = 'Basic ' + Buffer.from((provider.clientId + ':' + provider.clientSecret)).toString('base64')
  }


  if (provider.id === 'identity-server4' && !headers.Authorization) {
    headers.Authorization = `Bearer ${code}`
  }


  if (provider.protection.includes('pkce')) {
    params.code_verifier = codeVerifier
  }

[balazsorban44]

Yes, we could remove a lot of custom handling for providers as well.

[balazsorban44]

Hmm. 🤔 I was thinking that the profile callback could even be the request method of the new userinfo, further simplifying things...

[Bedol]

Looks like this kind of configuration will allow the implementation of other OAuth grant types.

[jackHedaya]

I'm digging this proposal. I turned away from using NextAuth simply because the OAuth provider I was using did not fit the library but with fine tune control like this I would be interested in giving it another shot.

[valstu]

This could be solution to my problem as well. I'm using identity provider which requires that all authentication and token requests are signed with private key. Atm this is impossible without forking next-auth.

[valstu]

Actually ended up using patch-package to monkey patch next-auth same way @Fronix mentioned on #950. But in conclusion I feel like the features mentions in this RFC would make it possible to integrate with many new providers without bloating the next-auth core with if (provider.id === 'mycustomprovider') {} blocks. I ended up monkey patching three separate files:

• getAuthorizationUrl function on server/lib/signing/oauth.js
• getOAuth2AccessToken function on server/lib/oauth/client.js
• getProfile function on server/lib/oauth/callback.js

In the first two I needed to sign the requests and send data as JWS instead of typical query string. In the getProfile function I needed to decrypt the response with providers public key.

In my case the provider is quite specific (so called strong authentication for Finnish audience only) and requires these extra security measures. I could of course make a PR and add this provider to next-auth but I feel like adding this logic in next-auth core seems a bit overkill and would just bloat the code since the usage would be quite marginal. So thumbs up for this RFC.

[balazsorban44]

For anyone following, I started working on this over at #2411. It is very early, so please be patient, but if you have anything constructive, please add it here, or on the PR!

[balazsorban44]

This has landed in the next-auth@4.0.0-next.20, please give this a try! Update to the documentation is coming in a subsequent PR, for now, see #2411 (comment) for an explanation. I hope it is helpful enough.

I kindly ask anyone who has one of the built-in providers dear to their heart to test it out and open an issue if it broke! I would like to make the migration to v4 smooth for anyone, and I will need help from the community, as we have 50+ built-in providers, and @ndom91 could not get an account for all of those! Please spread the word.