Corporate proxy support
Route provider requests through an organization’s HTTP proxy.
Auth.js · Function
customFetch
customFetch lets an OAuth provider use a replacement fetch function for direct requests to its OAuth endpoints. It supports integrations such as proxies, custom fetch libraries, logging, mocks, and provider-specific request adjustments.
How it works
customFetch is a symbol-based provider option that replaces the default fetch used for direct OAuth-provider endpoint requests. Assign it a function compatible with fetch; the function receives the request input and optional initialization data and must return a Promise resolving to a Response.
Syntax
const customFetch: typeof customFetch;Parameters
| Name | Type | Description |
|---|---|---|
input | URL | RequestInfo | Request URL or request object passed to fetch. |
init | RequestInit | Optional Fetch API request initialization options. |
Returns
Promise<Response>
Key points
- The option replaces the provider's normal fetch implementation.
- Its scope is direct requests to the provider's OAuth endpoints.
- Supported scenarios include corporate proxies, custom fetch implementations, and caching discovery-endpoint requests.
- It can also provide test mocks, request logging, or compatibility parameters for non-spec-compliant providers.
Common mistakes
- Treat the replacement fetch as security-sensitive: incorrect configuration can introduce security problems.
- The documented Undici proxy approach may not work in Edge runtimes or environments with proxy restrictions.
Example: Route GitHub requests through a proxy
import { Auth, customFetch } from "@auth/core"
import GitHub from "@auth/core/providers/github"
import { ProxyAgent, fetch as undici } from "undici"
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 })]
})Overrides the provider's OAuth HTTP requests with a fetch implementation that routes through an Undici proxy agent.
When to use it
Custom transport
Use a compatible fetch implementation to alter transport behavior.
Testing mocks
Replace network calls with controlled responses during automated tests.
Logging and compatibility adjustments
Add diagnostics or provider-specific request metadata.
Interview questions
QWhat does customFetch change?
customFetch is an exported symbol used as a computed provider option. Setting it to a fetch-compatible function makes that provider use the replacement for requests to its OAuth endpoints.
Follow-up: How would you apply it to only one provider? Pass the computed property on that provider's configuration, for example GitHub({ [customFetch]: proxy }).
QWhat is the expected function shape?
The function accepts the same input and optional initialization arguments as fetch and returns Promise<Response>. This lets the implementation add transport behavior while preserving the expected Web Fetch contract.
Follow-up: What types should a proxy wrapper preserve? Use Parameters<typeof fetch> for its arguments and ReturnType<typeof fetch> for its result, as in the documented example.
QWhen is overriding fetch useful?
Typical uses include corporate proxies, alternate fetch libraries, endpoint-cache discovery, test mocks, logging, and adding headers or parameters for providers that do not follow the specification. The override targets direct OAuth endpoint calls.
Follow-up: What should be checked before deploying a custom transport? Verify its security behavior and runtime compatibility, especially when using proxy-specific libraries.
Related
AuthGitHubfetchProxyAgent