Astro | ZITADEL Docs
Astro
Overview
Astro is a modern web framework that delivers lightning-fast performance with server-first architecture and seamless client-side hydration. This example demonstrates how to integrate Zitadel authentication using the OAuth 2.0 PKCE flow to secure your Astro application with professional identity management.
Auth library
This example uses Auth.js (specifically the @auth/core package and auth-astro adapter), a comprehensive authentication library that implements the OpenID Connect protocol. Auth.js handles PKCE code generation and verification, token exchange, session management, and automatic token refresh to maintain long-lived user sessions.
What this example demonstrates
This Astro application showcases a complete authentication workflow with Zitadel using Auth.js. Users start on a public landing page and click a login button to authenticate through Zitadel's authorization endpoint using the secure PKCE flow. After successful authentication, users are redirected to a protected profile page displaying their user information and claims retrieved from the ID token.
The example implements server-side session management with encrypted JWT tokens, ensuring secure authentication state across Astro's server-rendered pages. Protected routes automatically redirect unauthenticated users to the login flow using Astro's middleware, preventing unauthorized access to sensitive areas.
The application includes complete logout functionality that performs federated single sign-out, terminating both the local session and the remote Zitadel session through the end-session endpoint using Auth.js. It demonstrates token refresh capabilities using refresh tokens with the offline_access scope, allowing users to maintain authenticated sessions without repeated logins.
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/api/auth/callback/zitadelfor development) - Configure post-logout redirect URIs (e.g.,
http://localhost:3000/api/auth/logout/callback) - Copy your Client ID from the application details
Note: Make sure to enable Dev Mode in the ZITADEL Management Console if you're using HTTP URLs during local development. For production deployments, always use HTTPS URLs and disable Dev Mode.
Run the example
Once you have your Zitadel application configured:
- Clone the repository.
- Create a
.envfile based on.env.exampleand configure it with the values from your Zitadel application. Use these environment variable names exactly as shown:
PORT=3000
SESSION_DURATION=3600
SESSION_SECRET=your-very-secret-and-strong-session-key
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your_client_id_from_console
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/api/auth/callback/zitadel
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/api/auth/logout/callback
AUTH_TRUST_HOST=true
NEXTAUTH_URL=http://localhost:3000
Replace these values with:
- Your actual Zitadel instance URL (the ZITADEL_DOMAIN)
- The Client ID you copied when creating the application
- A randomly generated SESSION_SECRET using:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" - A randomly generated ZITADEL_CLIENT_SECRET (required by Auth.js even though PKCE doesn't require it)
- The redirect URIs you configured in the PKCE setup (must match exactly)
- Install dependencies using npm by running
npm install, then start the development server withnpm run devto verify the authentication flow end-to-end athttp://localhost:3000.