Skip to main content

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. 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 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:4321/api/auth/callback for development)
  4. Configure post-logout redirect URIs (e.g., http://localhost:4321/api/auth/logout/callback)
  5. Copy your Client ID from the application details

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

  1. Clone the repository.
  2. 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)
  3. 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.

Learn more and resources​

Was this page useful?