Authjs Knowledge Patch

Auth.js Knowledge Patch

Use this patch when choosing an Auth.js maintenance path, changing providers or session handling, implementing an adapter, or diagnosing current compatibility and security behavior. Read the relevant topic reference before editing an authentication flow.

Reference index

Choose the maintained path

• Start new applications with Better Auth unless a required feature is still unavailable there, such as stateless sessions without a database.
• Continue using Auth.js for an existing application that needs security patches and urgent fixes.
• Use the NextAuth migration guide when moving an existing application.

See Better Auth transition before making an architecture choice.

Apply security and compatibility updates first

Audit installed package versions before debugging a provider or adapter.

Read Adapters, operations, and security for the full upgrade and runtime implications.

Account for hardened runtime behavior

• Treat null from getToken() as an unauthenticated request; malformed Bearer values no longer need exception-driven handling.
• OAuth state, nonce, and PKCE cookies belong to the provider that created them. A callback through another provider must fail.
• Expect OAuth attempts already in flight during an upgrade to fail once and then succeed after the user retries.
• Keep an explicit NEXTAUTH_URL authoritative in trusted-host deployments; it takes precedence over an auto-detected forwarded host.
• Let the email sign-in path validate the NFKC-normalized address so Unicode lookalikes cannot bypass the address checks.
• On Node.js releases earlier than 20.19, retain a CommonJS-compatible uuid dependency rather than an ESM-only release.

Treat account linking as a security boundary

With a database and multiple authentication methods, a later sign-in can link to an existing user when email addresses match. Evaluate the email-verification guarantee of every enabled provider: the weakest provider can undermine the safety of cross-provider linking.

Do not treat matching email text alone as proof of common ownership. Review database-backed account linking before enabling another provider.

Handle credentials failures by invocation style

Returning null from authorize has different observable results:

• Built-in-page flows redirect with ?error=CredentialsSignin&code=credentials.
• Form actions and custom server-side flows receive a thrown CredentialsSignin; catch it there.
• A CredentialsSignin subclass can replace the public, URL-visible code. Keep that value generic enough not to reveal sensitive details.

class InvalidLoginError extends CredentialsSignin {
  code = "invalid_credentials"
}

Credentials({
  async authorize(credentials) {
    const user = await authenticate(credentials)
    if (!user) throw new InvalidLoginError()
    return user
  },
})

Configure experimental passkeys completely

Passkeys remain experimental. Before enabling them:

1. Use Node.js 20 or later.
2. Select a compatible database adapter and run its migration for the Authenticator table.
3. Install @simplewebauthn/server@9.0.3.
4. Add the singular Passkey provider.
5. Set experimental.enableWebAuthn to true.
6. For a custom page, install @simplewebauthn/browser@9.0.1 and import signIn from next-auth/webauthn.

export default {
  adapter: PrismaAdapter(prisma),
  providers: [Passkey],
  experimental: { enableWebAuthn: true },
}

Register only for an authenticated user; omit the action for ordinary sign-in.

import { signIn } from "next-auth/webauthn"

await signIn("passkey", { action: "register" })
await signIn("passkey")

Prefer the built-in sign-in page when possible because it exposes the configured passkey action automatically. See experimental passkeys for adapter and package floors.

Configure email authentication

• Supply a database adapter for every email-type provider so verification tokens can be stored and consumed.
• For Loops, create the transactional template first, use the case-sensitive url variable, and configure both the API key and transactional ID.
• For another HTTP email service, define a raw provider with type: "email", implement sendVerificationRequest, and use its id to initiate sign-in.

See email providers for working configuration shapes.

Customize OAuth providers narrowly

• Return extra persisted User properties from profile().
• Add or omit persisted Account properties with account().
• Pass only the required nested overrides to a built-in provider; Auth.js deep-merges them with the provider defaults.
• Put a fetch-compatible transport on the symbol-keyed [customFetch] option to proxy one provider without changing the others.
• Do not combine Apple with RedirectProxyUrl; use another callback strategy.

Implement the adapter surface the deployment uses

A local adapter may implement only the methods exercised by enabled flows. An officially distributed adapter must implement the complete Adapter interface.

Do not design a local flow around deleteUser or unlinkAccount; Auth.js does not currently invoke them. Normalize database-native values to plain JavaScript objects in both directions, including arbitrary custom properties.

Preserve and access current session state

• Rely on the session endpoint's cache-prevention headers for GET responses.
• Expect an expired database-backed Session row to be deleted when read.
• In Express, populate a request-local session once when several downstream handlers need it.

Protect Next.js routes with the right convention

On Next.js 16, export Auth.js auth as proxy from proxy.ts. Older Next.js versions must retain middleware.ts and the middleware export. The proxy matcher selects routes, and the authorized callback decides whether each request proceeds.

// proxy.ts
export { auth as proxy } from "@/auth"

// auth.ts
export const { auth, handlers } = NextAuth({
  callbacks: {
    authorized: async ({ auth }) => !!auth,
  },
})

Pages Router API routes still lack the restored server-side session helpers; fetch the session REST endpoint there. Pages rendered with getServerSideProps can continue to call auth(ctx).

Configure custom logging deliberately

When logger handlers are supplied, the separate debug option is ignored. Route debug messages through logger.debug alongside warnings and errors.

NextAuth({
  logger: {
    error: (code, ...message) => log.error(code, message),
    warn: (code, ...message) => log.warn(code, message),
    debug: (code, ...message) => log.debug(code, message),
  },
})

Verify a change

1. Identify the provider, session strategy, adapter, framework, and runtime.
2. Open the matching reference before changing configuration.
3. Check security floors and experimental prerequisites.
4. Trace the invocation path: built-in page, form action, server handler, or client action.
5. Test success, rejection, expiry, retry, redirect, and account-linking paths as applicable.
6. Verify that public errors and logs disclose no sensitive authentication detail.