zitadel/apps/docs/content/sdk-examples/nextjs.mdx

---
title: Next.js
description: "Integrate ZITADEL authentication into Next.js applications using the OAuth 2.0 PKCE flow."
sidebar_label: Next.js
framework_url: https://nextjs.org
auth_library: next-auth
auth_library_url: https://next-auth.js.org
example_repo: https://github.com/zitadel/example-auth-nextjs
auth_flow: pkce
status: stable
---

## Overview

[Next.js](https://nextjs.org) is a React framework for building full-stack web applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your Next.js application.

#### Auth library

This example uses **[next-auth](https://www.npmjs.com/package/next-auth)** with **[openid-client](https://www.npmjs.com/package/openid-client)** to implement the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manage [PKCE](https://oauth.net/2/pkce/) code challenge generation, perform secure token exchange, and provide session management helpers.

---

## What this example demonstrates

This Next.js application demonstrates a secure authentication flow using Zitadel with the industry-standard [PKCE flow](https://oauth.net/2/pkce/). Users start on a public landing page, initiate login via the Zitadel authorization server, and after successful authentication are redirected back to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).

The application implements session management using NextAuth.js with a JWT-based session strategy. It includes automatic callback handling with secure token exchange, route protection for authenticated-only pages, and an example of requesting additional [OIDC scopes](https://zitadel.com/docs/apis/openidoauth/scopes) (including `offline_access` for refresh tokens and Zitadel-specific scopes for metadata and roles).

The logout flow implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** via the end-session endpoint, terminating both the local session and the Zitadel session before redirecting the user back to the application. It also demonstrates automatic token refresh to maintain long-lived sessions without requiring users to re-authenticate.

---

## Getting started

### Prerequisites

Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the PKCE application setup guide to:

1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/api/auth/callback/zitadel` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/api/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions

> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production deployments, always use HTTPS URLs and disable Dev Mode.

### Run the example

Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/login-users):

1. Clone the [repository](https://github.com/zitadel/example-auth-nextjs).
2. Create a `.env.local` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications-overview). Use these environment variable names exactly as shown:
   ```
   NODE_ENV=development
   PORT=3000
   SESSION_SECRET=your-very-secret-and-strong-session-key
   SESSION_DURATION=3600
   ZITADEL_DOMAIN=https://your-zitadel-domain
   ZITADEL_CLIENT_ID=your-zitadel-application-client-id
   ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
   ZITADEL_CALLBACK_URL=http://localhost:3000/api/auth/callback/zitadel
   ZITADEL_POST_LOGIN_URL=/profile
   ZITADEL_POST_LOGOUT_URL=http://localhost:3000/api/auth/logout/callback
   NEXTAUTH_URL=http://localhost:3000
   ```
   Replace these values with:
	- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **ZITADEL_DOMAIN**)
	- The **Client ID** you copied when creating the application
	- A randomly generated **SESSION_SECRET** using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
	- A randomly generated **ZITADEL_CLIENT_SECRET** (required by Auth.js / NextAuth.js even though PKCE doesn't require it)
	- The **redirect URIs** you configured in the PKCE setup (must match exactly)
3. Install dependencies using [npm](https://www.npmjs.com) by running `npm install`, then start the development server with `npm run dev` to verify the authentication flow end-to-end at `http://localhost:3000`.

---

## Learn more and resources

* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Next.js documentation](https://nextjs.org)
* [NextAuth.js documentation](https://next-auth.js.org/)
* [Example repository](https://github.com/zitadel/example-auth-nextjs)