Auth0 Next.js SDK: Auth0 Next.js Authentication Guide

What is the Auth0 Next.js SDK?

Auth0 Next.js SDK is a TypeScript library that adds Auth0-based user authentication to a Next.js app, published as @auth0/nextjs-auth0 on npm. It ships an Auth0Client for the server plus a middleware (or proxy) handler that intercepts requests at the network boundary to manage login, callback, and logout. The SDK supports both the Next.js 15 middleware model and the newer proxy.ts convention in Next.js 16.

Configurable Authentication Options

• ✓A `domain` option that accepts a plain string or a `DomainResolver` function, letting you serve multiple Auth0 custom domains from one deployment.
• ✓A `logoutStrategy` setting (`auto`, `oidc`, or `v2`) that controls whether logout calls the OIDC end-session endpoint or Auth0's `/v2/logout` endpoint, the latter needed for wildcard URLs.
• ✓Rolling session control through the `session` option, including a `beforeSessionRolled` predicate to decide per request whether to extend the session.
• ✓`enableParallelTransactions` is on by default; each simultaneous login attempt gets a transaction cookie tagged with a unique state value instead of every attempt sharing one cookie that can collide.
• ✓A `sessionStore` interface for plugging in your own database-backed session persistence instead of the default encrypted cookie.
• ✓`beforeSessionSaved` and `onCallback` hooks to modify the session before it's persisted or to handle callback errors and redirects yourself.
• ✓`pushedAuthorizationRequests` turns on the PAR protocol when talking to the authorization server, and `clientAssertionSigningKey`/`clientAssertionSigningAlg` support `private_key_jwt` client authentication.

Installing the Auth0 Next.js SDK

Install the package with `npm i @auth0/nextjs-auth0`. The README states it requires Node.js 20 LTS or newer LTS releases; there's no support statement for anything older. After installing, add four environment variables to `.env.local`: `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, and `AUTH0_SECRET`, plus an optional `APP_BASE_URL` for environments with a stable domain. The domain, client ID, and secret come from an Auth0 Dashboard application that must be created as a 'Regular Web Application' — other application types aren't documented as compatible. Generate `AUTH0_SECRET` — used to encrypt session and transaction cookies — by running `openssl rand -hex 32`.

Getting Started with Next.js Authentication

Create `lib/auth0.ts` and instantiate `new Auth0Client()`; it picks up the four environment variables automatically and applies what the README calls safe cookie defaults. Next you wire up the network boundary: on Next.js 15 that's a `middleware.ts` file at the project root (inside `src/` if you use that layout) calling `auth0.middleware(request)`, with a matcher that excludes `_next/static`, `_next/image`, and a few metadata files. On Next.js 16, `proxy.ts` replaces `middleware.ts` as the recommended file, and its `proxy` function takes the standard `Request` type instead of `NextRequest`. The README notes that `middleware.ts` still runs under the Edge runtime on Next.js 16 for backward compatibility, but it's deprecated on the Node runtime and will eventually be removed. Once the boundary is in place, send users to `/auth/login` to start the flow, and call `auth0.getSession()` in a server component to read the logged-in user — the README is explicit that you should use plain anchor links rather than Next.js's `<Link>` component for auth routes so navigation isn't handled client-side. Skip setting `APP_BASE_URL` and the SDK infers the base URL from the incoming request instead, which is what keeps Vercel and Netlify preview URLs working without per-deploy config; in production, though, this forces secure cookies and throws an `InvalidConfigurationError` if you try to disable that.

Alternative Next.js Authentication Solutions

Common Questions About Auth0 Next.js SDK

The problem it solves

Wiring OAuth into a Next.js App Router app means hand-coding a login redirect, a callback handler that exchanges a code for tokens, encrypted session cookies, and logout — all while Next.js's own routing conventions keep shifting (App Router, then middleware.ts, now proxy.ts in Next.js 16). Auth0 Next.js SDK's setup docs exist because that plumbing has to sit at the network boundary correctly or the whole flow breaks, and it has to be redone whenever Next.js changes how that boundary works. The SDK packages the Auth0Client plus a middleware/proxy handler so that boundary code, cookie encryption, and the Next.js 15-to-16 migration path are Auth0's problem to keep current, not yours.

Best use cases

• •Adding login to a Next.js App Router site that already uses Auth0 (or is moving to Auth0) as its identity provider, rather than rolling a custom OAuth flow.
• •Server components that need to read the logged-in user directly via `auth0.getSession()` without a separate client-side auth check.
• •Preview-deployment workflows on Vercel or Netlify, where the base URL changes per branch and you don't want to hardcode `APP_BASE_URL` for each one.
• •Multi-tenant setups that need several Auth0 custom domains, using the `DomainResolver` function instead of a single static domain string.
• •Teams migrating a Next.js 15 app with an existing `middleware.ts` auth setup toward Next.js 16 and its `proxy.ts` convention.

Who should try it — and who should skip

Try Auth0 Next.js SDK if your team is already on Auth0, or is choosing a hosted identity provider anyway, and you want the App Router middleware/proxy wiring, session cookie encryption, and the Next.js 16 migration path handled instead of built from primitives. Skip it if you don't want to depend on an external identity provider at all — Auth.js or a self-hosted option like authentik removes that account dependency — or if your app isn't on Next.js, since this SDK is specific to that framework's middleware and proxy conventions.

Related repositories