feat(oauth): expose custom fetch (#11975)

* chore: upgrade packages

* drop unused imports

* feat: expose custom `fetch` option

* properly forward user option, add corporate proxy guide

* add to sidebar

* expose `customFetch` symbol from `next-auth`

* expose `customFetch` from other frameworks too

Author: balazsorban44

docs/pages/guides/_meta.js

@@ -6,12 +6,13 @@ export default {
   "extending-the-session": "Extending the Session",
   "restricting-user-access": "Restricting users accessing to the app",
   "role-based-access-control": "Role-Based Access Control",
+  "corporate-proxy": "Supporting Corporate Proxies",
+  "edge-compatibility": "Edge Compatibility",
   "configuring-github": "Configuring GitHub for OAuth",
   "configuring-resend": "Configuring Resend for magic links",
   "configuring-oauth-providers": "Configuring OAuth providers",
   "configuring-http-email": "Configuring Custom HTTP Email Provider",
   "creating-a-database-adapter": "Creating a Database Adapter",
   "creating-a-framework-integration": "Creating a Framework Integration",
   "refresh-token-rotation": "Refresh Token Rotation",
-  "edge-compatibility": "Edge Compatibility",
 }

docs/pages/guides/corporate-proxy.mdx

@@ -0,0 +1,32 @@
+import { Code } from "@/components/Code"
+
+# Supporting corporate proxies
+
+Auth.js libraries like NextAuth.js use the `fetch` API to communicate with OAuth providers. If your organization uses a corporate proxy, you may need to configure the `fetch` API to use the proxy.
+
+## Using a custom fetch function
+
+You can provide a custom `fetch` function to NextAuth.js by passing it as an option to the provider. This allows you to configure the `fetch` function to use a proxy.
+
+Here, we use the `undici` library to make requests through a proxy server. We create a custom `fetch` function that uses `undici` and the `ProxyAgent` library to make requests through the proxy server.
+
+<Code>
+  <Code.Next>
+
+```tsx filename="auth.ts"
+import NextAuth, { customFetch } from "next-auth"
+import GitHub from "next-auth/providers/github"
+
+const dispatcher = new ProxyAgent("my.proxy.server")
+function proxy(...args: Parameters<typeof fetch>): ReturnType<typeof fetch> {
+  // @ts-expect-error `undici` has a `duplex` option
+  return undici(args[0], { ...(args[1] ?? {}), dispatcher })
+}
+
+export const { handlers, auth } = NextAuth({
+  providers: [GitHub({ [customFetch]: proxy })],
+})
+```
+
+  </Code.Next>
+</Code>

packages/core/src/index.ts

@@ -67,6 +67,7 @@ import type { CredentialInput, Provider } from "./providers/index.js"
 import { JWT, JWTOptions } from "./jwt.js"
 import { isAuthAction } from "./lib/utils/actions.js"
 
+export { customFetch } from "./lib/utils/custom-fetch.js"
 export { skipCSRFCheck, raw, setEnvDefaults, createActionURL, isAuthAction }
 
 export async function Auth(

packages/core/src/lib/actions/callback/oauth/callback.ts

@@ -17,6 +17,7 @@ import type {
 import { type OAuthConfigInternal } from "../../../../providers/index.js"
 import type { Cookie } from "../../../utils/cookie.js"
 import { isOIDCProvider } from "../../../utils/providers.js"
+import { fetchOpt } from "../../../utils/custom-fetch.js"
 
 /**
  * Handles the following OAuth steps.
@@ -33,6 +34,7 @@ export async function handleOAuth(
   options: InternalOptions<"oauth" | "oidc">
 ) {
   const { logger, provider } = options
+
   let as: o.AuthorizationServer
 
   const { token, userinfo } = provider
@@ -44,7 +46,10 @@ export async function handleOAuth(
     // We assume that issuer is always defined as this has been asserted earlier
 
     const issuer = new URL(provider.issuer!)
-    const discoveryResponse = await o.discoveryRequest(issuer)
+    const discoveryResponse = await o.discoveryRequest(
+      issuer,
+      fetchOpt(provider)
+    )
     const discoveredAs = await o.processDiscoveryResponse(
       issuer,
       discoveryResponse
@@ -114,7 +119,7 @@ export async function handleOAuth(
         ) {
           args[1].body.delete("code_verifier")
         }
-        return fetch(...args)
+        return fetchOpt(provider)[o.customFetch](...args)
       },
       clientPrivateKey: provider.token?.clientPrivateKey,
     }
@@ -159,7 +164,8 @@ export async function handleOAuth(
       const userinfoResponse = await o.userInfoRequest(
         as,
         client,
-        processedCodeResponse.access_token
+        processedCodeResponse.access_token,
+        fetchOpt(provider)
       )
 
       profile = await o.processUserInfoResponse(
@@ -190,7 +196,8 @@ export async function handleOAuth(
       const userinfoResponse = await o.userInfoRequest(
         as,
         client,
-        processedCodeResponse.access_token
+        processedCodeResponse.access_token,
+        fetchOpt(provider)
       )
       profile = await userinfoResponse.json()
     } else {

packages/core/src/lib/actions/signin/authorization-url.ts

@@ -3,6 +3,7 @@ import * as o from "oauth4webapi"
 
 import type { InternalOptions, RequestInternal } from "../../../types.js"
 import type { Cookie } from "../../utils/cookie.js"
+import { fetchOpt } from "../../utils/custom-fetch.js"
 
 /**
  * Generates an authorization/request token URL.
@@ -24,7 +25,10 @@ export async function getAuthorizationUrl(
     // We check this in assert.ts
 
     const issuer = new URL(provider.issuer!)
-    const discoveryResponse = await o.discoveryRequest(issuer)
+    const discoveryResponse = await o.discoveryRequest(
+      issuer,
+      fetchOpt(options.provider)
+    )
     const as = await o.processDiscoveryResponse(issuer, discoveryResponse)
 
     if (!as.authorization_endpoint) {

packages/core/src/lib/init.ts

@@ -52,7 +52,7 @@ export const defaultCallbacks: InternalOptions["callbacks"] = {
 
 /** Initialize all internal options and cookies. */
 export async function init({
-  authOptions,
+  authOptions: config,
   providerId,
   action,
   url,
@@ -65,13 +65,8 @@ export async function init({
   options: InternalOptions
   cookies: cookie.Cookie[]
 }> {
-  const logger = setLogger(authOptions)
-  const { providers, provider } = parseProviders({
-    providers: authOptions.providers,
-    url,
-    providerId,
-    options: authOptions,
-  })
+  const logger = setLogger(config)
+  const { providers, provider } = parseProviders({ url, providerId, config })
 
   const maxAge = 30 * 24 * 60 * 60 // Sessions expire after 30 days of being idle by default
 
@@ -102,7 +97,7 @@ export async function init({
       buttonText: "",
     },
     // Custom options override defaults
-    ...authOptions,
+    ...config,
     // These computed settings can have values in userOptions but we override them
     // and are request-specific.
     url,
@@ -111,38 +106,38 @@ export async function init({
     provider,
     cookies: merge(
       cookie.defaultCookies(
-        authOptions.useSecureCookies ?? url.protocol === "https:"
+        config.useSecureCookies ?? url.protocol === "https:"
       ),
-      authOptions.cookies
+      config.cookies
     ),
     providers,
     // Session options
     session: {
       // If no adapter specified, force use of JSON Web Tokens (stateless)
-      strategy: authOptions.adapter ? "database" : "jwt",
+      strategy: config.adapter ? "database" : "jwt",
       maxAge,
       updateAge: 24 * 60 * 60,
       generateSessionToken: () => crypto.randomUUID(),
-      ...authOptions.session,
+      ...config.session,
     },
     // JWT options
     jwt: {
-      secret: authOptions.secret!, // Asserted in assert.ts
-      maxAge: authOptions.session?.maxAge ?? maxAge, // default to same as `session.maxAge`
+      secret: config.secret!, // Asserted in assert.ts
+      maxAge: config.session?.maxAge ?? maxAge, // default to same as `session.maxAge`
       encode: jwt.encode,
       decode: jwt.decode,
-      ...authOptions.jwt,
+      ...config.jwt,
     },
     // Event messages
-    events: eventsErrorHandler(authOptions.events ?? {}, logger),
-    adapter: adapterErrorHandler(authOptions.adapter, logger),
+    events: eventsErrorHandler(config.events ?? {}, logger),
+    adapter: adapterErrorHandler(config.adapter, logger),
     // Callback functions
-    callbacks: { ...defaultCallbacks, ...authOptions.callbacks },
+    callbacks: { ...defaultCallbacks, ...config.callbacks },
     logger,
     callbackUrl: url.origin,
     isOnRedirectProxy,
     experimental: {
-      ...authOptions.experimental,
+      ...config.experimental,
     },
   }
 

packages/core/src/lib/utils/custom-fetch.ts

@@ -0,0 +1,34 @@
+import * as o from "oauth4webapi"
+import type { InternalProvider } from "../../types.js"
+
+/**
+ * This advanced option allows you to override the default `fetch` function used by the provider
+ * to make requests to the provider's OAuth endpoints.
+ *
+ * It can be used to support corporate proxies, custom fetch libraries, cache discovery endpoints,
+ * add mocks for testing, logging, set custom headers/params for non-spec compliant providers, etc.
+ *
+ * @example
+ * ```ts
+ * import { Auth, customFetch } from "@auth/core"
+ * import GitHub from "@auth/core/providers/github"
+ *
+ * const dispatcher = new ProxyAgent("my.proxy.server")
+ * function proxy(...args: Parameters<typeof fetch>): ReturnType<typeof fetch> {
+ *   return undici(args[0], { ...(args[1] ?? {}), dispatcher })
+ * }
+ *
+ * const response = await Auth(request, {
+ *   providers: [GitHub({ [customFetch]: proxy })]
+ * })
+ * ```
+ *
+ * @see https://undici.nodejs.org/#/docs/api/ProxyAgent?id=example-basic-proxy-request-with-local-agent-dispatcher
+ * @see https://authjs.dev/guides/corporate-proxy
+ */
+export const customFetch = Symbol("custom-fetch")
+
+/** @internal */
+export function fetchOpt(provider: InternalProvider<"oauth" | "oidc">) {
+  return { [o.customFetch]: provider[customFetch] ?? fetch }
+}

packages/core/src/lib/utils/providers.ts

@@ -7,28 +7,27 @@ import type {
   OAuthEndpointType,
   OAuthUserConfig,
   ProfileCallback,
-  Provider,
 } from "../../providers/index.js"
 import type { InternalProvider, Profile } from "../../types.js"
-import type { AuthConfig } from "../../index.js"
+import { type AuthConfig } from "../../index.js"
+import { customFetch } from "../utils/custom-fetch.js"
 
 /**
  * Adds `signinUrl` and `callbackUrl` to each provider
  * and deep merge user-defined options.
  */
 export default function parseProviders(params: {
-  providers: Provider[]
   url: URL
   providerId?: string
-  options: AuthConfig
+  config: AuthConfig
 }): {
   providers: InternalProvider[]
   provider?: InternalProvider
 } {
-  const { providerId, options } = params
-  const url = new URL(options.basePath ?? "/auth", params.url.origin)
+  const { providerId, config } = params
+  const url = new URL(config.basePath ?? "/auth", params.url.origin)
 
-  const providers = params.providers.map((p) => {
+  const providers = config.providers.map((p) => {
     const provider = typeof p === "function" ? p() : p
     const { options: userOptions, ...defaults } = provider
 
@@ -40,8 +39,14 @@ export default function parseProviders(params: {
     })
 
     if (provider.type === "oauth" || provider.type === "oidc") {
-      merged.redirectProxyUrl ??= options.redirectProxyUrl
-      return normalizeOAuth(merged) as InternalProvider
+      merged.redirectProxyUrl ??= config.redirectProxyUrl
+      const normalized = normalizeOAuth(merged) as InternalProvider<
+        "oauth" | "oidc"
+      >
+      // @ts-expect-error Symbols don't get merged by the `merge` function
+      // so we need to do it manually.
+      normalized[customFetch] ??= userOptions?.[customFetch]
+      return normalized
     }
 
     return merged as InternalProvider

packages/core/src/providers/oauth.ts

@@ -2,6 +2,7 @@ import type { Client, PrivateKey } from "oauth4webapi"
 import type { CommonProviderOptions } from "../providers/index.js"
 import type { Awaitable, Profile, TokenSet, User } from "../types.js"
 import type { AuthConfig } from "../index.js"
+import type { customFetch } from "../lib/utils/custom-fetch.js"
 
 // TODO: fix types
 type AuthorizationParameters = any
@@ -221,6 +222,8 @@ export interface OAuth2Config<Profile>
    */
   allowDangerousEmailAccountLinking?: boolean
   redirectProxyUrl?: AuthConfig["redirectProxyUrl"]
+  /** @see {customFetch} */
+  [customFetch]?: typeof fetch
   /**
    * The options provided by the user.
    * We will perform a deep-merge of these values

packages/core/test/actions/callback.test.ts

@@ -1,6 +1,4 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
-import * as jose from "jose"
-import * as o from "oauth4webapi"
 
 import GitHub from "../../src/providers/github.js"
 import Credentials from "../../src/providers/credentials.js"