Next.js with ZITADEL

https://github.com/zitadel/example-auth-nextjs
Admin
The 'Next.js with ZITADEL' example project demonstrates how to implement a secure user login using...
Tokens:24,731
Snippets:377
Trust Score:9.8
License:Apache-2.0
Update:3 months ago
Show doc for...
Tokens:
Raw
### Install and Run the Application

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/README.md

Commands to clone the repository, install dependencies, and start the development server.

```bash
# 1. Clone the repository
git clone git@github.com:zitadel/example-auth-nextjs.git

cd example-auth-nextjs

# 2. Install the project dependencies
npm install

# 3. Start the development server
npm start
# or
make start
```

--------------------------------

### Example Sign-In Error URLs

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/message-errors.md

Example URL structures for triggering sign-in error states.

```text
/auth/login?error=AccessDenied
/auth/login?error=OAuthCallback
```

--------------------------------

### Example Error Page URLs

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/message-errors.md

Example URL structures for triggering the dedicated error page.

```text
/auth/error?error=Configuration
/auth/error?error=AccessDenied
```

--------------------------------

### Usage Example for buildLogoutUrl

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Implementation example within a Next.js logout route, including cookie storage for the CSRF state.

```typescript
// Called in logout endpoint
import { buildLogoutUrl } from '@/lib/auth';

const session = await getSession(request);
if (!session?.idToken) {
  return NextResponse.json(
    { error: 'No valid session' },
    { status: 400 }
  );
}

const { url, state } = await buildLogoutUrl(session.idToken);

const response = NextResponse.redirect(url);
response.cookies.set('logout_state', state, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax',
  path: '/api/auth/logout/callback',
});

return response;
```

--------------------------------

### Start Development Server

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Command to launch the development server to apply changes.

```bash
npm run dev
```

--------------------------------

### View header output

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Example of expected security headers in the response.

```text
X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline';
Referrer-Policy: strict-origin-when-cross-origin
```

--------------------------------

### signIn Usage Examples

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Demonstrates implementing a login button component and a simple inline click handler.

```tsx
import { signIn } from '@zitadel/next-auth/react';

export function LoginButton() {
  const handleLogin = async () => {
    await signIn('zitadel', {
      redirect: true,
      redirectTo: '/profile'
    });
  };
  
  return <button onClick={handleLogin}>Login</button>;
}

// In home page (click handler)
<button onClick={() => signIn('zitadel')}>
  Login with Zitadel
</button>
```

--------------------------------

### Fetch User Information

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Example usage for fetching and displaying user information from the API route.

```typescript
// Fetch user info
const response = await fetch('/api/userinfo');
const userInfo = await response.json();

if (response.ok) {
  console.log('User:', userInfo.name);
  console.log('Email:', userInfo.email);
  console.log('Organization:', userInfo['urn:zitadel:iam:user:resourceowner'].name);
} else {
  console.error('Failed to fetch user info:', userInfo.error);
}
```

--------------------------------

### Email Scope Claims Example

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Example of the email and verification status claims returned when the email scope is requested.

```typescript
{
  email: "john@example.com",
  email_verified: true
}
```

--------------------------------

### Implement project-based RBAC

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Example of project role claims and how to check for specific roles within an application session.

```typescript
{
  'urn:zitadel:iam:org:project:111111111111111111:roles': [
    'admin',
    'editor'
  ],
  'urn:zitadel:iam:org:project:222222222222222222:roles': [
    'viewer'
  ]
}
```

```typescript
const session = await getSession();
const roles = session.idToken['urn:zitadel:iam:org:project:projectid:roles'];

if (roles?.includes('admin')) {
  // Show admin features
}
```

--------------------------------

### Phone Scope Claims Example

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Example of the phone number and verification status claims returned when the phone scope is requested.

```typescript
{
  phone_number: "+12025551234",
  phone_number_verified: true
}
```

--------------------------------

### Logout Usage Examples

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Methods for triggering the logout process via HTML form or programmatic fetch request.

```html
<!-- Form submission to logout endpoint -->
<form action="/api/auth/logout" method="POST">
  <button type="submit">Sign out</button>
</form>
```

```typescript
// Programmatic logout
const response = await fetch('/api/auth/logout', {
  method: 'POST'
});

if (response.ok) {
  // Browser will follow redirect
  window.location.href = await response.text();
}
```

--------------------------------

### Production Hardening for CSP

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Provides examples for tightening CSP policies in production environments using nonces or trusted domains.

```typescript
'script-src \'self\' \'nonce-{random}\';'
```

```typescript
'script-src \'self\' https://cdn.trusted.com;'
```

--------------------------------

### Profile Scope JWT Claims Example

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Example of the user profile information returned within a session or JWT when the profile scope is requested.

```typescript
// In session/JWT
{
  name: "John Doe",
  given_name: "John",
  family_name: "Doe",
  picture: "https://zitadel.cloud/profile/johndoe.jpg",
  locale: "en-US"
}
```

--------------------------------

### Refresh Token Grant Execution

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/types.md

Example of using the refresh token to obtain new credentials.

```typescript
// In refreshAccessToken()
const newTokens = await oidc.refreshTokenGrant(
  config,
  token.refreshToken as string
);
```

--------------------------------

### Information Leakage Prevention Example

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Demonstrates how the Referrer-Policy header prevents sensitive information leakage in URLs when navigating to external sites.

```text
Link: /profile?secret_token=abc123
Without policy: External site receives full URL
With policy: External site receives only origin
```

--------------------------------

### Handle API Errors

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Example of handling 401 unauthorized errors and general API failures.

```typescript
const response = await fetch('/api/userinfo');
const data = await response.json();

if (response.status === 401) {
  // Session expired or no access token
  // Trigger re-authentication
  window.location.href = '/api/auth/signin/zitadel';
} else if (!response.ok) {
  // ZITADEL API error
  console.error('UserInfo API error:', data.error);
}
```

--------------------------------

### Example JWT Claims Structure

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/types.md

Representation of claims included in the JWT based on requested scopes.

```javascript
{
  // OpenID Connect standard claims
  iss: 'https://my-org.zitadel.cloud',
  sub: 'user-id-123',
  aud: 'client-id',
  exp: 1234567890,
  iat: 1234563290,
  auth_time: 1234563290,
  
  // Profile scope claims
  name: 'John Doe',
  given_name: 'John',
  family_name: 'Doe',
  picture: 'https://...',
  locale: 'en-US',
  
  // Email scope claims
  email: 'john@example.com',
  email_verified: true,
  
  // ZITADEL-specific claims
  'urn:zitadel:iam:user:metadata': { ... },
  'urn:zitadel:iam:user:resourceowner': {
    id: 'org-id',
    name: 'Organization Name',
    primary_domain: 'org.zitadel.cloud'
  },
  'urn:zitadel:iam:org:projects:roles': {
    'project-id': ['admin', 'member']
  }
}
```

--------------------------------

### ZITADEL UserInfo JSON Response Structure

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Example of the JSON structure returned by the ZITADEL OpenID Connect UserInfo endpoint.

```json
{
  "sub": "user-id",
  "email": "user@example.com",
  "email_verified": true,
  "name": "User Name",
  "given_name": "User",
  "family_name": "Name",
  "picture": "https://example.com/picture.jpg",
  "locale": "en-US",
  "updated_at": 1234567890,
  "urn:zitadel:iam:user:metadata": {...},
  "urn:zitadel:iam:user:resourceowner": {...},
  "urn:zitadel:iam:org:projects:roles": {...}
}
```

--------------------------------

### GET /api/auth/session

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Fetches the current user session information.

```APIDOC
## GET /api/auth/session

### Description
Retrieves the current session details, including tokens. Triggers a token refresh if the session is expired.

### Method
GET

### Endpoint
/api/auth/session

### Response
#### Success Response (200)
- **idToken** (string) - The user's ID token
- **accessToken** (string) - The user's access token
- **error** (string|null) - Error status if applicable

#### Response Example
{
  "idToken": "eyJ...",
  "accessToken": "eyJ...",
  "error": null
}
```

--------------------------------

### Define GET Handler Signature

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

The TypeScript signature for the API route handler.

```typescript
export async function GET(request: Request): Promise<NextResponse>
```

--------------------------------

### Example of Over-requesting Scopes

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Avoid requesting unnecessary scopes like address, phone, or project IDs.

```typescript
'openid',
'profile',
'email',
'address',
'phone',
'urn:zitadel:iam:org:project:id:zitadel:aud'
```

--------------------------------

### Access resource owner information

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Example of the resource owner claim structure and a pattern for implementing tenant isolation.

```typescript
{
  'urn:zitadel:iam:user:resourceowner': {
    id: "123456789012345678",
    name: "Acme Corporation",
    primary_domain: "acme.zitadel.cloud"
  }
}
```

```typescript
const session = await getSession();
const orgId = session.idToken['urn:zitadel:iam:user:resourceowner:id'];
// Filter data by orgId for tenant isolation
```

--------------------------------

### Logout Error Handling

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Example of handling a 400 status code when no valid session is found during logout.

```typescript
const response = await fetch('/api/auth/logout', { method: 'POST' });

if (!response.ok) {
  if (response.status === 400) {
    // No valid session - already logged out or session expired
    window.location.href = '/';
  }
}
```

--------------------------------

### GET /api/userinfo

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/README.md

Retrieves extended user profile information from the ZITADEL identity provider.

```APIDOC
## GET /api/userinfo

### Description
Fetches extended user information from ZITADEL for the currently authenticated session.

### Method
GET

### Endpoint
/api/userinfo
```

--------------------------------

### Define handler object structure

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Defines the expected structure for GET and POST request handlers.

```typescript
const handlers: {
  GET: (request: NextRequest) => Promise<NextResponse>
  POST: (request: NextRequest) => Promise<NextResponse>
}
```

--------------------------------

### Perform administrative API operations

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Examples of administrative API calls enabled by the ZITADEL Management API audience scope.

```typescript
// List users in organization
GET /management/v1/users

// Create new user
POST /management/v1/users

// Modify user attributes
PUT /management/v1/users/{userId}
```

--------------------------------

### Refresh Access Token Usage

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Example of how the refreshAccessToken function is invoked within the NextAuth.js jwt callback.

```typescript
// This function is called automatically by the jwt callback
// Do not call directly in application code

// The jwt callback handles this:
const newToken = await refreshAccessToken(expiredToken);
if (newToken.error) {
  // Force user to sign in again
  session.error = newToken.error;
}
```

--------------------------------

### Retrieve user metadata scope

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Example of the user metadata claim structure returned when the urn:zitadel:iam:user:metadata scope is requested.

```typescript
{
  'urn:zitadel:iam:user:metadata': {
    department: "Engineering",
    employee_id: "EMP-12345",
    cost_center: "CC-789"
  }
}
```

--------------------------------

### Simulate Clickjacking Attack

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

An example of how an attacker might attempt to embed a site in a hidden iframe to hijack user clicks.

```html
<!-- Attacker's site -->
<iframe src="https://yourapp.com/profile" style="opacity: 0;"></iframe>
<button>Click here for free pizza</button>
<!-- Attacker captures clicks meant for hidden iframe -->
```

--------------------------------

### Implement ErrorBoundary Usage

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Examples of wrapping components with ErrorBoundary, including custom fallbacks and conditional error detail display.

```tsx
import { ErrorBoundary } from '@/components/ErrorBoundary';
import { DataTable } from './DataTable';

// Basic usage
<ErrorBoundary>
  <DataTable />
</ErrorBoundary>

// With custom fallback
<ErrorBoundary fallback={<div>Something broke</div>}>
  <DataTable />
</ErrorBoundary>

// Show error details in development
<ErrorBoundary showDetails={process.env.NODE_ENV === 'development'}>
  <App />
</ErrorBoundary>
```

--------------------------------

### Complete .env.local Configuration

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

A comprehensive template for all required application, session, ZITADEL, and NextAuth environment variables.

```bash
# ==============================================================================
# Application Environment
# ==============================================================================
NODE_ENV=development
PORT=3000

# ==============================================================================
# Session Configuration
# ==============================================================================
SESSION_SECRET="a7f3d2e1c9b8a6f5d4e3c2b1a0f9e8d7c6b5a4f3d2e1c0b9a8f7e6d5c4b3a2"
SESSION_DURATION=3600

# ==============================================================================
# ZITADEL Configuration
# ==============================================================================
ZITADEL_DOMAIN="https://my-org-a1b2c3.zitadel.cloud"
ZITADEL_CLIENT_ID="12345678901234567890"
ZITADEL_CLIENT_SECRET="b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0"
ZITADEL_CALLBACK_URL="http://localhost:3000/api/auth/callback/zitadel"
ZITADEL_POST_LOGOUT_URL="http://localhost:3000/api/auth/logout/callback"
ZITADEL_POST_LOGIN_URL="/profile"

# ==============================================================================
# NextAuth Configuration
# ==============================================================================
NEXTAUTH_URL="http://localhost:3000"
```

--------------------------------

### Build Application

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Command to compile the application after modifying scope configurations.

```bash
npm run build
```

--------------------------------

### Environment-Specific Configurations

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Configuration variants tailored for development, staging, and production deployment environments.

```bash
NODE_ENV=development
ZITADEL_DOMAIN="https://dev.zitadel.cloud"
ZITADEL_CALLBACK_URL="http://localhost:3000/api/auth/callback/zitadel"
ZITADEL_POST_LOGOUT_URL="http://localhost:3000/api/auth/logout/callback"
SESSION_SECRET="[generated-secret]"
NEXTAUTH_URL="http://localhost:3000"
```

```bash
NODE_ENV=production
ZITADEL_DOMAIN="https://staging.zitadel.cloud"
ZITADEL_CALLBACK_URL="https://staging.yourdomain.com/api/auth/callback/zitadel"
ZITADEL_POST_LOGOUT_URL="https://staging.yourdomain.com/api/auth/logout/callback"
SESSION_SECRET="[generated-secret]"
NEXTAUTH_URL="https://staging.yourdomain.com"
```

```bash
NODE_ENV=production
ZITADEL_DOMAIN="https://zitadel.yourdomain.com"
ZITADEL_CALLBACK_URL="https://yourdomain.com/api/auth/callback/zitadel"
ZITADEL_POST_LOGOUT_URL="https://yourdomain.com/api/auth/logout/callback"
SESSION_SECRET="[generated-secret-unique-per-environment]"
NEXTAUTH_URL="https://yourdomain.com"
```

--------------------------------

### GET /api/auth/logout/callback

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/README.md

Handles the callback request after a successful logout from the ZITADEL identity provider.

```APIDOC
## GET /api/auth/logout/callback

### Description
Processes the logout callback handler after the user has been logged out from ZITADEL.

### Method
GET

### Endpoint
/api/auth/logout/callback
```

--------------------------------

### Trigger Login with Zitadel

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Use the signIn function from @zitadel/next-auth/react to initiate the PKCE authentication flow.

```typescript
import { signIn } from '@zitadel/next-auth/react';

<button onClick={() => signIn('zitadel')}>
  Login
</button>
```

--------------------------------

### Configure Server Port

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Demonstrates that the PORT variable in .env.local is ignored by Next.js and must be set via CLI.

```bash
# .env.local (ignored)
PORT=3000

# CLI (effective)
npm run dev -- -p 4000
```

--------------------------------

### Use Header Component

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Demonstrates rendering the Header component based on the user's authentication state.

```tsx
import { Header } from '@/components/Header';

// On public page (logged out)
<Header isAuthenticated={false} />

// On protected page (logged in)
<Header isAuthenticated={true} />
```

--------------------------------

### Open Scopes Configuration File

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Command to access the file where ZITADEL scopes are defined.

```bash
vi src/lib/scopes.ts
```

--------------------------------

### ZITADEL Domain Configuration

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Defines the ZITADEL instance URL and the discovery endpoint format.

```bash
GET {ZITADEL_DOMAIN}/.well-known/openid-configuration
```

```bash
ZITADEL_DOMAIN="https://my-org.zitadel.cloud"
```

--------------------------------

### Logout Callback Handler Signature

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

The TypeScript signature for the GET logout callback route handler.

```typescript
export async function GET(request: NextRequest): Promise<NextResponse>
```

--------------------------------

### Offline Access Refresh Flow and Implementation

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Demonstrates the conceptual flow of using refresh tokens and the implementation logic for refreshing access tokens in authentication callbacks.

```text
1. User logs in, receives access token (1 hour) + refresh token
2. After 1 hour of use, access token expires
3. refreshAccessToken() uses refresh token to get new access token
4. User continues using app without re-authenticating
```

```typescript
// In authOptions.callbacks.jwt
if (Date.now() >= token.expiresAt) {
  return refreshAccessToken(token);  // Uses offline_access
}
```

--------------------------------

### Global Stylesheet Import

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Loads Tailwind CSS and global styles into the application.

```typescript
import './globals.css';
```

--------------------------------

### GET/POST /api/auth/signin/zitadel

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Initiates the sign-in process by redirecting the user to the ZITADEL authorization endpoint.

```APIDOC
## GET/POST /api/auth/signin/zitadel

### Description
Sign-in initiation endpoint that generates PKCE parameters and redirects the user to ZITADEL for authentication.

### Method
POST

### Endpoint
/api/auth/signin/zitadel

### Parameters
#### Request Body
- **csrfToken** (string) - Required - CSRF protection token
- **callbackUrl** (string) - Optional - URL to redirect to after successful sign-in

### Response
- 302 redirect to ZITADEL authorization endpoint
```

--------------------------------

### Callbacks

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Documentation for the lifecycle callbacks used to manage authentication state, token refreshing, and session data.

```APIDOC
## Callbacks

### redirect
Controls post-login destination. Defaults to /profile or ZITADEL_POST_LOGIN_URL.

### jwt
Manages token lifecycle. Handles initial login token extraction and automatic refresh of expired access tokens.

### session
Transforms the JWT into a session object. Exposes idToken and accessToken to the application while keeping refresh tokens server-side.
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/README.md

Define the required ZITADEL and session configuration in a .env.local file. Ensure the SESSION_SECRET and ZITADEL_CLIENT_SECRET are cryptographically secure strings.

```dotenv
# Port number where your Next.js server will listen for incoming HTTP requests.
# Change this if port 3000 is already in use on your system.
# Note: Next.js does not load .env.local early enough to pick the port for its own server startup.
# That means Next.js chooses its default port (3000) unless you pass one from the shell or CLI flag.
# E.g. `npm run dev -- -p 4000`
PORT=3000

# Session timeout in seconds. Users will be automatically logged out after this
# duration of inactivity. 3600 seconds = 1 hour.
SESSION_DURATION=3600

# Secret key used to cryptographically sign session cookies to prevent
# tampering. MUST be a long, random string. Generate a secure key using:
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
SESSION_SECRET="your-very-secret-and-strong-session-key"

# Your ZITADEL instance domain URL. Found in your ZITADEL console under
# instance settings. Include the full https:// URL.
# Example: https://my-org-a1b2c3.zitadel.cloud
ZITADEL_DOMAIN="https://your-zitadel-domain"

# Application Client ID from your ZITADEL application settings. This unique
# identifier tells ZITADEL which application is making the authentication
# request.
ZITADEL_CLIENT_ID="your-client-id"

# While the Authorization Code Flow with PKCE for public clients
# does not strictly require a client secret for OIDC specification compliance,
# Auth.js will still require a value for its internal configuration.
# Therefore, please provide a randomly generated string here.
# You can generate a secure key using:
# node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
ZITADEL_CLIENT_SECRET="your-randomly-generated-client-secret"

# OAuth callback URL where ZITADEL redirects after user authentication. This
# MUST exactly match a Redirect URI configured in your ZITADEL application.
ZITADEL_CALLBACK_URL="http://localhost:3000/api/auth/callback/zitadel"

# URL where users are redirected after logout. This should match a Post Logout
# Redirect URI configured in your ZITADEL application settings.
ZITADEL_POST_LOGOUT_URL="http://localhost:3000/api/auth/logout/callback"

# Optional. URL where users are redirected after successful login.
# Defaults to "/profile" if not specified.
ZITADEL_POST_LOGIN_URL="/profile"

# NextAuth.js base URL for your application. In development, this is typically
# http://localhost:3000. In production, use your actual domain.
NEXTAUTH_URL="http://localhost:3000"
```

--------------------------------

### Configure NEXTAUTH_URL

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Sets the base URL of the application, which is recommended for production and custom domain configurations.

```bash
NEXTAUTH_URL="http://localhost:3000"
```

--------------------------------

### Implement ZITADEL_POST_LOGIN_URL redirection

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Logic for handling post-login redirection, supporting both relative paths and absolute URLs.

```typescript
async redirect({ baseUrl }) {
  const postLoginUrl = process.env.ZITADEL_POST_LOGIN_URL || '/profile';
  return postLoginUrl.startsWith('http')
    ? postLoginUrl
    : `${baseUrl}${postLoginUrl}`;
}
```

```bash
ZITADEL_POST_LOGIN_URL="/dashboard"
```

--------------------------------

### Usage in API and Server Components

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Demonstrates how to export handlers and retrieve sessions in a Next.js application.

```typescript
import { authOptions, handlers, getSession } from '@/lib/auth';

// In API route handlers:
export const { GET, POST } = handlers;

// In server components:
const session = await getSession();

// In logout endpoint:
const { url, state } = await buildLogoutUrl(session?.idToken);
```

--------------------------------

### Define Next.js Directory Structure

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Visual representation of the project's file-based routing layout within the src/app directory.

```text
src/app/
├── page.tsx                      # / (home)
├── layout.tsx                    # Root layout
├── not-found.tsx                 # 404 page
├── globals.css                   # Global styles
├── profile/
│   └── page.tsx                  # /profile (protected)
├── auth/
│   ├── login/
│   │   └── page.tsx              # /auth/login
│   ├── error/
│   │   └── page.tsx              # /auth/error
│   └── (auth-group)/             # Route group (not a route)
├── logout/
│   ├── success/
│   │   └── page.tsx              # /logout/success
│   └── error/
│       └── page.tsx              # /logout/error
└── api/
    └── auth/
        ├── logout/
        │   ├── route.ts          # POST /api/auth/logout
        │   └── callback/
        │       └── route.ts      # GET /api/auth/logout/callback
        ├── [...]nextauth]/
        │   └── route.ts          # OAuth routes
        └── userinfo/
            └── route.ts          # GET /api/userinfo
```

--------------------------------

### Integrate ZitadelProvider in RootLayout

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Wrapping the application layout with the provider to enable session access.

```tsx
// src/app/layout.tsx
import { ZitadelProvider } from '@/app/providers';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ZitadelProvider>
          {children}
        </ZitadelProvider>
      </body>
    </html>
  );
}
```

--------------------------------

### Initialize NextAuth handlers

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Exports the necessary handlers and utility functions from the NextAuth configuration.

```typescript
export const { handlers, getSession, signInUrl, signOutUrl } = NextAuth(authOptions)
```

--------------------------------

### Configure ZITADEL_CALLBACK_URL

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Sets the OAuth authorization code callback URL. Must match exactly one of the Redirect URIs configured in the ZITADEL Console.

```bash
ZITADEL_CALLBACK_URL="http://localhost:3000/api/auth/callback/zitadel"
```

--------------------------------

### Authentication Handlers

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

The handlers object provides GET and POST methods to manage the OAuth 2.0 flow, including sign-in, callback handling, session management, and sign-out.

```APIDOC
## [GET/POST] /api/auth/*

### Description
Handles OAuth 2.0 Authorization Code Flow + PKCE, including redirecting to ZITADEL, processing callbacks, and managing session cookies.

### Endpoints
- POST /api/auth/signin/zitadel: Initiates the sign-in process.
- GET /api/auth/callback/zitadel: Handles the authorization code callback.
- GET /api/auth/session: Fetches the current session.
- POST /api/auth/signout: Signs out the user locally.
```

--------------------------------

### Implement JWT Callback

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/types.md

Handles initial login and subsequent token refresh logic.

```typescript
async jwt({ token, account, user }) {
  if (account && user) {
    // Initial login - store tokens
    return { ...token, idToken: account.id_token, ... };
  }
  // Subsequent access - check expiry and refresh if needed
  if (Date.now() >= token.expiresAt) {
    return refreshAccessToken(token);
  }
  return token;
}
```

--------------------------------

### Test headers with curl

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Use curl to inspect the response headers of your application.

```bash
curl -i https://yourapp.com
```

--------------------------------

### Usage of signInUrl

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Generates a login URL with an optional redirect path.

```typescript
import { signInUrl } from '@/lib/auth';

// Generate login URL with redirect
const loginUrl = signInUrl({ redirectTo: '/dashboard' });

// Redirect unauthenticated user
redirect(loginUrl);
```

--------------------------------

### Application Metadata Configuration

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Defines the page title, description, and favicon for the application.

```typescript
export const metadata: Metadata = {
  title: 'Zitadel PKCE Demo',
  description: 'PKCE authentication demo with Zitadel',
  icons: {
    icon: '/favicon.svg',
  },
};
```

--------------------------------

### Logout Usage Flow

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Step-by-step sequence of the logout process.

```text
1. User clicks logout button
2. POST to /api/auth/logout
3. Server generates state, sets cookie, redirects to ZITADEL
4. User signs out at ZITADEL
5. ZITADEL redirects to /api/auth/logout/callback?state=...
6. Callback validates state, clears cookies
7. Redirect to /logout/success
```

--------------------------------

### signIn(providerId, options)

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Triggers the authentication flow by redirecting the user to the ZITADEL authorization endpoint.

```APIDOC
## signIn(providerId, options)

### Description
Client-side function to trigger the authentication flow. It initiates a PKCE OAuth flow, redirects the user to ZITADEL, and handles the session creation upon return.

### Signature
`signIn(providerId?: string, options?: SignInOptions): Promise<SignInResponse | undefined>`

### Parameters
- **providerId** (string) - Optional - Provider name (e.g., 'zitadel')
- **options** (SignInOptions) - Optional - Configuration object for redirect behavior

### Options Object
- **redirect** (boolean) - Optional - Whether to redirect after login (Default: true)
- **redirectTo** (string) - Optional - Path to redirect to after successful login

### Returns
- **error** (string) - Error message if authentication fails
- **status** (number) - HTTP status code
- **ok** (boolean) - Success status
- **url** (string) - Redirect URL

### Usage Example
```tsx
import { signIn } from '@zitadel/next-auth/react';

const handleLogin = async () => {
  await signIn('zitadel', {
    redirect: true,
    redirectTo: '/profile'
  });
};
```
```

--------------------------------

### Define Callback URL

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Sets the default redirect destination after a successful login.

```typescript
const callbackUrl = searchParams.get('callbackUrl') ?? '/profile';
```

--------------------------------

### Implement redirect callback

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Controls the post-login redirect destination based on environment variables.

```typescript
async redirect({ baseUrl }): Promise<string>
```

```typescript
// With ZITADEL_POST_LOGIN_URL="/dashboard"
// Returns: "http://localhost:3000/dashboard"

// Without ZITADEL_POST_LOGIN_URL
// Returns: "http://localhost:3000/profile"
```

--------------------------------

### signInUrl

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Generates a sign-in URL with an optional redirect parameter for authentication.

```APIDOC
## signInUrl

### Description
Generates a sign-in URL to redirect the user to the authentication page. If a redirectTo path is provided, it is appended as a callbackUrl query parameter.

### Signature
`signInUrl(options?: { redirectTo?: string }) => string`

### Parameters
- **redirectTo** (string) - Optional - Path to redirect after successful login.

### Returns
- **string** - The sign-in URL (e.g., /auth/login?callbackUrl=/profile).

### Usage Example
```typescript
import { signInUrl } from '@/lib/auth';
const loginUrl = signInUrl({ redirectTo: '/dashboard' });
```
```

--------------------------------

### Sign-In Form Submission

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Submits the sign-in request to the provider URL with required CSRF and callback tokens.

```html
<form action={provider.signinUrl} method="POST">
  <input type="hidden" name="csrfToken" value={csrfToken} />
  <input type="hidden" name="callbackUrl" value={callbackUrl} />
  <button type="submit">
    Sign in with {provider.name}
  </button>
</form>
```

--------------------------------

### buildLogoutUrl(idToken: string)

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Constructs a ZITADEL logout URL with CSRF protection via a state parameter.

```APIDOC
## Function: `buildLogoutUrl`

### Description
Constructs a ZITADEL logout URL with CSRF protection via state parameter. This function performs OIDC metadata discovery and generates a random UUID for state validation.

### Signature
`export async function buildLogoutUrl(idToken: string): Promise<{ url: string; state: string }>`

### Parameters
- **idToken** (string) - Required - User's OpenID Connect ID token from session.

### Returns
- **url** (string) - Full logout endpoint URL to redirect user to.
- **state** (string) - CSRF state parameter (random UUID for validation).

### Usage Example
```typescript
import { buildLogoutUrl } from '@/lib/auth';

const { url, state } = await buildLogoutUrl(session.idToken);

const response = NextResponse.redirect(url);
response.cookies.set('logout_state', state, {
  httpOnly: true,
  secure: process.env.NODE_ENV === 'production',
  sameSite: 'lax',
  path: '/api/auth/logout/callback',
});
```
```

--------------------------------

### Implement Protected Page in Next.js

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Demonstrates server-side session verification and redirection for protected routes.

```tsx
import { getSession } from '@/lib/auth';
import { Header } from '@/components/Header';
import { Footer } from '@/components/Footer';
import { redirect } from 'next/navigation';

export default async function ProtectedPage() {
  // Server-side session check
  const session = await getSession();
  
  if (!session) {
    redirect('/auth/login');
  }
  
  return (
    <div className="flex flex-col min-h-screen">
      <Header isAuthenticated={true} />
      <main className="flex-1">
        {/* Page content */}
      </main>
      <Footer />
    </div>
  );
}
```

--------------------------------

### Implement ZitadelProvider

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Client-side wrapper component that provides session context to the application.

```typescript
'use client';

import { SessionProvider } from '@zitadel/next-auth/react';

export function ZitadelProvider({ children }: { children: ReactNode }) {
  return <SessionProvider>{children}</SessionProvider>;
}
```

--------------------------------

### Define Minimal OAuth Scopes

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/oauth-scopes.md

Recommended approach for requesting only necessary user information.

```typescript
'openid',
'profile',
'email'
```

--------------------------------

### Root Layout Structure

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

The main layout component wrapping all pages with global styles, error boundaries, and the Zitadel session provider.

```typescript
export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body className="flex min-h-screen flex-col bg-gray-50">
        <ErrorBoundary showDetails={process.env.NODE_ENV === 'development'}>
          <ZitadelProvider>
            {children}
          </ZitadelProvider>
        </ErrorBoundary>
      </body>
    </html>
  );
}
```

--------------------------------

### Define authOptions for ZITADEL

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

The configuration object for NextAuth.js using the ZITADEL provider.

```typescript
export const authOptions: NextAuthConfig
```

```typescript
const authOptions: NextAuthConfig = {
  providers: [
    Zitadel({
      issuer: string,              // ZITADEL_DOMAIN
      clientId: string,            // ZITADEL_CLIENT_ID
      clientSecret: string,        // ZITADEL_CLIENT_SECRET
      authorization: {
        params: { scope: string }  // ZITADEL_SCOPES
      }
    })
  ],
  session: {
    strategy: 'jwt',
    maxAge: number               // SESSION_DURATION or 3600
  },
  secret: string,               // SESSION_SECRET
  pages: {
    signIn: '/auth/login',
    error: '/auth/error'
  },
  callbacks: {
    redirect,
    jwt,
    session
  }
}
```

--------------------------------

### GET/POST /api/auth/callback/zitadel

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-routes.md

Handles the OAuth authorization code callback from ZITADEL to complete the authentication flow.

```APIDOC
## GET/POST /api/auth/callback/zitadel

### Description
OAuth authorization code callback handler that processes the authorization code and state from ZITADEL to finalize the authentication.

### Method
GET

### Endpoint
/api/auth/callback/zitadel

### Parameters
#### Query Parameters
- **code** (string) - Required - Authorization code from ZITADEL
- **state** (string) - Required - PKCE state parameter
- **error** (string) - Optional - Error code if authorization failed

### Response
- 302 redirect to post-login URL (default: /profile)
- Sets session cookie with tokens
- 302 redirect to error page if failed
```

--------------------------------

### SignInOptions Interface

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Configuration options for the signIn function, including redirect behavior.

```typescript
interface SignInOptions {
  redirect?: boolean        // Default: true
  redirectTo?: string       // Path after login
  // Additional NextAuth.js options
}
```

--------------------------------

### Fetch Providers and CSRF Token

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Fetches available authentication providers and the CSRF token on component mount.

```typescript
const [providers, setProviders] = useState(null);

useEffect(() => {
  const fetchProviders = async () => {
    const [providersData, tokenData] = await Promise.all([
      getProviders(),
      getCsrfToken(),
    ]);
    setProviders(providersData);
    setCsrfToken(tokenData || '');
  };
  void fetchProviders();
}, []);
```

--------------------------------

### Configure Security Headers in Next.js

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/README.md

Define custom security headers in next.config.js to enhance application security. This configuration includes X-Frame-Options, Content-Security-Policy, and Referrer-Policy.

```javascript
/** @type {import('next').NextConfig} */
const nextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'X-Frame-Options',
            value: 'DENY',
          },
          {
            key: 'Content-Security-Policy',
            value:
              "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline';",
          },
          {
            key: 'Referrer-Policy',
            value: 'strict-origin-when-cross-origin',
          },
        ],
      },
    ];
  },
};
```

--------------------------------

### Set Node Environment

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Defines the application environment, affecting cookie security flags.

```bash
NODE_ENV=production
```

--------------------------------

### signOutUrl

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Generates a sign-out URL for local session termination.

```APIDOC
## signOutUrl

### Description
Generates a sign-out URL to terminate the local session. Note that this does not log the user out from the ZITADEL instance; use buildLogoutUrl() for full logout.

### Signature
`signOutUrl() => string`

### Returns
- **string** - The sign-out endpoint URL (typically /api/auth/signout).

### Usage Example
```typescript
import { signOutUrl } from '@/lib/auth';
const logoutEndpoint = signOutUrl();
```
```

--------------------------------

### Configure ZITADEL_POST_LOGOUT_URL

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Defines the URL where users are redirected after logging out. Must be registered in the Post Logout Redirect URIs section of the ZITADEL Console.

```bash
ZITADEL_POST_LOGOUT_URL="http://localhost:3000/api/auth/logout/callback"
```

--------------------------------

### Implement CSP Report-Only mode

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Use the Report-Only header to test CSP policies without blocking resources.

```typescript
{
  key: 'Content-Security-Policy-Report-Only',
  value: '...',
}
```

```typescript
// Testing phase: Report-Only
key: 'Content-Security-Policy-Report-Only',
value: "default-src 'none'; ...",

// Production: Enforced
key: 'Content-Security-Policy',
value: "default-src 'none'; ...",
```

--------------------------------

### Configure Permissions-Policy

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Disables unused browser APIs like camera, microphone, and geolocation to reduce the attack surface.

```typescript
{
  key: 'Permissions-Policy',
  value: 'camera=(), microphone=(), geolocation=()',
}
```

--------------------------------

### Generate and Set ZITADEL Client Secret

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Generates a random string for Auth.js client authentication and sets the environment variable.

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

```bash
ZITADEL_CLIENT_SECRET="b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0"
```

--------------------------------

### Implementing a Dedicated Error Page

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/message-errors.md

Use this snippet to create a standalone error page that displays headings and messages for authentication failures.

```typescript
import { getMessage } from '@/lib/message';

const error = searchParams.get('error') || 'default';
const { heading, message } = getMessage(error, 'auth-error');

return (
  <div>
    <h1>{heading}</h1>
    <p>{message}</p>
    <Link href="/auth/login">Try signing in again</Link>
  </div>
);
```

--------------------------------

### POST /api/auth/logout

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/README.md

Initiates the logout process for the current user session via ZITADEL.

```APIDOC
## POST /api/auth/logout

### Description
Initiates the ZITADEL logout flow for the authenticated user.

### Method
POST

### Endpoint
/api/auth/logout
```

--------------------------------

### Configure Content-Security-Policy

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Defines the CSP directives for development and production environments to restrict resource loading and script execution.

```text
script-src 'self' 'unsafe-eval' 'unsafe-inline'
```

```text
script-src 'self' 'nonce-{csp_nonce}'
style-src 'self'
img-src 'self' data: https:
font-src 'self'
connect-src 'self'
default-src 'none'
```

--------------------------------

### Validate Required Environment Variables

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Ensures essential environment variables are present before application startup to prevent runtime errors.

```typescript
const required = [
  'ZITADEL_DOMAIN',
  'ZITADEL_CLIENT_ID',
  'ZITADEL_CLIENT_SECRET',
  'SESSION_SECRET'
];

for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Missing required environment variable: ${key}`);
  }
}
```

--------------------------------

### Zitadel Session Provider

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Wraps the application to enable the useSession() hook in client components.

```typescript
<ZitadelProvider>
  {children}
</ZitadelProvider>
```

--------------------------------

### Wrap Component with Suspense

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Wraps the sign-in content in a Suspense boundary for proper async handling.

```typescript
export default function CustomSignInPage() {
  return (
    <Suspense fallback={<div>Loading…</div>}>
      <SignInContent />
    </Suspense>
  );
}
```

--------------------------------

### Define Requested OAuth Scopes

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/types.md

List of standard and ZITADEL-specific scopes used to request claims.

```typescript
'openid'
'profile'
'email'
'offline_access'
'urn:zitadel:iam:user:metadata'
'urn:zitadel:iam:user:resourceowner'
'urn:zitadel:iam:org:projects:roles'
```

--------------------------------

### Use getSession in Server Components

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Retrieves the session in a server component and redirects to sign-in if unauthenticated.

```typescript
import { getSession } from '@/lib/auth';

export default async function ProfilePage() {
  const session = await getSession();
  
  if (!session) {
    redirect(signInUrl({ redirectTo: '/profile' }));
  }
  
  return <div>Welcome {session.idToken}</div>;
}
```

--------------------------------

### Parse Session Duration

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Shows how the session duration is parsed from environment variables with a fallback default.

```typescript
maxAge: Number(process.env.SESSION_DURATION) || 3600
```

--------------------------------

### Usage of signOutUrl

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-auth.md

Generates the local sign-out endpoint URL.

```typescript
import { signOutUrl } from '@/lib/auth';

const logoutEndpoint = signOutUrl();
// Returns: "/api/auth/signout"
```

--------------------------------

### XSS Attack Prevention with CSP

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Illustrates how a strict CSP policy blocks inline scripts and event handlers that would otherwise execute in an XSS attack.

```html
<!-- Without CSP -->
<input onload="alert('XSS')" />  <!-- Executes -->

<!-- With CSP: default-src 'self' -->
<input onload="alert('XSS')" />  <!-- Blocked -->

<!-- Inline script blocked unless 'unsafe-inline' added -->
<script>alert('XSS')</script>     <!-- Blocked by default -->
```

--------------------------------

### Configure X-Permitted-Cross-Domain-Policies

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Prevents cross-domain policy files for legacy technologies like Flash or PDF.

```typescript
{
  key: 'X-Permitted-Cross-Domain-Policies',
  value: 'none',
}
```

--------------------------------

### Implement Session Callback

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/types.md

Shapes the session object by mapping JWT tokens.

```typescript
async session({ session, token }) {
  session.idToken = token.idToken;
  session.accessToken = token.accessToken;
  // refreshToken NOT included (server-side only)
  return session;
}
```

--------------------------------

### Set ZITADEL Client ID

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Configures the OAuth 2.0 client identifier obtained from the ZITADEL Console.

```bash
ZITADEL_CLIENT_ID="12345678901234567890"
```

--------------------------------

### Loading Fallback State

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Displays a loading message while authentication providers are being fetched.

```typescript
if (!providers) {
  return (
    <main className="grid flex-1 place-items-center bg-white px-6 py-24">
      <p className="text-gray-600">Loading…</p>
    </main>
  );
}
```

--------------------------------

### Use SignOutButton Component

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/api-components.md

Shows the implementation of the SignOutButton within the Header component.

```tsx
import { SignOutButton } from '@/components/SignOutButton';

<Header isAuthenticated={true}>
  <SignOutButton />
</Header>
```

--------------------------------

### Generate Session Secret

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Generates a secure 32-byte hexadecimal string for session signing.

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

--------------------------------

### Protect Profile Route

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Verify the user session and redirect unauthenticated users to the login page with a callback URL.

```typescript
const session = await getSession();

if (!session) {
  redirect(signInUrl({ redirectTo: '/profile' }));
}
```

--------------------------------

### Set Session Duration

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/configuration.md

Configures the inactivity timeout for user sessions in seconds.

```bash
SESSION_DURATION=7200
```

--------------------------------

### Configure Security Headers in Next.js

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/security-headers.md

Defines security headers within the next.config.ts file to be applied across all application routes.

```typescript
const nextConfig: NextConfig = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'X-Frame-Options',
            value: 'DENY',
          },
          {
            key: 'X-Content-Type-Options',
            value: 'nosniff',
          },
          {
            key: 'Content-Security-Policy',
            value: "default-src 'self'; script-src 'self' 'unsafe-eval' 'unsafe-inline';",
          },
          {
            key: 'Referrer-Policy',
            value: 'strict-origin-when-cross-origin',
          },
        ],
      },
    ];
  },
};
```

--------------------------------

### Body Layout Styling

Source: https://github.com/zitadel/example-auth-nextjs/blob/main/_autodocs/page-routes.md

Applies flexbox layout and background styling to the body element.

```html
<body className="flex min-h-screen flex-col bg-gray-50">
```
Tokens:
Raw