Skip to main content

Fastify

Overview​

Fastify is a fast and low overhead web framework for Node.js, designed for building efficient server-side applications. This example demonstrates how to integrate ZITADEL using the OAuth 2.0 PKCE flow to authenticate users securely and maintain sessions across your application.

Auth library​

This example uses @mridang/fastify-auth, a Fastify plugin that wraps @auth/core (formerly Auth.js). The underlying @auth/core library implements the OpenID Connect (OIDC) flow, manages PKCE, performs secure token exchange, and provides session management helpers. This integration leverages the @auth/core/providers/zitadel provider specifically designed for ZITADEL authentication.

What this example demonstrates​

This example shows a complete authentication implementation using Fastify with server-side rendering via @fastify/view and Handlebars templates. The application implements secure user authentication through ZITADEL using the industry-standard PKCE flow, which prevents authorization code interception attacks without requiring client secrets.

The example includes a custom sign-in page that initiates the OAuth 2.0 authentication flow, automatic callback handling with secure token exchange, and JWT-based session management with @fastify/cookie. Protected routes use the requireAuth middleware to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including OIDC claims and session metadata.

The application also demonstrates proper federated logout by terminating sessions both locally and with ZITADEL's end-session endpoint, complete with CSRF protection using state parameters. Additionally, it includes automatic token refresh using refresh tokens to maintain long-lived sessions without requiring users to re-authenticate. The example uses ZITADEL-specific scopes like urn:zitadel:iam:user:metadata and urn:zitadel:iam:org:projects:roles to access extended user attributes and role information for implementing role-based access control (RBAC).

Getting started​

Prerequisites​

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

  1. Create a new Web application in your ZITADEL project
  2. Configure it to use the PKCE authentication method
  3. Set up your redirect URIs (e.g., http://localhost:3000/auth/callback for development)
  4. Configure post-logout redirect URIs (e.g., http://localhost:3000)
  5. Copy your Client ID for use in the next steps
  6. Optionally enable refresh tokens in Token Settings for long-lived sessions

Note: Make sure to enable Dev Mode in the ZITADEL 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:

  1. Clone the repository.
  2. Create a .env file (copy from .env.example) and configure it with the values from your ZITADEL application. Use these exact environment variable names: 
    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=
    ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
    ZITADEL_POST_LOGIN_URL=/profile
    ZITADEL_POST_LOGOUT_URL=http://localhost:3000
    Replace these values with:
    • Your actual ZITADEL instance URL for ZITADEL_DOMAIN (the issuer)
    • The Client ID you copied when creating the application for ZITADEL_CLIENT_ID
    • The redirect URI you configured in the PKCE setup for ZITADEL_CALLBACK_URL (must match exactly)
    • The post-logout redirect URI for ZITADEL_POST_LOGOUT_URL
    • A strong random string for SESSION_SECRET (generate using: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
  3. Install dependencies using npm with npm install and start the development server with npm run dev to verify the authentication flow end-to-end.

Learn more and resources​

Was this page useful?