@auth0/nextjs-auth0

Getting Started

1. Install the SDK

1npm i @auth0/nextjs-auth0@beta

2. Add the environment variables

Add the following environment variables to your .env.local file:

AUTH0_DOMAIN=
AUTH0_CLIENT_ID=
AUTH0_CLIENT_SECRET=
AUTH0_SECRET=
APP_BASE_URL=

The AUTH0_DOMAIN, AUTH0_CLIENT_ID, and AUTH0_CLIENT_SECRET can be obtained from the Auth0 Dashboard once you've created an application. This application must be a Regular Web Application.

The AUTH0_SECRET is the key used to encrypt the session and transaction cookies. You can generate a secret using openssl:

1openssl rand -hex 32

The APP_BASE_URL is the URL that your application is running on. When developing locally, this is most commonly http://localhost:3000.

[!IMPORTANT]
You will need to register the follwing URLs in your Auth0 Application via the Auth0 Dashboard:

• Add http://localhost:3000/auth/callback to the list of Allowed Callback URLs
• Add http://localhost:3000 to the list of Allowed Logout URLs

3. Create the Auth0 SDK client

Create an instance of the Auth0 client. This instance will be imported and used in anywhere we need access to the authentication methods on the server.

Add the following contents to a file named lib/auth0.ts:

1import { Auth0Client } from "@auth0/nextjs-auth0/server"
2
3export const auth0 = new Auth0Client()

4. Add the authentication middleware

Create a middleware.ts file in the root of your project's directory:

1import type { NextRequest } from "next/server"
2
3import { auth0 } from "./lib/auth0"
4
5export async function middleware(request: NextRequest) {
6  return await auth0.middleware(request)
7}
8
9export const config = {
10  matcher: [
11    /*
12     * Match all request paths except for the ones starting with:
13     * - _next/static (static files)
14     * - _next/image (image optimization files)
15     * - favicon.ico, sitemap.xml, robots.txt (metadata files)
16     */
17    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
18  ],
19}

[!NOTE]
If you're using a src/ directory, the middleware.ts file must be created inside the src/ directory.

You can now begin to authenticate your users by redirecting them to your application's /auth/login route:

1import { auth0 } from "@/lib/auth0"
2
3export default async function Home() {
4  const session = await auth0.getSession()
5
6  if (!session) {
7    return (
8      <main>
9        <a href="/auth/login?screen_hint=signup">Sign up</a>
10        <a href="/auth/login">Log in</a>
11      </main>
12    )
13  }
14
15  return (
16    <main>
17      <h1>Welcome, {session.user.name}!</h1>
18    </main>
19  )
20}

[!IMPORTANT]
You must use <a> tags instead of the <Link> component to ensure that the routing is not done client-side as that may result in some unexpected behavior.

Customizing the client

You can customize the client by using the options below:

Option	Type	Description
domain	string	The Auth0 domain for the tenant (e.g.: example.us.auth0.com or https://example.us.auth0.com). If it's not specified, it will be loaded from the AUTH0_DOMAIN environment variable.
clientId	string	The Auth0 client ID. If it's not specified, it will be loaded from the AUTH0_CLIENT_ID environment variable.
clientSecret	string	The Auth0 client secret. If it's not specified, it will be loaded from the AUTH0_CLIENT_SECRET environment variable.
authorizationParameters	AuthorizationParameters	The authorization parameters to pass to the /authorize endpoint. See Passing authorization parameters for more details.
clientAssertionSigningKey	string or CryptoKey	Private key for use with private_key_jwt clients. This can also be specified via the AUTH0_CLIENT_ASSERTION_SIGNING_KEY environment variable.
clientAssertionSigningAlg	string	The algorithm used to sign the client assertion JWT. This can also be provided via the AUTH0_CLIENT_ASSERTION_SIGNING_ALG environment variable.
appBaseUrl	string	The URL of your application (e.g.: http://localhost:3000). If it's not specified, it will be loaded from the APP_BASE_URL environment variable.
secret	string	A 32-byte, hex-encoded secret used for encrypting cookies. If it's not specified, it will be loaded from the AUTH0_SECRET environment variable.
signInReturnToPath	string	The path to redirect the user to after successfully authenticating. Defaults to /.
session	SessionConfiguration	Configure the session timeouts and whether to use rolling sessions or not. See Session configuration for additional details.
beforeSessionSaved	BeforeSessionSavedHook	A method to manipulate the session before persisting it. See beforeSessionSaved for additional details.
onCallback	OnCallbackHook	A method to handle errors or manage redirects after attempting to authenticate. See onCallback for additional details.
sessionStore	SessionStore	A custom session store implementation used to persist sessions to a data store. See Database sessions for additional details.
pushedAuthorizationRequests	boolean	Configure the SDK to use the Pushed Authorization Requests (PAR) protocol when communicating with the authorization server.
routes	Routes	Configure the paths for the authentication routes. See Custom routes for additional details.
allowInsecureRequests	boolean	Allow insecure requests to be made to the authorization server. This can be useful when testing with a mock OIDC provider that does not support TLS, locally. This option can only be used when NODE_ENV is not set to production.

Passing authorization parameters

There are 2 ways to customize the authorization parameters that will be passed to the /authorize endpoint. The first option is through static configuration when instantiating the client, like so:

1export const auth0 = new Auth0Client({
2  authorizationParameters: {
3    scope: "openid profile email",
4    audience: "urn:custom:api",
5  },
6})

The second option is through the query parameters to the /auth/login endpoint which allows you to specify the authorization parameters dynamically. For example, to specify an audience, the login URL would look like so:

1<a href="/auth/login?audience=urn:my-api">Login</a>

The returnTo parameter

Redirecting the user after authentication

The returnTo parameter can be appended to the login to specify where you would like to redirect the user after they have completed their authentication and have returned to your application.

For example: /auth/login?returnTo=/dashboard would redirect the user to the /dashboard route after they have authenticated.

Redirecting the user after logging out

The returnTo parameter can be appended to the logout to specify where you would like to redirect the user after they have logged out.

For example: /auth/login?returnTo=https://example.com/some-page would redirect the user to the https://example.com/some-page URL after they have logged out.

[!NOTE]
The URLs specified as returnTo parameters must be registered in your client's Allowed Logout URLs.

Accessing the authenticated user

In the browser

To access the currently authenticated user on the client, you can use the useUser() hook, like so:

1"use client"
2
3import { useUser } from "@auth0/nextjs-auth0"
4
5export default function Profile() {
6  const { user, isLoading, error } = useUser()
7
8  if (isLoading) return <div>Loading...</div>
9
10  return (
11    <main>
12      <h1>Profile</h1>
13      <div>
14        <pre>{JSON.stringify(user, null, 2)}</pre>
15      </div>
16    </main>
17  )
18}

On the server (App Router)

On the server, the getSession() helper can be used in Server Components, Server Routes, and Server Actions to get the session of the currently authenticated user and to protect resources, like so:

1import { auth0 } from "@/lib/auth0"
2
3export default async function Home() {
4  const session = await auth0.getSession()
5
6  if (!session) {
7    return <div>Not authenticated</div>
8  }
9
10  return (
11    <main>
12      <h1>Welcome, {session.user.name}!</h1>
13    </main>
14  )
15}

On the server (Pages Router)

On the server, the getSession(req) helper can be used in getServerSideProps and API routes to get the session of the currently authenticated user and to protect resources, like so:

1import type { GetServerSideProps, InferGetServerSidePropsType } from "next"
2
3import { auth0 } from "@/lib/auth0"
4
5export const getServerSideProps = (async (ctx) => {
6  const session = await auth0.getSession(ctx.req)
7
8  if (!session) return { props: { user: null } }
9
10  return { props: { user: session.user ?? null } }
11}) satisfies GetServerSideProps<{ user: any | null }>
12
13export default function Page({
14  user,
15}: InferGetServerSidePropsType<typeof getServerSideProps>) {
16  if (!user) {
17    return (
18      <main>
19        <p>Not authenticated!</p>
20      </main>
21    )
22  }
23
24  return (
25    <main>
26      <p>Welcome, {user.name}!</p>
27    </main>
28  )
29}

Middleware

In middleware, the getSession(req) helper can be used to get the session of the currently authenticated user and to protect resources, like so:

1import { NextRequest, NextResponse } from "next/server"
2
3import { auth0 } from "@/lib/auth0"
4
5export async function middleware(request: NextRequest) {
6  const authRes = await auth0.middleware(request)
7
8  if (request.nextUrl.pathname.startsWith("/auth")) {
9    return authRes
10  }
11
12  const session = await auth0.getSession(request)
13
14  if (!session) {
15    // user is not authenticated, redirect to login page
16    return NextResponse.redirect(new URL("/auth/login", request.nextUrl.origin))
17  }
18
19  // the headers from the auth middleware should always be returned
20  return authRes
21}

[!IMPORTANT]
The request object must be passed as a parameter to the getSession(request) method when called from a middleware to ensure that any updates to the session can be read within the same request.

Updating the session

The updateSession method could be used to update the session of the currently authenticated user in the App Router, Pages Router, and middleware. If the user does not have a session, an error will be thrown.

[!NOTE] Any updates to the session will be overwritten when the user re-authenticates and obtains a new session.

On the server (App Router)

On the server, the updateSession() helper can be used in Server Routes and Server Actions to update the session of the currently authenticated user, like so:

1import { NextResponse } from "next/server"
2
3import { auth0 } from "@/lib/auth0"
4
5export async function GET() {
6  const session = await auth0.getSession()
7
8  if (!session) {
9    return NextResponse.json({ error: "Unauthorized" }, { status: 401 })
10  }
11
12  await auth0.updateSession({
13    ...session,
14    updatedAt: Date.now(),
15  })
16
17  return NextResponse.json(null, { status: 200 })
18}

[!NOTE] The updateSession() method is not usable in Server Components as it is not possible to write cookies.

On the server (Pages Router)

On the server, the updateSession(req, res, session) helper can be used in getServerSideProps and API routes to update the session of the currently authenticated user, like so:

1import type { NextApiRequest, NextApiResponse } from "next"
2
3import { auth0 } from "@/lib/auth0"
4
5type ResponseData =
6  | {}
7  | {
8      error: string
9    }
10
11export default async function handler(
12  req: NextApiRequest,
13  res: NextApiResponse<ResponseData>
14) {
15  const session = await auth0.getSession(req)
16
17  if (!session) {
18    return res.status(401).json({ error: "Unauthorized" })
19  }
20
21  await auth0.updateSession(req, res, {
22    ...session,
23    updatedAt: Date.now(),
24  })
25
26  res.status(200).json({})
27}

Middleware

In middleware, the updateSession(req, res, session) helper can be used to update the session of the currently authenticated user, like so:

1import { NextRequest, NextResponse } from "next/server"
2
3import { auth0 } from "@/lib/auth0"
4
5export async function middleware(request: NextRequest) {
6  const authRes = await auth0.middleware(request)
7
8  if (request.nextUrl.pathname.startsWith("/auth")) {
9    return authRes
10  }
11
12  const session = await auth0.getSession(request)
13
14  if (!session) {
15    // user is not authenticated, redirect to login page
16    return NextResponse.redirect(new URL("/auth/login", request.nextUrl.origin))
17  }
18
19  await auth0.updateSession(request, authRes, {
20    ...session,
21    user: {
22      ...session.user,
23      // add custom user data
24      updatedAt: Date.now(),
25    },
26  })
27
28  // the headers from the auth middleware should always be returned
29  return authRes
30}

[!IMPORTANT]
The request and response objects must be passed as a parameters to the updateSession(request, response, session) method when called from a middleware to ensure that any updates to the session can be read within the same request.

If you are using the Pages Router and need to read updates to the session made in the middleware within the same request, you will need to ensure that any updates to the session are propagated on the request object, like so:

1import { NextRequest, NextResponse } from "next/server"
2
3import { auth0 } from "@/lib/auth0"
4
5export async function middleware(request: NextRequest) {
6  const authRes = await auth0.middleware(request)
7
8  if (request.nextUrl.pathname.startsWith("/auth")) {
9    return authRes
10  }
11
12  const session = await auth0.getSession(request)
13
14  if (!session) {
15    // user is not authenticated, redirect to login page
16    return NextResponse.redirect(new URL("/auth/login", request.nextUrl.origin))
17  }
18
19  await auth0.updateSession(request, authRes, {
20    ...session,
21    user: {
22      ...session.user,
23      // add custom user data
24      updatedAt: Date.now(),
25    },
26  })
27
28  // create a new response with the updated request headers
29  const resWithCombinedHeaders = NextResponse.next({
30    request: {
31      headers: request.headers,
32    },
33  })
34
35  // set the response headers (set-cookie) from the auth response
36  authRes.headers.forEach((value, key) => {
37    resWithCombinedHeaders.headers.set(key, value)
38  })
39
40  // the headers from the auth middleware should always be returned
41  return resWithCombinedHeaders
42}

Getting an access token

The getAccessToken() helper can be used both in the browser and on the server to obtain the access token to call external APIs. If the access token has expired and a refresh token is available, it will automatically be refreshed and persisted.

In the browser

To obtain an access token to call an external API on the client, you can use the getAccessToken() helper, like so:

1"use client"
2
3import { getAccessToken } from "@auth0/nextjs-auth0"
4
5export default function Component() {
6  async function fetchData() {
7    try {
8      const token = await getAccessToken()
9      // call external API with token...
10    } catch (err) {
11      // err will be an instance of AccessTokenError if an access token could not be obtained
12    }
13  }
14
15  return (
16    <main>
17      <button onClick={fetchData}>Fetch Data</button>
18    </main>
19  )
20}

On the server (App Router)

On the server, the getAccessToken() helper can be used in Server Routes, Server Actions and Server Components to get an access token to call external APIs.

[!IMPORTANT]
Server Components cannot set cookies. Calling getAccessToken() in a Server Component will cause the access token to be refreshed, if it is expired, and the updated token set will not to be persisted.

It is recommended to call getAccessToken(req, res) in the middleware if you need to use the refresh token in a Server Component as this will ensure the token is refreshed and correctly persisted.

For example:

1import { NextResponse } from "next/server"
2
3import { auth0 } from "@/lib/auth0"
4
5export async function GET() {
6  try {
7    const token = await auth0.getAccessToken()
8    // call external API with token...
9  } catch (err) {
10    // err will be an instance of AccessTokenError if an access token could not be obtained
11  }
12
13  return NextResponse.json({
14    message: "Success!",
15  })
16}

On the server (Pages Router)

On the server, the getAccessToken(req, res) helper can be used in getServerSideProps and API routes to get an access token to call external APIs, like so:

1import type { NextApiRequest, NextApiResponse } from "next"
2
3import { auth0 } from "@/lib/auth0"
4
5export default async function handler(
6  req: NextApiRequest,
7  res: NextApiResponse<{ message: string }>
8) {
9  try {
10    const token = await auth0.getAccessToken(req, res)
11    // call external API with token...
12  } catch (err) {
13    // err will be an instance of AccessTokenError if an access token could not be obtained
14  }
15
16  res.status(200).json({ message: "Success!" })
17}

Middleware

In middleware, the getAccessToken(req, res) helper can be used to get an access token to call external APIs, like so:

1import { NextRequest, NextResponse } from "next/server"
2
3import { auth0 } from "@/lib/auth0"
4
5export async function middleware(request: NextRequest) {
6  const authRes = await auth0.middleware(request)
7
8  if (request.nextUrl.pathname.startsWith("/auth")) {
9    return authRes
10  }
11
12  const session = await auth0.getSession(request)
13
14  if (!session) {
15    // user is not authenticated, redirect to login page
16    return NextResponse.redirect(new URL("/auth/login", request.nextUrl.origin))
17  }
18
19  const accessToken = await auth0.getAccessToken(request, authRes)
20
21  // the headers from the auth middleware should always be returned
22  return authRes
23}

[!IMPORTANT]
The request and response objects must be passed as a parameters to the getAccessToken(request, response) method when called from a middleware to ensure that the refreshed access token can be accessed within the same request.

If you are using the Pages Router and are calling the getAccessToken method in both the middleware and an API Route or getServerSideProps, it's recommended to propagate the headers from the middleware, as shown below. This will ensure that calling getAccessToken in the API Route or getServerSideProps will not result in the access token being refreshed again.

1import { NextRequest, NextResponse } from "next/server"
2
3import { auth0 } from "@/lib/auth0"
4
5export async function middleware(request: NextRequest) {
6  const authRes = await auth0.middleware(request)
7
8  if (request.nextUrl.pathname.startsWith("/auth")) {
9    return authRes
10  }
11
12  const session = await auth0.getSession(request)
13
14  if (!session) {
15    // user is not authenticated, redirect to login page
16    return NextResponse.redirect(new URL("/auth/login", request.nextUrl.origin))
17  }
18
19  const accessToken = await auth0.getAccessToken(request, authRes)
20
21  // create a new response with the updated request headers
22  const resWithCombinedHeaders = NextResponse.next({
23    request: {
24      headers: request.headers,
25    },
26  })
27
28  // set the response headers (set-cookie) from the auth response
29  authRes.headers.forEach((value, key) => {
30    resWithCombinedHeaders.headers.set(key, value)
31  })
32
33  // the headers from the auth middleware should always be returned
34  return resWithCombinedHeaders
35}

<Auth0Provider />

Passing an initial user from the server

You can wrap your components in an <Auth0Provider /> and pass an initial user object to make it available to your components using the useUser() hook. For example:

1import { Auth0Provider } from "@auth0/nextjs-auth0"
2
3import { auth0 } from "@/lib/auth0"
4
5export default async function RootLayout({
6  children,
7}: Readonly<{
8  children: React.ReactNode
9}>) {
10  const session = await auth0.getSession()
11
12  return (
13    <html lang="en">
14      <body>
15        <Auth0Provider user={session?.user}>{children}</Auth0Provider>
16      </body>
17    </html>
18  )
19}

The loaded user will then be used as a fallback in useUser() hook.

Hooks

The SDK exposes hooks to enable you to provide custom logic that would be run at certain lifecycle events.

beforeSessionSaved

The beforeSessionSaved hook is run right before the session is persisted. It provides a mechanism to modify the session claims before persisting them.

The hook recieves a SessionData object and an ID token. The function must return a Promise that resolves to a SessionData object: (session: SessionData) => Promise<SessionData>. For example:

1export const auth0 = new Auth0Client({
2  async beforeSessionSaved(session, idToken) {
3    return {
4      ...session,
5      user: {
6        ...session.user,
7        foo: "bar",
8      },
9    }
10  },
11})

onCallback

The onCallback hook is run once the user has been redirected back from Auth0 to your application with either an error or the authorization code which will be verified and exchanged.

The onCallback hook receives 3 parameters:

1. error: the error returned from Auth0 or when attempting to complete the transaction. This will be null if the transaction was completed successfully.
2. context: provides context on the transaction that initiated the transaction.
3. session: the SessionData that will be persisted once the transaction completes successfully. This will be null if there was an error.

The hook must return a Promise that resolves to a NextResponse.

For example, a custom onCallback hook may be specified like so:

1export const auth0 = new Auth0Client({
2  async onCallback(error, context, session) {
3    // redirect the user to a custom error page
4    if (error) {
5      return NextResponse.redirect(
6        new URL(`/error?error=${error.message}`, process.env.APP_BASE_URL)
7      )
8    }
9
10    // complete the redirect to the provided returnTo URL
11    return NextResponse.redirect(
12      new URL(context.returnTo || "/", process.env.APP_BASE_URL)
13    )
14  },
15})

Session configuration

The session configuration can be managed by specifying a session object when configuring the Auth0 client, like so:

1export const auth0 = new Auth0Client({
2  session: {
3    rolling: true,
4    absoluteDuration: 60 * 60 * 24 * 30, // 30 days in seconds
5    inactivityDuration: 60 * 60 * 24 * 7, // 7 days in seconds
6  },
7})

Option	Type	Description
rolling	boolean	When enabled, the session will continue to be extended as long as it is used within the inactivity duration. Once the upper bound, set via the absoluteDuration, has been reached, the session will no longer be extended. Default: true.
absoluteDuration	number	The absolute duration after which the session will expire. The value must be specified in seconds. Default: 30 days.
inactivityDuration	number	The duration of inactivity after which the session will expire. The value must be specified in seconds. Default: 7 days.

Database sessions

By default, the user's sessions are stored in encrypted cookies. You may choose to persist the sessions in your data store of choice.

To do this, you can provide a SessionStore implementation as an option when configuring the Auth0 client, like so:

1export const auth0 = new Auth0Client({
2  sessionStore: {
3    async get(id) {
4      // query and return a session by its ID
5    },
6    async set(id, sessionData) {
7      // upsert the session given its ID and sessionData
8    },
9    async delete(id) {
10      // delete the session using its ID
11    },
12    async deleteByLogoutToken({ sid, sub }: { sid: string; sub: string }) {
13      // optional method to be implemented when using Back-Channel Logout
14    },
15  },
16})

Back-Channel Logout

The SDK can be configured to listen to Back-Channel Logout events. By default, a route will be mounted /auth/backchannel-logout which will verify the logout token and call the deleteByLogoutToken method of your session store implementation to allow you to remove the session.

To use Back-Channel Logout, you will need to provide a session store implementation as shown in the Database sessions section above with the deleteByLogoutToken implemented.

A LogoutToken object will be passed as the parameter to deleteByLogoutToken which will contain either a sid claim, a sub claim, or both.

Combining middleware

By default, the middleware does not protect any pages. It is used to mount the authentication routes and provide the necessary functionality for rolling sessions.

You can combine multiple middleware, like so:

1export async function middleware(request: NextRequest) {
2  const authResponse = await auth0.middleware(request)
3
4  // if path starts with /auth, let the auth middleware handle it
5  if (request.nextUrl.pathname.startsWith("/auth")) {
6    return authResponse
7  }
8
9  // call any other middleware here
10  const someOtherResponse = await someOtherMiddleware(request)
11
12  // add any headers from the auth middleware to the response
13  for (const [key, value] of authResponse.headers) {
14    someOtherResponse.headers.set(key, value)
15  }
16
17  return someOtherResponse
18}

For a complete example using next-intl middleware, please see the examples/ directory of this repository.

ID Token claims and the user object

By default, the following properties claims from the ID token are added to the user object in the session automatically:

• sub
• name
• nickname
• given_name
• family_name
• picture
• email
• email_verified
• org_id

If you'd like to customize the user object to include additional custom claims from the ID token, you can use the beforeSessionSaved hook (see beforeSessionSaved hook)

[!NOTE]
It's best practice to limit what claims are stored on the user object in the session to avoid bloating the session cookie size and going over browser limits.

Routes

The SDK mounts 6 routes:

1. /auth/login: the login route that the user will be redirected to to start a initiate an authentication transaction
2. /auth/logout: the logout route that must be addedto your Auth0 application's Allowed Logout URLs
3. /auth/callback: the callback route that must be addedto your Auth0 application's Allowed Callback URLs
4. /auth/profile: the route to check the user's session and return their attributes
5. /auth/access-token: the route to check the user's session and return an access token (which will be automatically refreshed if a refresh token is available)
6. /auth/backchannel-logout: the route that will receive a logout_token when a configured Back-Channel Logout initiator occurs

Custom routes

The default paths can be set using the routes configuration option. For example, when instantiating the client:

1import { Auth0Client } from "@auth0/nextjs-auth0/server"
2
3export const auth0 = new Auth0Client({
4  routes: {
5    login: "/login",
6    logout: "/logout",
7    callback: "/callback",
8    backChannelLogout: "/backchannel-logout",
9  },
10})

To configure the profile and access token routes, you must use the NEXT_PUBLIC_PROFILE_ROUTE and NEXT_PUBLIC_ACCESS_TOKEN_ROUTE, respectively. For example:

# .env.local
# required environment variables...

NEXT_PUBLIC_PROFILE_ROUTE=/api/me
NEXT_PUBLIC_ACCESS_TOKEN_ROUTE=/api/auth/token

[!IMPORTANT]
Updating the route paths will also require updating the Allowed Callback URLs and Allowed Logout URLs configured in the Auth0 Dashboard for your client.