initial commit

Author: mridang

README.md

@@ -1,20 +1,20 @@
-# Express.js with ZITADEL
+# Express with ZITADEL
 
-[Express.js](https://expressjs.com/) is a popular and powerful framework for building the backend of web applications. In a traditional setup, often called a "Backend for Frontend" (BFF), your Express server manages both your application's logic and renders the web pages that users see.
+[Express](https://expressjs.com/) is a fast, unopinionated, minimalist web framework for Node.js. It provides a robust set of features for web and mobile applications, making it one of the most popular choices for building server-side applications. In a modern setup, your Express application manages both your application's frontend and backend logic through server-side routes and middleware.
 
-To secure such an application, you need a reliable way to handle user logins. For the Express ecosystem, [Passport.js](http://www.passportjs.org/) is the standard and recommended middleware for authentication. Think of it as a flexible security guard for your app. This guide demonstrates how to use Passport.js with an Express v5 application to implement a secure login with ZITADEL.
+To secure such an application, you need a reliable way to handle user logins. For the Express ecosystem, [Auth.js](https://authjs.dev/) (formerly NextAuth.js) is the standard and recommended library for authentication. Think of it as a flexible security guard for your app. This guide demonstrates how to use Auth.js with an Express application to implement a secure login with ZITADEL.
 
 We'll be using the **OpenID Connect (OIDC)** protocol with the **Authorization Code Flow + PKCE**. This is the industry-best practice for security, ensuring that the login process is safe from start to finish. You can learn more in our [guide to OAuth 2.0 recommended flows](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows).
 
-This example uses **Passport.js**, the standard for Express.js authentication. While ZITADEL doesn't offer a specific SDK, Passport.js is highly modular. It works with a "strategy" that handles the communication with ZITADEL. Under the hood, this example uses the powerful [`openid-client`](https://github.com/panva/node-openid-client) library to manage the secure OIDC PKCE flow.
+This example uses **Auth.js**, the standard for Express authentication. While ZITADEL doesn't offer a specific SDK, Auth.js is highly modular. It works with a "provider" that handles the communication with ZITADEL. Under the hood, this example uses the powerful OIDC standard to manage the secure PKCE flow.
 
 Check out our Example Application to see it in action.
 
 ## Example Application
 
-The example repository includes a complete Express.js application, ready to run, that demonstrates how to integrate ZITADEL for user authentication.
+The example repository includes a complete Express application, ready to run, that demonstrates how to integrate ZITADEL for user authentication.
 
-This example application showcases a typical web app authentication pattern: users start on a public landing page, click a login button to authenticate with ZITADEL, and are then redirected to a protected profile page displaying their user information. The app also includes secure logout functionality that clears the session and redirects users back to ZITADEL's logout endpoint. All protected routes are automatically secured using Passport.js middleware, ensuring only authenticated users can access sensitive areas of your application.
+This example application showcases a typical web app authentication pattern: users start on a public landing page, click a login button to authenticate with ZITADEL, and are then redirected to a protected profile page displaying their user information. The app also includes secure logout functionality that clears the session and redirects users back to ZITADEL's logout endpoint. All protected routes are automatically secured using Auth.js middleware and session management, ensuring only authenticated users can access sensitive areas of your application.
 
 ### Prerequisites
 
@@ -23,6 +23,7 @@ Before you begin, ensure you have the following:
 #### System Requirements
 
 - Node.js (v20 or later is recommended)
+- npm, yarn, or pnpm package manager
 
 #### Account Setup
 
@@ -31,13 +32,13 @@ You'll need a ZITADEL account and application configured. Follow the [ZITADEL do
 > **Important:** Configure the following URLs in your ZITADEL application settings:
 >
 > - **Redirect URIs:** Add `http://localhost:3000/auth/callback` (for development)
-> - **Post Logout Redirect URIs:** Add `http://localhost:3000` (for development)
+> - **Post Logout Redirect URIs:** Add `http://localhost:3000/auth/logout/callback` (for development)
 >
 > These URLs must exactly match what your Express application uses. For production, add your production URLs.
 
 ### Configuration
 
-To run the application, you first need to copy the `.env.example` file to a new file named `.env` and fill in your ZITADEL application credentials.
+To run the application, you first need to copy the `.env.example` file to a new file named `.env.local` and fill in your ZITADEL application credentials.
 
 ```dotenv
 # Port number where your Express server will listen for incoming HTTP requests.
@@ -63,21 +64,25 @@ ZITADEL_DOMAIN="https://your-zitadel-domain"
 # request.
 ZITADEL_CLIENT_ID="your-client-id"
 
-# Client Secret for confidential applications. Leave empty for public clients.
-# Only required if you selected "Confidential" when creating your ZITADEL app.
-ZITADEL_CLIENT_SECRET=""
+# While the Authorization Code Flow with PKCE for public clients
+# does not strictly require a client secret for OIDC specification compliance,
+# AuthJS 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/auth/callback"
 
 # 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"
+ZITADEL_POST_LOGOUT_URL="http://localhost:3000/auth/logout/callback"
 
-# Internal redirect destination after successful login. This is where your app
-# sends users after ZITADEL confirms authentication. Defaults to "/profile".
-ZITADEL_POST_LOGIN_URL="/profile"
+# Auth.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"
 ```
 
 ### Installation and Running
@@ -86,9 +91,9 @@ Follow these steps to get the application running:
 
 ```bash
 # 1. Clone the repository
-git clone [email protected]:zitadel/example-auth-expressjs.git
+git clone [email protected]:zitadel/example-auth-express.git
 
-cd example-auth-expressjs
+cd example-auth-express
 
 # 2. Install the project dependencies
 npm install
@@ -99,11 +104,42 @@ npm run dev
 
 The application will now be running at `http://localhost:3000`.
 
+## Key Features
+
+### PKCE Authentication Flow
+
+The application implements the secure Authorization Code Flow with PKCE (Proof Key for Code Exchange), which is the recommended approach for modern web applications.
+
+### Session Management
+
+Built-in session management with Auth.js handles user authentication state across your application, with automatic token refresh and secure session storage.
+
+### Route Protection
+
+Protected routes automatically redirect unauthenticated users to the login flow, ensuring sensitive areas of your application remain secure.
+
+### Logout Flow
+
+Complete logout implementation that properly terminates both the local session and the ZITADEL session, with proper redirect handling.
+
 ## TODOs
 
-### 1. Security headers (Helmet)
+### 1. Security headers (Express middleware)
+
+**Not enabled.** Consider adding security headers middleware in your Express application:
 
-**Not enabled yet.** Add [`helmet`](https://www.npmjs.com/package/helmet) before production:
+```javascript
+import helmet from 'helmet';
+
+app.use(helmet({
+  contentSecurityPolicy: {
+    directives: {
+      defaultSrc: ["'self'"],
+      scriptSrc: ["'self'", "'unsafe-eval'", "'unsafe-inline'"],
+    },
+  },
+}));
+```
 
 At minimum, configure:
 
@@ -112,21 +148,8 @@ At minimum, configure:
 - `Referrer-Policy`
 - `Permissions-Policy`
 
-### 2. No CSRF protection yet
-
-State‑changing routes (logout, future POST/PUT/DELETE) are currently vulnerable.
-Add CSRF protection using [`csrf-csrf`](https://www.npmjs.com/package/csrf-csrf)
-
-Remember to:
-
-- Make logout a **POST**.
-- Embed the CSRF token in a hidden form field or send it via `X-CSRF-Token` header.
-- Set cookies with `SameSite=Lax` or stricter.
-
-> OWASP reference: <https://owasp.org/www-community/attacks/csrf>
-
 ## Resources
 
-- **Express.js Documentation:** <https://expressjs.com/>
-- **Passport.js Documentation:** <http://www.passportjs.org/>
-- **Express Session Middleware:** <https://expressjs.com/en/resources/middleware/session.html>
+- **Express Documentation:** <https://expressjs.com/>
+- **Auth.js Documentation:** <https://authjs.dev/>
+- **ZITADEL Documentation:** <https://zitadel.com/docs>

knip.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  ignoreDependencies: ['handlebars'],
+};