Express.js

Overview

Express.js is a fast, unopinionated, minimalist web framework for Node.js that provides a robust set of features for building web and mobile applications. This example demonstrates how to integrate Zitadel using the OAuth 2.0 PKCE flow to authenticate users securely and maintain sessions across your Express application.

Auth library

This example uses @auth/express (GitHub), the Express.js adapter for Auth.js. This library implements the OpenID Connect (OIDC) protocol with PKCE support, manages token exchange, performs automatic token refresh, and provides session management with secure cookie-based storage.

What this example demonstrates

This Express.js example provides a complete authentication implementation using Zitadel as the identity provider. The application starts with a public landing page featuring a login button that initiates the PKCE authentication flow. When users click login, @auth/express generates a cryptographic code verifier and challenge, then redirects to Zitadel's authorization endpoint. After successful authentication at Zitadel, users return to the application's callback URL where the authorization code is exchanged for access tokens and an ID token.

The example includes protected routes using Express middleware that automatically verify session state and redirect unauthenticated users to the sign-in page. Authenticated users can access their profile page displaying user information including email, name, and custom metadata claims that automatically verify session state and redirect unauthenticated users to the sign-in page. Authenticated users can access their profile page displaying user information including email, name, and custom metadata claims from Zitadel. The application maintains long-lived sessions through automatic token refresh that automatically verify session state and redirect unauthenticated users to the sign-in page. Authenticated users can access their profile page displaying user information including email, name, and custom metadata claims from Zitadel. The application maintains long-lived sessions through automatic token refresh using refresh tokens, ensuring users remain authenticated without repeated logins.

Sign-out functionality implements federated logout by redirecting to Zitadel's end-session endpoint with the ID token hint, terminating both the local session and the Zitadel session. The logout flow includes CSRF protection through state parameter validation, and users are redirected to a success page after logout completion. All authentication flows use secure HTTP-only cookies for session storage and implement proper security headers.

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.local file 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_DURATION=3600
ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id_from_console
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-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 from the PKCE setup guide)
- 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'))")
- The redirect URI you configured in the PKCE setup (must match exactly)
- A strong session secret (generate using: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
Install dependencies using npm and start the development server:
bash
```
npm install
npm run dev
```

The application will be running at http://localhost:3000.