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 using Auth.js. Users start on a public landing page and click a login button to authenticate through Zitadel's authorization endpoint 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 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. Users start on a public landing page and click a login button to authenticate through Zitadel's authorization endpoint. It demonstrates token refresh that performs federated single sign-out, terminating both the local session and the remote Zitadel session through the end-session endpoint. It demonstrates token refresh capabilities using refresh tokens with the offline_access scope that performs federated single sign-out, terminating both the local session and the remote Zitadel session through the end-session endpoint. It demonstrates token refresh capabilities using refresh tokens with the offline_access scope, allowing users to maintain authenticated sessions without repeated logins. The example also shows how to request additional OIDC scopes that performs federated single sign-out, terminating both the local session and the remote Zitadel session through the end-session endpoint. It demonstrates token refresh capabilities using refresh tokens with the offline_access scope like profile, email, and Zitadel-specific scopes for user metadata that performs federated single sign-out, terminating both the local session and the remote Zitadel session through the end-session endpoint. It demonstrates token refresh capabilities using refresh tokens with the offline_access scope, allowing users to maintain authenticated sessions without repeated logins. The example also shows how to request additional OIDC scopes like profile, email, and Zitadel-specific scopes for user metadata, organization information that performs federated single sign-out, terminating both the local session and the remote Zitadel session through the end-session endpoint. It demonstrates token refresh capabilities using refresh tokens with the offline_access scope, allowing users to maintain authenticated sessions without repeated logins. The example also shows how to request additional OIDC scopes like profile, email, and Zitadel-specific scopes for user metadata, organization information, and role assignments that performs federated single sign-out, terminating both the local session and the remote Zitadel session through the end-session endpoint. It demonstrates token refresh capabilities using refresh tokens with the offline_access scope, allowing users to maintain authenticated sessions without repeated logins. The example also shows how to request additional OIDC scopes like profile, email, and Zitadel-specific scopes for user metadata, organization information, and role assignments.

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:4321/api/auth/callback for development)
Configure post-logout redirect URIs (e.g., http://localhost:4321/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 .env file based on .env.example and configure it with the values from your Zitadel application. Use these environment variable names exactly as shown:
```
PORT=4321
SESSION_DURATION=3600
SESSION_SECRET=your-very-secret-and-strong-session-key
ZITADEL_DOMAIN=https://your-zitadel-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id_from_console
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:4321/auth/callback
ZITADEL_POST_LOGOUT_URL=http://localhost:4321/api/auth/logout/callback
AUTH_TRUST_HOST=true
NEXTAUTH_URL=http://localhost:4321
```
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 with npm run dev to verify the authentication flow end-to-end at http://localhost:4321.