mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-01 11:52:15 +00:00
96f9bbc044
### **Restructure Docs Navigation & Consolidate Core Concepts**
**Summary**
This PR refactors the documentation navigation to follow a clearer
**User Journey** and consolidates fragmented pages to reduce redundancy.
**Key Changes**
* **Sidebar:**
* Replaced the legacy resource-based structure with user-journey-focused
categories.
**Proposed Structure:**
```
Get Started
├─ Overview
│ └─ Guides Overview (Brief intro to docs, persona-aligned: "Get auth working in minutes for your B2B app.")
├─ Quickstart Guide
│ └─ Quickstart (Step-by-step: Sign up, spin up instance, connect app, log in – mirrors brand's 4-step guide.)
├─ Authenticate Users
│ ├─ Login with ZITADEL (OIDC)
│ ├─ Get ID / Access Token
│ └─ Logout
├─ Examples & SDKs
│ ├─ SPA / Frontend
│ ├─ Web Applications
│ ├─ APIs / Backend Services
│ ├─ Hybrid / Full-Stack
│ └─ Sample Applications (Include community-contributed examples for openness.)
├─ Key Concepts
│ ├─ Instances, Orgs, Projects, Apps
│ ├─ Policies (Intro)
│ └─ Users & Roles
└─ Use Cases
├─ B2B Integration (Tailored to multi-tenant enterprise needs.)
├─ B2C Login
├─ Multi-Tenant / SaaS
├─ Branded Login & White-Label
└─ Machine-to-Machine (M2M)
Configure Identity & Policies
├─ Identity Providers
│ ├─ External IDPs (e.g., Google, Azure)
│ └─ Custom Providers
├─ Policies
│ ├─ Password Policies
│ ├─ Lockout Policies
│ └─ Privacy Policies
├─ Roles & Permissions
│ ├─ RBAC Setup
│ └─ Custom Roles
└─ Compliance & Security
├─ Audits & Logs
└─ Certifications (Highlight trust through openness.)
Integrate & Authenticate
├─ OIDC & OAuth Flows
├─ API Access
│ ├─ gRPC APIs
│ └─ REST APIs
├─ SDKs
│ ├─ Go
│ ├─ JavaScript/TypeScript
│ ├─ Python
│ └─ Others (Link to community SDKs.)
└─ External Integrations
├─ SAML
├─ LDAP
└─ Webhooks
Test & Debug
├─ Testing Tools
│ ├─ Console Testing
│ └─ API Playground
├─ Common Issues
│ ├─ Token Errors
│ └─ Integration Failures
└─ Debugging Guides
├─ Logs & Monitoring
└─ Error Codes Reference
Deploy & Operate
├─ Deployment Options
│ ├─ Cloud (ZITADEL Cloud)
│ ├─ Self-Hosted (Linux, MacOS)
│ ├─ Docker Compose
│ └─ Kubernetes
├─ Configuration
│ ├─ Environment Variables
│ └─ Advanced Settings
├─ Scaling & Performance
│ ├─ High Availability
│ └─ Backup & Restore
└─ Monitoring & Maintenance
├─ Metrics
└─ Upgrades
Architecture & Concepts
├─ System Architecture
│ ├─ Core Components
│ └─ Data Flow Diagrams (Expressive visuals per brand.)
├─ Principles
│ ├─ Multi-Tenancy
│ └─ Open Standards (OIDC, SAML)
└─ Advanced Topics
├─ Customization
└─ Extensibility (Open-source contributions.)
Product, Releases & Support
├─ Product Features
│ ├─ Roadmap (Public, for transparency.)
│ └─ Pricing & Tiers
├─ Releases
│ ├─ Changelog
│ └─ Upgrade Guides
└─ Support Resources
├─ Community (Discord, GitHub – for community-led growth.)
├─ FAQ
├─ Contact Support
└─ Contribute (Encourage feedback/shaping the product.)
```
**Content Consolidation:**
* Merged separate "Concept" and "Console Guide" files into single,
comprehensive **Overview** pages for core resources:
* `Organizations`, `Projects`, `Applications`, `Users`, `Console`, and
`Actions`.
```
concepts/structure/organizations + guides/manage/console/organizations -> guides/manage/console/organizations-overview
concepts/structure/projects + guides/manage/console/projects -> guides/manage/console/projects-overview
concepts/structure/applications + guides/manage/console/applications -> guides/manage/console/applications-overview
concepts/structure/users + guides/manage/console/users -> guides/manage/console/users-overview
guides/manage/console/actions + apis/actions/introduction -> guides/manage/console/actions-overview
concepts/features/console + guides/manage/console/overview -> guides/manage/console/console-overview
```
**Redirects (`vercel.json`):**
* Added permanent redirects for all the 6 legacy files mentioned above
**No files were deleted**
---------
Co-authored-by: Florian Forster <[email protected]>
90 lines
6.5 KiB
Plaintext
90 lines
6.5 KiB
Plaintext
---
|
|
title: SvelteKit
|
|
sidebar_label: SvelteKit
|
|
framework_url: https://kit.svelte.dev
|
|
auth_library: "@auth/core"
|
|
auth_library_url: https://www.npmjs.com/package/@auth/core
|
|
example_repo: https://github.com/zitadel/example-auth-sveltekit
|
|
auth_flow: pkce
|
|
status: stable
|
|
---
|
|
|
|
## Overview
|
|
|
|
[SvelteKit](https://kit.svelte.dev) is a framework for building web applications with flexible filesystem-based routing and a unified approach to server-side and client-side logic. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](/docs/concepts/pkce)** to authenticate users securely and maintain sessions across your application.
|
|
|
|
#### Auth library
|
|
|
|
This example uses **[@auth/sveltekit](https://www.npmjs.com/package/@auth/sveltekit)**, the SvelteKit integration of **[@auth/core](https://www.npmjs.com/package/@auth/core)** (formerly NextAuth.js). Auth.js provides a complete authentication solution that handles the [OpenID Connect](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manages [PKCE](/docs/concepts/pkce) code generation and verification, performs secure token exchange, and provides session management utilities across your SvelteKit application.
|
|
|
|
---
|
|
|
|
## What this example demonstrates
|
|
|
|
This example provides a complete authentication implementation showing how to secure a [SvelteKit](https://kit.svelte.dev) application with [Zitadel](https://zitadel.com/docs). Users start on a public landing page and click a login button to authenticate through Zitadel's [authorization server](https://zitadel.com/docs/apis/openidoauth/endpoints) using the **[PKCE flow](/docs/concepts/pkce)**. After successful authentication, they're redirected to a protected profile page that displays their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).
|
|
|
|
The example demonstrates route protection using [SvelteKit's server-side load functions](https://kit.svelte.dev/docs/load) that verify [session state](https://zitadel.com/docs/concepts/tokens) before rendering protected pages. Authentication state is managed through [@auth/sveltekit hooks](https://www.npmjs.com/package/@auth/sveltekit), which integrate with [SvelteKit's hooks system](https://kit.svelte.dev/docs/hooks) to provide session data throughout your application. The implementation includes automatic [access token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate.
|
|
|
|
The logout flow implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** with proper CSRF protection, terminating both the local application session and the Zitadel session before redirecting users back to your application. Custom error pages provide user-friendly messages for authentication failures, and the example includes comprehensive security headers configured through [SvelteKit's hooks](https://kit.svelte.dev/docs/hooks).
|
|
|
|
---
|
|
|
|
## Getting started
|
|
|
|
### Prerequisites
|
|
|
|
Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to:
|
|
|
|
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview)
|
|
2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce)
|
|
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
|
|
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
|
|
5. Copy your **Client ID** for use in the next steps
|
|
|
|
> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview) 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:
|
|
|
|
1. Clone the [repository](https://github.com/zitadel/example-auth-sveltekit).
|
|
2. Create a `.env.local` file in the project root and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/console-overview). **Use these exact environment variable names:**
|
|
```
|
|
SESSION_SECRET=your-very-secret-and-strong-session-key
|
|
SESSION_DURATION=3600
|
|
ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
|
|
ZITADEL_CLIENT_ID=your_client_id_from_console
|
|
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
|
|
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
|
|
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
|
|
NEXTAUTH_URL=http://localhost:3000
|
|
```
|
|
Replace these values with:
|
|
- A secure random string for `SESSION_SECRET` (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
|
|
- Your actual Zitadel instance URL for `ZITADEL_DOMAIN` (the issuer URL)
|
|
- The **Client ID** you copied when creating the application
|
|
- A random string for `ZITADEL_CLIENT_SECRET` (Auth.js requires this even though PKCE doesn't strictly need it)
|
|
- The **redirect URI** you configured in the PKCE setup (must match exactly)
|
|
- The **post-logout redirect URI** you configured
|
|
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
4. Navigate to `http://localhost:3000` to verify the authentication flow end-to-end.
|
|
|
|
---
|
|
|
|
## Learn more and resources
|
|
|
|
* **Zitadel documentation:** [https://zitadel.com/docs](https://zitadel.com/docs)
|
|
* **PKCE concept:** [/docs/concepts/pkce](/docs/concepts/pkce)
|
|
* **PKCE application setup:** [/docs/guides/integrate/login/oidc/pkce-setup](/docs/guides/integrate/login/oidc/pkce-setup)
|
|
* **Federated logout:** [https://zitadel.com/docs/guides/integrate/login/oidc/logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
|
|
* **OIDC integration guide:** [https://zitadel.com/docs/guides/integrate/login/oidc/](https://zitadel.com/docs/guides/integrate/login/oidc/)
|
|
* **SvelteKit documentation:** [https://kit.svelte.dev](https://kit.svelte.dev)
|
|
* **Auth.js (SvelteKit):** [https://www.npmjs.com/package/@auth/sveltekit](https://www.npmjs.com/package/@auth/sveltekit)
|
|
* **Auth.js Core:** [https://www.npmjs.com/package/@auth/core](https://www.npmjs.com/package/@auth/core)
|
|
* **Example repository:** [https://github.com/zitadel/example-auth-sveltekit](https://github.com/zitadel/example-auth-sveltekit)
|
|
* **All framework examples:** [/docs/examples](/docs/examples)
|