Next.js

Run the following command within your project directory to install the Auth0 Next.js SDK:

npm install @auth0/nextjs-auth0

The SDK exposes methods and variables that help you integrate Auth0 with your Next.js application using Route Handlers on the backend and React Context with React Hooks on the frontend.

In the root directory of your project, create the file .env.local with the following environment variables:

AUTH0_SECRET='use [openssl rand -hex 32] to generate a 32 bytes value'
APP_BASE_URL='http://localhost:3000'
AUTH0_DOMAIN='https://{yourDomain}'
AUTH0_CLIENT_ID='{yourClientId}'
AUTH0_CLIENT_SECRET='{yourClientSecret}'
'If your application is API authorized add the variables AUTH0_AUDIENCE and AUTH0_SCOPE'
AUTH0_AUDIENCE='your_auth_api_identifier'
AUTH0_SCOPE='openid profile email read:shows'

• AUTH0_SECRET: A long secret value used to encrypt the session cookie. You can generate a suitable string using openssl rand -hex 32 on the command line.
• APP_BASE_URL: The base URL of your application
• AUTH0_DOMAIN: The URL of your Auth0 tenant domain
• AUTH0_CLIENT_ID: Your Auth0 application's Client ID
• AUTH0_CLIENT_SECRET: Your Auth0 application's Client Secret

The SDK will read these values from the Node.js process environment and configure itself automatically.

Create a file at lib/auth0.js to add an instance of the Auth0 client. This instance provides methods for handling authentication, sesssions and user data.

// lib/auth0.js

import { Auth0Client } from "@auth0/nextjs-auth0/server";

// Initialize the Auth0 client 
export const auth0 = new Auth0Client({
  // Options are loaded from environment variables by default
  // Ensure necessary environment variables are properly set
  // domain: process.env.AUTH0_DOMAIN,
  // clientId: process.env.AUTH0_CLIENT_ID,
  // clientSecret: process.env.AUTH0_CLIENT_SECRET,
  // appBaseUrl: process.env.APP_BASE_URL,
  // secret: process.env.AUTH0_SECRET,

  authorizationParameters: {
    // In v4, the AUTH0_SCOPE and AUTH0_AUDIENCE environment variables for API authorized applications are no longer automatically picked up by the SDK.
    // Instead, we need to provide the values explicitly.
    scope: process.env.AUTH0_SCOPE,
    audience: process.env.AUTH0_AUDIENCE,
  }
});

The Next.js Middleware allows you to run code before a request is completed. Create a middleware.ts file. This file is used to enforce authentication on specific routes.

import type { NextRequest } from "next/server";
import { auth0 } from "./lib/auth0";

export async function middleware(request: NextRequest) {
  return await auth0.middleware(request);
}

export const config = {
  matcher: [
    /*
     * Match all request paths except for the ones starting with:
     * - _next/static (static files)
     * - _next/image (image optimization files)
     * - favicon.ico, sitemap.xml, robots.txt (metadata files)
     */
    "/((?!_next/static|_next/image|favicon.ico|sitemap.xml|robots.txt).*)",
  ],
};

The middleware function intercepts incoming requests and applies Auth0's authentication logic. The matcher configuration ensures that the middleware runs on all routes except for static files and metadata.

Using the SDK's middleware auto-configures the following routes:

• /auth/login: The route to perform login with Auth0
• /auth/logout: The route to log the user out
• /auth/callback: The route Auth0 will redirect the user to after a successful login
• /auth/profile: The route to fetch the user profile
• /auth/access-token: The route to verify the user's session and return an access token (which automatically refreshes if a refresh token is available)
• /auth/backchannel-logout: The route to receive a logout_token when a configured Back-Channel Logout initiator occurs

Users can now log in to your application at /auth/login route provided by the SDK. Use an anchor tag to add a link to the login route to redirect your users to the Auth0 Universal Login Page, where Auth0 can authenticate them. Upon successful authentication, Auth0 redirects your users back to your application.

<a href="/auth/login">Login</a>

npm i && npm run dev

Now that you can log in to your Next.js application, you need a way to log out. Add a link that points to the /auth/logout API route. To learn more, read Log Users out of Auth0 with OIDC Endpoint.

<a href="/auth/logout">Logout</a>

The Auth0 Next.js SDK helps you retrieve the profile information associated with the logged-in user, such as their name or profile picture, to personalize the user interface.

The profile information is available through the user property exposed by the useUser() hook. Take this Client Component as an example of how to use it:

'use client';

export default function Profile() {
  const { user, isLoading } = useUser();
  return (
    <>
      {isLoading && <p>Loading...</p>}
      {user && (
        <div style={{ textAlign: "center" }}>
          <img
            src={user.picture}
            alt="Profile"
            style={{ borderRadius: "50%", width: "80px", height: "80px" }}
          />
          <h2>{user.name}</h2>
          <p>{user.email}</p>
          <pre>{JSON.stringify(user, null, 2)}</pre>
        </div>
      )}
    </>
  );
}

The user property contains sensitive information and artifacts related to the user's identity. As such, its availability depends on the user's authentication status. To prevent any render errors:

• Ensure that the SDK has completed loading before accessing the user property by checking that isLoading is false.
• Ensure that the SDK has loaded successfully by checking that no error was produced.
• Check the user property to ensure that Auth0 has authenticated the user before React renders any component that consumes it.

The profile information is available through the user property exposed by the getSession function. Take this Server Component as an example of how to use it:

import { auth0 } from "@/lib/auth0";

export default async function ProfileServer() {
  const { user } = await auth0.getSession(); 
  return ( user && ( <div> <img src={user.picture} alt={user.name}/> <h2>{user.name}</h2> <p>{user.email}</p> </div> )  ); 
}

We put together a few examples on how to use nextjs-auth0 for more advanced use cases.