apps/docs/content/sdk-examples/astro.mdx
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.
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.
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.
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:
http://localhost:3000/api/auth/callback/zitadel for development)http://localhost:3000/api/auth/logout/callback)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.
Once you have your Zitadel application configured:
.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=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
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"npm install, then start the development server with npm run dev to verify the authentication flow end-to-end at http://localhost:3000.