NestJS

Overview

NestJS is a progressive Node.js framework for building efficient, reliable, and scalable server-side applications using TypeScript. This example demonstrates how to integrate Zitadel using the OAuth 2.0 PKCE flow to authenticate users securely and maintain sessions across your NestJS application.

Auth library

This example uses @auth/core, the core authentication library powering Auth.js, which implements the OpenID Connect (OIDC) flow, manages PKCE, performs token exchange, and exposes helpers for session state. The example integrates this through the @mridang/nestjs-auth NestJS module, which provides decorators, guards, and middleware for seamless authentication within the NestJS ecosystem.

What this example demonstrates

This example implements a complete authentication flow using PKCE with Zitadel as the identity provider. Users begin on a public landing page and click a login button to authenticate through Zitadel's authorization server. After successful authentication, they're redirected to a protected profile page displaying their user information retrieved from the ID token with Zitadel as the identity provider. Users begin on a public landing page and click a login button to authenticate through Zitadel's authorization server. After successful authentication, they're redirected to a protected profile page displaying their user information retrieved from the ID token and access token.

The application leverages NestJS controllers to handle authentication routes and @mridang/nestjs-auth guards to handle authentication routes and @mridang/nestjs-auth guards to protect routes requiring authentication. Session management to handle authentication routes and @mridang/nestjs-auth guards to protect routes requiring authentication. Session management is handled through encrypted JWT-based sessions to handle authentication routes and @mridang/nestjs-auth guards to protect routes requiring authentication. Session management is handled through encrypted JWT-based sessions stored in secure, HTTP-only cookies. The example includes automatic token refresh to handle authentication routes and @mridang/nestjs-auth guards to protect routes requiring authentication. Session management is handled through encrypted JWT-based sessions stored in secure, HTTP-only cookies. The example includes automatic token refresh functionality using refresh tokens, ensuring users maintain their sessions without interruption when access tokens expire.

The logout implementation demonstrates federated logout by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. CSRF protection by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. CSRF protection during logout is achieved through a state parameter validated in the callback. The example also showcases accessing Zitadel's UserInfo endpoint to fetch real-time user data, including custom claims with Zitadel as the identity provider. Users begin on a public landing page and click a login button to authenticate through Zitadel's authorization server. After successful authentication, they're redirected to a protected profile page displaying their user information retrieved from the ID token, roles by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. CSRF protection during logout is achieved through a state parameter validated in the callback. The example also showcases accessing Zitadel's UserInfo endpoint to fetch real-time user data, including custom claims, roles, and organization membership.

All protected routes are secured using the @mridang/nestjs-auth global guard, with the @Public() decorator marking routes that don't require authentication. The application uses Handlebars templates for server-side rendering and Tailwind CSS for styling, providing a complete reference implementation for NestJS developers.

Getting started

Prerequisites

Before running this example, you need to create and configure a PKCE application in the ZITADEL Management Console. Follow the PKCE application setup guide to:

Create a new Web application in your Zitadel project
Configure it to use the PKCE authentication method
Set up your redirect URIs (e.g., http://localhost:3000/auth/callback/zitadel for development)
Configure post-logout redirect URIs (e.g., http://localhost:3000/auth/logout/callback)
Copy your Client ID for use in the next steps

Note: Make sure to enable Dev Mode in the ZITADEL Management Console if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.

Run the example

Once you have your Zitadel application configured:

Clone the repository.
Create a .env file in the project root and configure it with the values from your Zitadel application. Use the exact environment variable names from the repository:
```
NODE_ENV=development
PORT=3000

SESSION_SECRET=your-very-secret-and-strong-session-key
SESSION_SALT=your-cryptographic-salt
SESSION_DURATION=3600

ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id_from_console
ZITADEL_CLIENT_SECRET=your_randomly_generated_secret
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback/zitadel
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual Zitadel instance URL (the Issuer)
- The Client ID you copied when creating the application
- A randomly generated Client Secret (generate using: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
- A secure Session Secret (generate using the same command)
- A cryptographic Session Salt for cookie encryption
- The redirect URI you configured in the PKCE setup (must match exactly)
- The post-logout redirect URI for the logout callback
Install dependencies using npm and start the development server:
bash
```
npm install
npm run dev
```
The application will be running at http://localhost:3000. Visit the URL to verify the authentication flow end-to-end.