> ## Documentation Index
> Fetch the complete documentation index at: https://auth0-cq3uo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Next.js

##### By Rita Zerrizuela

This guide demonstrates how to integrate Auth0 with any new or existing Next.js application using the Auth0 Next.js SDK.We recommend that you log in to follow this quickstart with examples configured for your account.

<Callout icon="file-lines" iconType="regular">
  **New to Auth?** Learn [How Auth0 works](/docs/overview), how it [integrates with Regular Web Applications](/docs/architecture-scenarios/web-app-sso) and which [protocol](/docs/flows) it uses.
</Callout>

## Configure Auth0

### Get Your Application Keys

When you signed up for Auth0, a new application was created for you, or you could have created a new one. You will need some details about that application to communicate with Auth0. You can get these details from the [Application Settings](https://manage.auth0.com/#/applications) section in the Auth0 dashboard.

<Frame>![App Dashboard](https://cdn2.auth0.com/docs/1.14550.0/media/articles/dashboard/client_settings.png)</Frame>

You need the following information:

* **Domain**
* **Client ID**
* **Client Secret**

<Callout icon="file-lines" iconType="regular">
  If you download the sample from the top of this page, these details are filled out for you.
</Callout>

### Configure Callback URLs

A callback URL is a URL in your application where Auth0 redirects the user after they have authenticated. The callback URL for your app must be added to the **Allowed Callback URLs** field in your [Application Settings](https://manage.auth0.com/#/applications). If this field is not set, users will be unable to log in to the application and will get an error.

<Callout icon="file-lines" iconType="regular">
  If you are following along with the sample project you downloaded from the top of this page, the callback URL you need to add to the **Allowed Callback URLs** field is `http://localhost:3000/auth/callback`.
</Callout>

### Configure Logout URLs

A logout URL is a URL in your application that Auth0 can return to after the user has been logged out of the authorization server. This is specified in the `returnTo` query parameter. The logout URL for your app must be added to the **Allowed Logout URLs** field in your [Application Settings](https://manage.auth0.com/#/applications). If this field is not set, users will be unable to log out from the application and will get an error.

<Callout icon="file-lines" iconType="regular">
  If you are following along with the sample project you downloaded from the top of this page, the logout URL you need to add to the **Allowed Logout URLs** field is `http://localhost:3000`.
</Callout>

## Install the Auth0 Next.js SDK

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

```bash lines theme={null}
npm install @auth0/nextjs-auth0
```

The SDK exposes methods and variables that help you integrate Auth0 with your Next.js application using [Route Handlers](https://nextjs.org/docs/app/building-your-application/routing/route-handlers) on the backend and [React Context](https://react.dev/reference/react/useContext) with [React Hooks](https://react.dev/reference/react/hooks) on the frontend.

### Configure the SDK

In the root directory of your project, create the file `.env.local` with the following [environment variables](https://nextjs.org/docs/app/guides/environment-variables):

```env lines theme={null}
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.

<Callout icon="file-lines" iconType="regular">
  Manually add the values for `AUTH0_AUDIENCE` and `AUTH_SCOPE` to the file `lib/auth0.js`. These values are not configured automatically.
  If you are using a [Custom Domain with Auth0](https://auth0.com/docs/custom-domains), set `AUTH0_DOMAIN` to the value of your Custom Domain instead of the value reflected in the application "Settings" tab.
</Callout>

### Create the Auth0 SDK Client

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.

```javascript lines theme={null}
// 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,
  }
});
```

### Add the Authentication Middleware

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.

```ts lines theme={null}
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.

#### Auto-configured routes

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](https://auth0.com/docs/secure/tokens/access-tokens) (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

<Callout icon="file-lines" iconType="regular">
  The `/auth/access-token` route is enabled by default, but is only neccessary when the access token is needed on the client-side. If this isn't something you need, you can disable this endpoint by setting `enableAccessTokenEndpoint` to `false`.
</Callout>

## Add Login to Your Application

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.

```html lines theme={null}
<a href="/auth/login">Login</a>
```

<Callout icon="file-lines" iconType="regular">
  Next.js suggests using [Link](https://nextjs.org/docs/api-reference/next/link) components instead of anchor tags, but since these are API routes and not pages, anchor tags are needed.
</Callout>

<Note>
  ### Checkpoint

  Add the login link to your application. Select it and verify that your Next.js application redirects you to the [Auth0 Universal Login](https://auth0.com/universal-login) page and that you can now log in or sign up using a username and password or a social provider.

  Once that's complete, verify that Auth0 redirects back to your application.

  If you are following along with the sample app project from the top of this page, run the command:

  ```bash lines theme={null}
  npm i && npm run dev
  ```

  and visit [http://localhost:3000](http://localhost:3000) in your browser.
</Note>

<Frame>![Auth0 Universal Login](https://cdn2.auth0.com/docs/1.14550.0/media/quickstarts/universal-login.png)</Frame>

<Callout icon="file-lines" iconType="regular">
  Auth0 enables the Google social provider by default on new tenants and offers you developer keys to test logging in with [social identity providers](/docs/connections/identity-providers-social). However, these developer keys have some limitations that may cause your application to behave differently. For more details on what this behavior may look like and how to fix it, consult the [Test Social Connections with Auth0 Developer Keys](/docs/connections/social/devkeys#limitations-of-developer-keys) document.
</Callout>

## Add Logout to Your Application

Now that you can log in to your Next.js application, you need [a way to log out](https://auth0.com/docs/logout/log-users-out-of-auth0). Add a link that points to the `/auth/logout` API route. To learn more, read [Log Users out of Auth0 with OIDC Endpoint](https://auth0.com/docs/authenticate/login/logout/log-users-out-of-auth0).

```html lines theme={null}
<a href="/auth/logout">Logout</a>
```

<Note>
  ### Checkpoint

  Add the logout link to your application. When you select it, verify that your Next.js application redirects you to the address you specified as one of the "Allowed Logout URLs" in the application "Settings".
</Note>

## Show User Profile Information

The Auth0 Next.js SDK helps you retrieve the [profile information](https://auth0.com/docs/users/user-profiles) associated with the logged-in user, such as their name or profile picture, to personalize the user interface.

### From a Client Component

The profile information is available through the `user` property exposed by the `useUser()` hook. Take this [Client Component](https://nextjs.org/docs/getting-started/react-essentials#client-components) as an example of how to use it:

```js lines theme={null}
'use client';
import { useUser } from "@auth0/nextjs-auth0"

export default function Profile() {
  const { user, isLoading } = useUser();
  return (
    <>
      {isLoading && <p>Loading...</p>}
      {user && (
        <div style={{ textAlign: "center" }}>
          <Frame><img
            src={user.picture}
            alt="Profile"
            style={{ borderRadius: "50%", width: "80px", height: "80px" }}
          /></Frame>
          <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.

### From a Server Component

The profile information is available through the `user` property exposed by the `getSession` function. Take this [Server Component](https://nextjs.org/docs/getting-started/react-essentials#server-components) as an example of how to use it:

```js lines theme={null}
import { auth0 } from "@/lib/auth0";

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

<Note>
  ### Checkpoint

  Verify that you can display the `user.name` or [any other](https://auth0.com/docs/users/user-profile-structure#user-profile-attributes) `user` property within a component correctly after you have logged in.
</Note>

## What's next?

We put together a few [examples](https://github.com/auth0/nextjs-auth0/blob/main/EXAMPLES.md) on how to use [nextjs-auth0](https://github.com/auth0/nextjs-auth0) for more advanced use cases.

[Edit on GitHub](https://github.com/auth0/docs/edit/master/articles/quickstart/webapp/nextjs/01-login.md)