Hono

Overview

Hono is a small, simple, and ultra-fast web framework for the Edges that works on Cloudflare Workers, Fastly Compute, Deno, Bun, Vercel, Netlify, AWS Lambda, Lambda@Edge, and Node.js. This example demonstrates how to integrate Zitadel using the OAuth 2.0 PKCE flow to authenticate users securely and maintain sessions across your Hono application.

Auth library

This example uses Auth.js (formerly NextAuth.js), the standard authentication library for modern web frameworks. Auth.js implements the OpenID Connect (OIDC) protocol with PKCE, performs secure token exchange, and provides session management helpers. The integration uses @hono/auth-js, the official Hono adapter for Auth.js, along with @auth/core which handles the core OIDC flows and the Zitadel provider.

What this example demonstrates

This example showcases a complete web application authentication pattern with Hono and Zitadel. Users start on a public landing page, initiate authentication with Zitadel using the secure PKCE flow, and are redirected to a protected profile page displaying their user information after successful authentication. The application demonstrates several key features including sign-in with authorization code flow + PKCE, OAuth callback handling with secure session storage using JWT strategy, route protection through authentication middleware that guards sensitive pages, automatic token refresh to maintain long-lived sessions without requiring re-authentication, access to user profile information including OIDC standard claims and Zitadel-specific claims such as organization roles and metadata, and secure sign-out with federated logout that terminates both the local session and the Zitadel session through the end-session endpoint.

The implementation uses Handlebars templates for server-side rendering, @hono/node-server for running on Node.js, secure HTTP-only cookies for session management, and CSRF protection through Auth.js built-in tokens. The authentication flow follows OAuth 2.0 best practices with Proof Key for Code Exchange to prevent authorization code interception attacks.

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 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 (copy from .env.example) 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=
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 (the Issuer from your instance settings)
- The Client ID you copied when creating the application in the PKCE setup
- The redirect URI you configured in the PKCE setup (must match exactly)
- The post-logout redirect URI for handling logout callbacks
- A strong random session secret (generate using: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")

Note: While PKCE doesn't require a client secret for public clients, Auth.js requires a value for internal configuration. You can leave ZITADEL_CLIENT_SECRET empty or provide a random string.

Install dependencies using npm and start the development server:
```
npm install
npm run dev
```

The application will be running at http://localhost:3000. Visit the homepage to test the authentication flow.