SolidStart

Overview

SolidStart is a full-stack web framework built on top of SolidJS that enables you to create performant web applications with a modern development experience. This example demonstrates how to integrate Zitadel using the OAuth 2.0 PKCE flow to authenticate users securely and maintain sessions across the app.

Auth library

This example uses @auth/solid-start, the SolidStart adapter for Auth.js, which builds on @auth/core. Auth.js implements the OpenID Connect (OIDC) flow, manages PKCE, performs token exchange, and exposes helpers for session state. The example also uses openid-client (GitHub) for manual token refresh operations and logout URL construction.

What this example demonstrates

This example shows a complete authentication implementation using SolidStart with Zitadel. Users start on a public landing page and click a login button to authenticate with Zitadel using the secure PKCE flow. The Auth.js library handles the OAuth 2.0 authorization code exchange and manages secure session storage using encrypted JWT tokens. After successful authentication, users are redirected to a protected profile page displaying their user information including OIDC claims like name, email, and custom Zitadel metadata.

The application implements automatic token refresh to maintain long-lived sessions without requiring users to re-authenticate. When an access token expires, the refresh logic seamlessly exchanges the refresh token for new tokens in the background. Route protection is implemented using SolidStart's server functions, ensuring only authenticated users can access sensitive areas. The logout flow implements federated logout with CSRF protection using state parameters, properly terminating both the local session and the Zitadel session before redirecting users back to the application.

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:

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/zitadel for development)
Configure post-logout redirect URIs (e.g., http://localhost:3000/api/auth/logout/callback)
Copy your Client ID for use in the next steps

Note: Make sure to enable Dev Mode in the Zitadel 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 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-zitadel-domain"
ZITADEL_CLIENT_ID="your-client-id"
ZITADEL_CLIENT_SECRET="your-randomly-generated-client-secret"
ZITADEL_CALLBACK_URL="http://localhost:3000/api/auth/callback/zitadel"
ZITADEL_POST_LOGIN_URL="/profile"
ZITADEL_POST_LOGOUT_URL="http://localhost:3000/api/auth/logout/callback"
NEXTAUTH_URL="http://localhost:3000"
```
Replace these values with:
- Your actual Zitadel instance URL (the Issuer)
- The Client ID you copied when creating the application
- The redirect URIs you configured in the PKCE setup (must match exactly)
- A secure random string for SESSION_SECRET (generate using: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
- A secure random string for ZITADEL_CLIENT_SECRET for Auth.js configuration compatibility
Install dependencies using npm and start the development server to verify the authentication flow end-to-end:
bash
```
npm install
npm run dev
```