mirror of
https://github.com/zitadel/zitadel.git
synced 2025-12-29 09:29:55 +00:00
docs: added the docs for the missing examples (#11005)
<!-- Please inform yourself about the contribution guidelines on submitting a PR here: https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md#submit-a-pull-request-pr. Take note of how PR/commit titles should be written and replace the template texts in the sections below. Don't remove any of the sections. It is important that the commit history clearly shows what is changed and why. Important: By submitting a contribution you agree to the terms from our Licensing Policy as described here: https://github.com/zitadel/zitadel/blob/main/LICENSING.md#community-contributions. --> # Which Problems Are Solved Replace this example text with a concise list of problems that this PR solves. For example: - If the property XY is not given, the system crashes with a nil pointer exception. # How the Problems Are Solved Replace this example text with a concise list of changes that this PR introduces. For example: - Validates if property XY is given and throws an error if not # Additional Changes Replace this example text with a concise list of additional changes that this PR introduces, that are not directly solving the initial problem but are related. For example: - The docs explicitly describe that the property XY is mandatory - Adds missing translations for validations. # Additional Context Replace this example with links to related issues, discussions, discord threads, or other sources with more context. Use the Closing #issue syntax for issues that are resolved with this PR. - Closes #xxx - Discussion #xxx - Follow-up for PR #xxx - https://discord.com/channels/xxx/xxx
This commit is contained in:
Mridang Agarwalla
committed by
GitHub
GitHub
parent
02499f5fc4
commit
ee17b7a074
86
docs/docs/sdk-examples/astro.mdx
Normal file
86
docs/docs/sdk-examples/astro.mdx
Normal file
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: Astro
|
||||
sidebar_label: Astro
|
||||
framework_url: https://astro.build
|
||||
auth_library: "@auth/core"
|
||||
auth_library_url: https://www.npmjs.com/package/@auth/core
|
||||
example_repo: https://github.com/zitadel/example-auth-astro
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[Astro](https://astro.build) 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](https://zitadel.com/docs)** authentication using the **[OAuth 2.0 PKCE flow](/docs/concepts/pkce)** to secure your Astro application with professional identity management.
|
||||
|
||||
#### Auth library
|
||||
|
||||
This example uses **[Auth.js](https://authjs.dev)** (specifically the **[@auth/core](https://www.npmjs.com/package/@auth/core)** package and **[auth-astro](https://www.npmjs.com/package/auth-astro)** adapter), a comprehensive authentication library that implements the [OpenID Connect](https://openid.net/connect/) protocol. Auth.js handles [PKCE](/docs/concepts/pkce) code generation and verification, [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints), [session management](https://zitadel.com/docs/concepts/sessions), and automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived user sessions.
|
||||
|
||||
---
|
||||
|
||||
## What this example demonstrates
|
||||
|
||||
This Astro application showcases a complete authentication workflow with [Zitadel](https://zitadel.com/docs) using [Auth.js](https://authjs.dev). Users start on a public landing page and click a login button to authenticate through Zitadel's [authorization endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints) using the secure [PKCE flow](/docs/concepts/pkce). After successful authentication, users are redirected to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims) retrieved from the [ID token](https://zitadel.com/docs/concepts/tokens).
|
||||
|
||||
The example implements [server-side session management](https://zitadel.com/docs/concepts/sessions) with encrypted [JWT tokens](https://zitadel.com/docs/concepts/tokens), ensuring secure authentication state across Astro's [server-rendered pages](https://docs.astro.build/en/core-concepts/astro-pages/). Protected routes automatically redirect unauthenticated users to the login flow using [Astro's middleware](https://docs.astro.build/en/guides/middleware/), preventing unauthorized access to sensitive areas.
|
||||
|
||||
The application includes complete [logout functionality](https://zitadel.com/docs/guides/integrate/login/oidc/logout) that performs [federated single sign-out](https://zitadel.com/docs/guides/integrate/login/oidc/logout), terminating both the local session and the remote Zitadel session through the [end-session endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints). It demonstrates [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) capabilities using [refresh tokens](https://zitadel.com/docs/concepts/tokens) with the `offline_access` [scope](https://zitadel.com/docs/apis/openidoauth/scopes), allowing users to maintain authenticated sessions without repeated logins. The example also shows how to request additional [OIDC scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `profile`, `email`, and Zitadel-specific scopes for [user metadata](https://zitadel.com/docs/guides/manage/customize/user-metadata), [organization information](https://zitadel.com/docs/guides/manage/organizations/), and [role assignments](https://zitadel.com/docs/guides/manage/console/roles).
|
||||
|
||||
---
|
||||
|
||||
## 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/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)
|
||||
2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce)
|
||||
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](https://zitadel.com/docs/guides/manage/console/overview) 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](https://zitadel.com/docs/guides/integrate/login/oidc/):
|
||||
|
||||
1. Clone the [repository](https://github.com/zitadel/example-auth-astro).
|
||||
2. Create a `.env` file based on `.env.example` and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview). 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](https://zitadel.com/docs/guides/manage/console/instance-settings) (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](https://www.npmjs.com) 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
|
||||
|
||||
* **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/)
|
||||
* **Astro documentation:** [https://astro.build](https://astro.build)
|
||||
* **Auth.js documentation:** [https://authjs.dev](https://authjs.dev)
|
||||
* **@auth/core package:** [https://www.npmjs.com/package/@auth/core](https://www.npmjs.com/package/@auth/core)
|
||||
* **auth-astro adapter:** [https://www.npmjs.com/package/auth-astro](https://www.npmjs.com/package/auth-astro)
|
||||
* **Example repository:** [https://github.com/zitadel/example-auth-astro](https://github.com/zitadel/example-auth-astro)
|
||||
* **All framework examples:** [/docs/examples](/docs/examples)
|
||||
91
docs/docs/sdk-examples/expressjs.mdx
Normal file
91
docs/docs/sdk-examples/expressjs.mdx
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Express.js
|
||||
sidebar_label: Express.js
|
||||
framework_url: https://expressjs.com
|
||||
auth_library: "@auth/express"
|
||||
auth_library_url: https://www.npmjs.com/package/@auth/express
|
||||
example_repo: https://github.com/zitadel/example-auth-express
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[Express.js](https://expressjs.com) is a fast, unopinionated, minimalist web framework for [Node.js](https://nodejs.org) that provides a robust set of features for building web and mobile applications. 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 Express application.
|
||||
|
||||
#### Auth library
|
||||
|
||||
This example uses **[@auth/express](https://www.npmjs.com/package/@auth/express)** ([GitHub](https://github.com/nextauthjs/next-auth)), the Express.js adapter for [Auth.js](https://authjs.dev). This library implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol with [PKCE](/docs/concepts/pkce) support, manages [token exchange](https://zitadel.com/docs/apis/openidoauth/grant-types), performs automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token), and provides [session management](https://zitadel.com/docs/concepts/sessions) with secure cookie-based storage.
|
||||
|
||||
---
|
||||
|
||||
## What this example demonstrates
|
||||
|
||||
This Express.js example provides a complete authentication implementation using [Zitadel](https://zitadel.com/docs) as the identity provider. The application starts with a public landing page featuring a login button that initiates the [PKCE authentication flow](/docs/concepts/pkce). When users click login, [@auth/express](https://www.npmjs.com/package/@auth/express) generates a cryptographic code verifier and challenge, then redirects to Zitadel's authorization endpoint. After successful authentication at Zitadel, users return to the application's [callback URL](https://zitadel.com/docs/guides/integrate/login/oidc/) where the authorization code is exchanged for [access tokens](https://zitadel.com/docs/apis/openidoauth/endpoints) and an [ID token](https://zitadel.com/docs/apis/openidoauth/claims).
|
||||
|
||||
The example includes protected routes using [Express middleware](https://expressjs.com/en/guide/using-middleware.html) that automatically verify [session state](https://zitadel.com/docs/concepts/sessions) and redirect unauthenticated users to the sign-in page. Authenticated users can access their profile page displaying user information including email, name, and custom [metadata claims](https://zitadel.com/docs/apis/openidoauth/claims) from Zitadel. The application maintains long-lived sessions through automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) using [refresh tokens](https://zitadel.com/docs/concepts/tokens), ensuring users remain authenticated without repeated logins.
|
||||
|
||||
Sign-out functionality implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by redirecting to Zitadel's end-session endpoint with the ID token hint, terminating both the local [session](https://zitadel.com/docs/concepts/sessions) and the Zitadel session. The logout flow includes [CSRF protection](https://authjs.dev/guides/basics/securing-pages-and-api-routes) through state parameter validation, and users are redirected to a success page after logout completion. All authentication flows use secure HTTP-only cookies for [session storage](https://authjs.dev/concepts/session-strategies) and implement proper security headers.
|
||||
|
||||
---
|
||||
|
||||
## 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/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/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/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](https://zitadel.com/docs/guides/integrate/login/oidc/):
|
||||
|
||||
1. Clone the [repository](https://github.com/zitadel/example-auth-express).
|
||||
2. Create a `.env.local` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview). 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-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_LOGIN_URL=/profile
|
||||
ZITADEL_POST_LOGOUT_URL=http://localhost:3000
|
||||
```
|
||||
Replace these values with:
|
||||
- Your actual Zitadel instance URL (the **Issuer** from the [PKCE setup guide](/docs/guides/integrate/login/oidc/pkce-setup))
|
||||
- The **Client ID** you copied when creating the application
|
||||
- A randomly generated client secret (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
|
||||
- The **redirect URI** you configured in the PKCE setup (must match exactly)
|
||||
- A strong session secret (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
|
||||
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The application will be running at `http://localhost:3000`.
|
||||
|
||||
---
|
||||
|
||||
## Learn more and resources
|
||||
|
||||
* **Zitadel documentation:** [https://zitadel.com/docs](https://zitadel.com/docs)
|
||||
* **PKCE concept:** /docs/concepts/pkce
|
||||
* **PKCE application 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/)
|
||||
* **Framework docs:** https://expressjs.com
|
||||
* **Auth library:** https://www.npmjs.com/package/@auth/express
|
||||
* **Auth.js documentation:** https://authjs.dev
|
||||
* **Example repository:** https://github.com/zitadel/example-auth-express
|
||||
* **All framework examples:** /docs/examples
|
||||
86
docs/docs/sdk-examples/fastify.mdx
Normal file
86
docs/docs/sdk-examples/fastify.mdx
Normal file
@@ -0,0 +1,86 @@
|
||||
---
|
||||
title: Fastify
|
||||
sidebar_label: Fastify
|
||||
framework_url: https://fastify.dev
|
||||
auth_library: "@auth/core"
|
||||
auth_library_url: https://www.npmjs.com/package/@auth/core
|
||||
example_repo: https://github.com/zitadel/example-auth-fastify
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[Fastify](https://fastify.dev) is a fast and low overhead web framework for Node.js, designed for building efficient server-side applications. This example demonstrates how to integrate **[ZITADEL](https://zitadel.com/docs)** 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 **[@mridang/fastify-auth](https://www.npmjs.com/package/@mridang/fastify-auth)**, a [Fastify](https://fastify.dev) plugin that wraps **[@auth/core](https://www.npmjs.com/package/@auth/core)** (formerly Auth.js). The underlying [@auth/core](https://authjs.dev) library implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](/docs/concepts/pkce), performs secure token exchange, and provides session management helpers. This integration leverages the **[@auth/core/providers/zitadel](https://authjs.dev/reference/core/providers/zitadel)** provider specifically designed for ZITADEL authentication.
|
||||
|
||||
---
|
||||
|
||||
## What this example demonstrates
|
||||
|
||||
This example shows a complete authentication implementation using [Fastify](https://fastify.dev) with [server-side rendering](https://fastify.dev) via [@fastify/view](https://www.npmjs.com/package/@fastify/view) and [Handlebars](https://handlebarsjs.com) templates. The application implements secure user authentication through [ZITADEL](https://zitadel.com/docs) using the industry-standard [PKCE flow](/docs/concepts/pkce), which prevents authorization code interception attacks without requiring client secrets.
|
||||
|
||||
The example includes a custom sign-in page that initiates the [OAuth 2.0](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) authentication flow, automatic [callback handling](https://zitadel.com/docs/guides/integrate/login/oidc/) with secure [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints), and [JWT-based session management](https://zitadel.com/docs/concepts/tokens) with [@fastify/cookie](https://www.npmjs.com/package/@fastify/cookie). Protected routes use the `requireAuth` middleware to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/concepts/tokens).
|
||||
|
||||
The application also demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with ZITADEL's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/concepts/tokens) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [ZITADEL-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles).
|
||||
|
||||
---
|
||||
|
||||
## 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/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)
|
||||
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`)
|
||||
5. Copy your **Client ID** for use in the next steps
|
||||
6. Optionally enable [refresh tokens](https://zitadel.com/docs/concepts/tokens) in Token Settings for long-lived sessions
|
||||
|
||||
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](https://zitadel.com/docs/guides/manage/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](https://zitadel.com/docs/guides/integrate/login/oidc/) configured:
|
||||
|
||||
1. Clone the [repository](https://github.com/zitadel/example-auth-fastify).
|
||||
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [ZITADEL application](https://zitadel.com/docs/guides/manage/console/overview). **Use these exact environment variable names:**
|
||||
```
|
||||
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-zitadel-application-client-id
|
||||
ZITADEL_CLIENT_SECRET=
|
||||
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
|
||||
ZITADEL_POST_LOGIN_URL=/profile
|
||||
ZITADEL_POST_LOGOUT_URL=http://localhost:3000
|
||||
```
|
||||
Replace these values with:
|
||||
- Your actual [ZITADEL instance URL](https://zitadel.com/docs/guides/manage/console/overview) for `ZITADEL_DOMAIN` (the issuer)
|
||||
- The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID`
|
||||
- The **redirect URI** you configured in the PKCE setup for `ZITADEL_CALLBACK_URL` (must match exactly)
|
||||
- The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL`
|
||||
- A strong random string for `SESSION_SECRET` (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
|
||||
3. Install dependencies using [npm](https://www.npmjs.com) with `npm install` and start the development server with `npm run dev` 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
|
||||
* **PKCE application 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/)
|
||||
* **Fastify documentation:** https://fastify.dev
|
||||
* **Auth.js (Auth/Core):** https://www.npmjs.com/package/@auth/core
|
||||
* **Fastify Auth plugin:** https://www.npmjs.com/package/@mridang/fastify-auth
|
||||
* **Example repository:** https://github.com/zitadel/example-auth-fastify
|
||||
* **All framework examples:** /docs/examples
|
||||
93
docs/docs/sdk-examples/hono.mdx
Normal file
93
docs/docs/sdk-examples/hono.mdx
Normal file
@@ -0,0 +1,93 @@
|
||||
---
|
||||
title: Hono
|
||||
sidebar_label: Hono
|
||||
framework_url: https://hono.dev
|
||||
auth_library: "@auth/core"
|
||||
auth_library_url: https://authjs.dev
|
||||
example_repo: https://github.com/zitadel/example-auth-hono
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[Hono](https://hono.dev) is a small, simple, and ultrafast web framework for the Edges that works on Cloudflare Workers, Fastly Compute, Deno, Bun, Vercel, Netlify, AWS Lambda, Lambda@Edge, and Node.js. 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 Hono application.
|
||||
|
||||
#### Auth library
|
||||
|
||||
This example uses **[Auth.js](https://authjs.dev)** (formerly NextAuth.js), the standard authentication library for modern web frameworks. Auth.js implements the [OpenID Connect](https://openid.net/connect/) (OIDC) protocol with [PKCE](/docs/concepts/pkce), performs secure token exchange, and provides session management helpers. The integration uses **[@hono/auth-js](https://www.npmjs.com/package/@hono/auth-js)**, the official Hono adapter for Auth.js, along with **[@auth/core](https://www.npmjs.com/package/@auth/core)** which handles the core OIDC flows and the **[Zitadel provider](https://authjs.dev/reference/core/providers/zitadel)**.
|
||||
|
||||
---
|
||||
|
||||
## What this example demonstrates
|
||||
|
||||
This example showcases a complete web application authentication pattern with [Hono](https://hono.dev) and [Zitadel](https://zitadel.com/docs). Users start on a public landing page, initiate authentication with Zitadel using the secure [PKCE flow](/docs/concepts/pkce), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) after successful authentication. The application demonstrates several key features including sign-in with [authorization code flow + PKCE](/docs/concepts/pkce), OAuth callback handling with secure [session storage](https://authjs.dev/concepts/session-strategies) using [JWT strategy](https://authjs.dev/concepts/session-strategies#jwt-session), route protection through [authentication middleware](https://hono.dev/docs/guides/middleware) that guards sensitive pages, automatic [token refresh](https://authjs.dev/guides/refresh-token-rotation) to maintain long-lived sessions without requiring re-authentication, access to user profile information including [OIDC standard claims](https://zitadel.com/docs/apis/openidoauth/claims) and [Zitadel-specific claims](https://zitadel.com/docs/apis/openidoauth/claims#reserved-claims) such as organization roles and metadata, and secure sign-out with [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) that terminates both the local session and the Zitadel session through the end-session endpoint.
|
||||
|
||||
The implementation uses [Handlebars templates](https://handlebarsjs.com/) for server-side rendering, [@hono/node-server](https://www.npmjs.com/package/@hono/node-server) for running on Node.js, secure [HTTP-only cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#security) for session management, and [CSRF protection](https://authjs.dev/concepts/session-strategies#csrf-protection) through Auth.js built-in tokens. The authentication flow follows OAuth 2.0 best practices with [Proof Key for Code Exchange](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) to prevent authorization code interception attacks.
|
||||
|
||||
---
|
||||
|
||||
## 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/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)
|
||||
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/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-hono).
|
||||
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview). **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-instance.zitadel.cloud
|
||||
ZITADEL_CLIENT_ID=your_client_id_from_console
|
||||
ZITADEL_CLIENT_SECRET=
|
||||
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
|
||||
ZITADEL_POST_LOGIN_URL=/profile
|
||||
ZITADEL_POST_LOGOUT_URL=http://localhost:3000
|
||||
```
|
||||
Replace these values with:
|
||||
- Your actual **Zitadel instance URL** (the Issuer from your [instance settings](https://zitadel.com/docs/guides/manage/console/instance-settings))
|
||||
- The **Client ID** you copied when creating the application in the PKCE setup
|
||||
- The **redirect URI** you configured in the PKCE setup (must match exactly)
|
||||
- The **post-logout redirect URI** for handling logout callbacks
|
||||
- A strong random **session secret** (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
|
||||
|
||||
> **Note:** While PKCE doesn't require a client secret for public clients, Auth.js requires a value for internal configuration. You can leave `ZITADEL_CLIENT_SECRET` empty or provide a random string.
|
||||
|
||||
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The application will be running at `http://localhost:3000`. Visit the homepage to test the authentication flow.
|
||||
|
||||
---
|
||||
|
||||
## 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/)
|
||||
* **OAuth recommended flows:** [https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows)
|
||||
* **Framework docs:** [https://hono.dev](https://hono.dev)
|
||||
* **Auth.js:** [https://authjs.dev](https://authjs.dev)
|
||||
* **Auth.js Hono adapter:** [https://www.npmjs.com/package/@hono/auth-js](https://www.npmjs.com/package/@hono/auth-js)
|
||||
* **Example repository:** [https://github.com/zitadel/example-auth-hono](https://github.com/zitadel/example-auth-hono)
|
||||
* **All framework examples:** [/docs/examples](/docs/examples)
|
||||
@@ -1,56 +1,97 @@
|
||||
---
|
||||
title: NestJS
|
||||
sidebar_label: NestJS
|
||||
framework_url: https://nestjs.com
|
||||
auth_library: "@auth/core"
|
||||
auth_library_url: https://www.npmjs.com/package/@auth/core
|
||||
example_repo: https://github.com/zitadel/example-auth-nestjs
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="100px">
|
||||
<img width="100px" src="/docs/img/tech/nestjs.svg" alt="nest js logo"/>
|
||||
</td>
|
||||
<td>
|
||||
<a href="https://nestjs.com/" target="_blank">NestJS</a> is a comprehensive and well-maintained TypeScript-based framework for building large-scale, scalable, and maintainable Node.js applications.
|
||||
Get started integrating ZITADEL to your NestJS API by checking out the <a href="https://github.com/ehwplus/zitadel-nodejs-nestjs" target="_blank">zitadel-nodejs-nestjs</a> Example.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
## Overview
|
||||
|
||||
[NestJS](https://nestjs.com) is a progressive Node.js framework for building efficient, reliable, and scalable server-side applications using [TypeScript](https://www.typescriptlang.org). 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 NestJS application.
|
||||
|
||||
### Resources
|
||||
- [Example App Repository](https://github.com/ehwplus/zitadel-nodejs-nestjs)
|
||||
- [Step-By-Step Guide](/docs/examples/secure-api/nodejs-nestjs)
|
||||
- [Passport.js](https://github.com/buehler/node-passport-zitadel) for integrating authentication
|
||||
- [Node.js gRPC Client Library](https://www.npmjs.com/package/@zitadel/node) for user and resource management
|
||||
#### Auth library
|
||||
|
||||
### SDK
|
||||
This example uses **[@auth/core](https://www.npmjs.com/package/@auth/core)**, the core authentication library powering [Auth.js](https://authjs.dev), which implements the [OpenID Connect (OIDC)](https://openid.net/connect/) flow, manages [PKCE](/docs/concepts/pkce), performs [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints), and exposes helpers for [session state](https://zitadel.com/docs/guides/integrate/login/oidc/session-handling). The example integrates this through the **[@mridang/nestjs-auth](https://www.npmjs.com/package/@mridang/nestjs-auth)** [NestJS module](https://docs.nestjs.com/modules), which provides [decorators](https://docs.nestjs.com/custom-decorators), [guards](https://docs.nestjs.com/guards), and middleware for seamless authentication within the NestJS ecosystem.
|
||||
|
||||
ZITADEL doesn't provide a specific Nestjs SDK. You can use [passport-zitadel](https://github.com/buehler/node-passport-zitadel) for the authentication part.
|
||||
---
|
||||
|
||||
Check out the [Example Application](/docs/sdk-examples/nestjs#example-application).
|
||||
## What this example demonstrates
|
||||
|
||||
Additionally, you can use [@zitadel/node](https://www.npmjs.com/package/@zitadel/node) for user and resource management.
|
||||
- Manage Resources through ZITADEL APIs
|
||||
- Authenticate Service User
|
||||
- Generated gRPC Clients for integrating ZITADEL API
|
||||
- User, Organization, Project, etc. Management
|
||||
This example implements a complete authentication flow using [PKCE](/docs/concepts/pkce) with [Zitadel](https://zitadel.com/docs) as the identity provider. Users begin on a public landing page and click a login button to authenticate through Zitadel's authorization server. After successful authentication, they're redirected to a protected profile page displaying their user information retrieved from the [ID token](https://zitadel.com/docs/apis/openidoauth/claims) and [access token](https://zitadel.com/docs/concepts/tokens).
|
||||
|
||||
:::note
|
||||
This library is built by our community.
|
||||
:::
|
||||
The application leverages [NestJS controllers](https://docs.nestjs.com/controllers) to handle authentication routes and [@mridang/nestjs-auth guards](https://www.npmjs.com/package/@mridang/nestjs-auth) to protect routes requiring authentication. [Session management](https://zitadel.com/docs/guides/integrate/login/oidc/session-handling) is handled through encrypted [JWT-based sessions](https://authjs.dev/concepts/session-strategies#jwt-session) stored in secure, HTTP-only cookies. The example includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) functionality using [refresh tokens](https://oauth.net/2/refresh-tokens/), ensuring users maintain their sessions without interruption when access tokens expire.
|
||||
|
||||
### Example Application
|
||||
The logout implementation demonstrates [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. [CSRF protection](https://owasp.org/www-community/attacks/csrf) during logout is achieved through a state parameter validated in the callback. The example also showcases accessing Zitadel's [UserInfo endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#userinfo) to fetch real-time user data, including [custom claims](https://zitadel.com/docs/apis/openidoauth/claims), [roles](https://zitadel.com/docs/guides/manage/console/roles), and organization membership.
|
||||
|
||||
What does the API Application Example include:
|
||||
- REST API Application secured with Spring Security and OAuth2
|
||||
- Private Endpoint: Accessible with a token
|
||||
All protected routes are secured using the [@mridang/nestjs-auth global guard](https://www.npmjs.com/package/@mridang/nestjs-auth), with the `@Public()` decorator marking routes that don't require authentication. The application uses [Handlebars templates](https://handlebarsjs.com) for server-side rendering and [Tailwind CSS](https://tailwindcss.com) for styling, providing a complete reference implementation for NestJS developers.
|
||||
|
||||
[Example API Application](https://github.com/ehwplus/zitadel-nodejs-nestjs)
|
||||
---
|
||||
|
||||
### Step-By-Step Guide
|
||||
## Getting started
|
||||
|
||||
After completing the Step-By-Step Guide you will have:
|
||||
1. Example REST API checking tokens against ZITADEL with OAuth2
|
||||
2. Private Endpoint accessible by authenticated user
|
||||
3. Correct setup for your application in ZITADEL
|
||||
### Prerequisites
|
||||
|
||||
[API APP Step-By-Step Guide](/docs/examples/secure-api/nodejs-nestjs)
|
||||
Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/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
|
||||
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 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-nestjs).
|
||||
2. Create a `.env` file in the project root and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview). **Use the exact environment variable names from the repository:**
|
||||
```
|
||||
NODE_ENV=development
|
||||
PORT=3000
|
||||
|
||||
SESSION_SECRET=your-very-secret-and-strong-session-key
|
||||
SESSION_SALT=your-cryptographic-salt
|
||||
SESSION_DURATION=3600
|
||||
|
||||
ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
|
||||
ZITADEL_CLIENT_ID=your_client_id_from_console
|
||||
ZITADEL_CLIENT_SECRET=your_randomly_generated_secret
|
||||
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
|
||||
ZITADEL_POST_LOGIN_URL=/profile
|
||||
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
|
||||
```
|
||||
Replace these values with:
|
||||
- Your actual Zitadel instance URL (the **Issuer**)
|
||||
- The **Client ID** you copied when creating the application
|
||||
- A randomly generated **Client Secret** (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
|
||||
- A secure **Session Secret** (generate using the same command)
|
||||
- A cryptographic **Session Salt** for cookie encryption
|
||||
- The **redirect URI** you configured in the PKCE setup (must match exactly)
|
||||
- The **post-logout redirect URI** for the logout callback
|
||||
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
The application will be running at `http://localhost:3000`. Visit the URL 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/)
|
||||
* **Framework docs:** [https://nestjs.com](https://nestjs.com)
|
||||
* **Auth library (@auth/core):** [https://www.npmjs.com/package/@auth/core](https://www.npmjs.com/package/@auth/core)
|
||||
* **NestJS auth module:** [https://www.npmjs.com/package/@mridang/nestjs-auth](https://www.npmjs.com/package/@mridang/nestjs-auth)
|
||||
* **Example repository:** [https://github.com/zitadel/example-auth-nestjs](https://github.com/zitadel/example-auth-nestjs)
|
||||
* **All framework examples:** [/docs/examples](/docs/examples)
|
||||
|
||||
88
docs/docs/sdk-examples/nuxtjs.mdx
Normal file
88
docs/docs/sdk-examples/nuxtjs.mdx
Normal file
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: Nuxt.js
|
||||
sidebar_label: Nuxt.js
|
||||
framework_url: https://nuxt.com
|
||||
auth_library: next-auth
|
||||
auth_library_url: https://next-auth.js.org
|
||||
example_repo: https://github.com/zitadel/example-auth-nuxtjs
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[Nuxt.js](https://nuxt.com) is the intuitive [Vue.js](https://vuejs.org) framework that enables you to create full-stack web applications with server-side rendering, file-based routing, and auto-imports. 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 **[@sidebase/nuxt-auth](https://www.npmjs.com/package/@sidebase/nuxt-auth)**, a Nuxt module that wraps **[NextAuth.js/Auth.js](https://next-auth.js.org)** for seamless authentication integration. Under the hood, it leverages **[next-auth](https://www.npmjs.com/package/next-auth)** with the **[openid-client](https://www.npmjs.com/package/openid-client)** library to implement the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manage [PKCE](/docs/concepts/pkce), perform token exchange, and handle [session management](https://zitadel.com/docs/concepts/structure/sessions).
|
||||
|
||||
---
|
||||
|
||||
## What this example demonstrates
|
||||
|
||||
This [Nuxt.js](https://nuxt.com) application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with the **[PKCE flow](/docs/concepts/pkce)**. Users begin on a public landing page where they can initiate sign-in with Zitadel through the **[@sidebase/nuxt-auth](https://www.npmjs.com/package/@sidebase/nuxt-auth)** module. After successful authentication, they're redirected to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).
|
||||
|
||||
The example implements secure [session management](https://zitadel.com/docs/concepts/structure/sessions) using [JWT tokens](https://zitadel.com/docs/concepts/structure/tokens) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) capabilities through [refresh tokens](https://zitadel.com/docs/concepts/structure/tokens#refresh-token). Protected routes automatically redirect unauthenticated users to the sign-in flow using [Nuxt middleware](https://nuxt.com/docs/guide/directory-structure/middleware), ensuring sensitive areas remain secure. The application also includes complete **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** functionality that properly terminates both the local session and the Zitadel session through the [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), redirecting users back to the application with proper CSRF protection using state parameters.
|
||||
|
||||
---
|
||||
|
||||
## 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/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)
|
||||
2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce)
|
||||
3. Set up your redirect URIs (e.g., `http://localhost:3000/api/auth/callback/zitadel` for development)
|
||||
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/`)
|
||||
5. 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:
|
||||
|
||||
1. Clone the [repository](https://github.com/zitadel/example-auth-nuxtjs).
|
||||
2. Create a `.env` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview). **Use these exact environment variable names:**
|
||||
```
|
||||
PORT=3000
|
||||
SESSION_DURATION=3600
|
||||
NUXT_AUTH_SECRET=your-very-secret-and-strong-session-key
|
||||
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_LOGOUT_URL=http://localhost:3000/
|
||||
AUTH_ORIGIN=http://localhost:3000
|
||||
```
|
||||
Replace these values with:
|
||||
- Your actual Zitadel instance URL (the **Issuer** from your [ZITADEL instance settings](https://zitadel.com/docs/guides/manage/console/overview))
|
||||
- The **Client ID** you copied when creating the application
|
||||
- A randomly generated **NUXT_AUTH_SECRET** for session encryption (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
|
||||
- The **callback URI** you configured in the PKCE setup (must match exactly)
|
||||
- The **post-logout redirect URI** you configured in the PKCE setup
|
||||
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The application will be running at `http://localhost:3000` where you can test the complete authentication flow.
|
||||
|
||||
---
|
||||
|
||||
## 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/)
|
||||
* **Framework docs:** [https://nuxt.com](https://nuxt.com)
|
||||
* **@sidebase/nuxt-auth:** [https://www.npmjs.com/package/@sidebase/nuxt-auth](https://www.npmjs.com/package/@sidebase/nuxt-auth)
|
||||
* **NextAuth.js/Auth.js:** [https://next-auth.js.org](https://next-auth.js.org)
|
||||
* **Example repository:** [https://github.com/zitadel/example-auth-nuxtjs](https://github.com/zitadel/example-auth-nuxtjs)
|
||||
* **All framework examples:** [/docs/examples](/docs/examples)
|
||||
90
docs/docs/sdk-examples/qwik.mdx
Normal file
90
docs/docs/sdk-examples/qwik.mdx
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: Qwik
|
||||
sidebar_label: Qwik
|
||||
framework_url: https://qwik.dev
|
||||
auth_library: "@auth/core"
|
||||
auth_library_url: https://www.npmjs.com/package/@auth/core
|
||||
example_repo: https://github.com/zitadel/example-auth-qwik
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[Qwik](https://qwik.dev) is a framework for building resumable web applications with instant-on interactivity and optimal performance. 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 the app.
|
||||
|
||||
#### Auth library
|
||||
|
||||
This example uses **[@auth/qwik](https://www.npmjs.com/package/@auth/qwik)**, a Qwik adapter for **[@auth/core](https://www.npmjs.com/package/@auth/core)** (formerly Auth.js/NextAuth.js), which implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](/docs/concepts/pkce), performs token exchange, and exposes helpers for [session state](https://zitadel.com/docs/concepts/sessions). The core library handles authentication across multiple frameworks and provides secure [token storage](https://zitadel.com/docs/concepts/tokens) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) capabilities.
|
||||
|
||||
---
|
||||
|
||||
## What this example demonstrates
|
||||
|
||||
This [Qwik](https://qwik.dev) application showcases a complete authentication implementation using [ZITADEL](https://zitadel.com/docs) with the [Authorization Code Flow with PKCE](/docs/concepts/pkce). The example includes secure sign-in functionality that redirects users to ZITADEL's hosted login page, handles the OAuth callback to exchange authorization codes for [access tokens](https://zitadel.com/docs/concepts/tokens), and manages [sessions](https://zitadel.com/docs/concepts/sessions) with [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#json-web-token-jwt-profile) stored in encrypted server-side cookies.
|
||||
|
||||
Route protection is implemented using [Qwik City's](https://qwik.dev/docs/qwikcity) `onRequest` handler, which performs server-side authentication checks before rendering protected pages. Unauthenticated users attempting to access secured routes are automatically redirected to the login page with a callback URL to return them to their intended destination after successful authentication. The application displays comprehensive user profile information including standard [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) like name and email, as well as ZITADEL-specific claims such as [organization membership](https://zitadel.com/docs/guides/manage/console/organizations) and [project roles](https://zitadel.com/docs/guides/manage/console/projects).
|
||||
|
||||
Sign-out functionality implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through ZITADEL's end-session endpoint, ensuring that users are logged out from both the application and ZITADEL's [single sign-on session](https://zitadel.com/docs/concepts/sessions). The logout process includes [CSRF protection](https://zitadel.com/docs/guides/integrate/login/oidc/logout#csrf-protection) using state parameters validated through secure cookies, followed by proper cleanup of session data and redirection back to the application.
|
||||
|
||||
---
|
||||
|
||||
## 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/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)
|
||||
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/zitadel` for development)
|
||||
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/api/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/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](https://zitadel.com/docs/guides/integrate/login/oidc/) configured:
|
||||
|
||||
1. Clone the [repository](https://github.com/zitadel/example-auth-qwik).
|
||||
2. Create a `.env.local` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview):
|
||||
```
|
||||
VITE_PORT=3000
|
||||
VITE_SESSION_SECRET=your-very-secret-and-strong-session-key
|
||||
VITE_SESSION_DURATION=3600
|
||||
VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
|
||||
VITE_ZITADEL_CLIENT_ID=your_client_id_from_console
|
||||
VITE_ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
|
||||
VITE_ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback/zitadel
|
||||
VITE_ZITADEL_POST_LOGOUT_URL=http://localhost:3000/api/auth/logout/callback
|
||||
```
|
||||
Replace these values with:
|
||||
- Your actual Zitadel instance URL (the **Issuer** from your [application settings](https://zitadel.com/docs/guides/integrate/login/oidc/))
|
||||
- The **Client ID** you copied when creating the application
|
||||
- A randomly generated session secret (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
|
||||
- A randomly generated client secret value (Auth.js requires this for internal configuration)
|
||||
- The **redirect URI** you configured in the PKCE setup (must match exactly)
|
||||
- The **post-logout redirect URI** you configured (must match exactly)
|
||||
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The application will be available at `http://localhost:3000`.
|
||||
|
||||
---
|
||||
|
||||
## Learn more and resources
|
||||
|
||||
* **Zitadel documentation:** [https://zitadel.com/docs](https://zitadel.com/docs)
|
||||
* **PKCE concept:** /docs/concepts/pkce
|
||||
* **PKCE application 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/)
|
||||
* **Framework docs:** https://qwik.dev
|
||||
* **Auth library (@auth/core):** https://www.npmjs.com/package/@auth/core
|
||||
* **Qwik adapter (@auth/qwik):** https://www.npmjs.com/package/@auth/qwik
|
||||
* **Example repository:** https://github.com/zitadel/example-auth-qwik
|
||||
* **All framework examples:** /docs/examples
|
||||
90
docs/docs/sdk-examples/solidstart.mdx
Normal file
90
docs/docs/sdk-examples/solidstart.mdx
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: SolidStart
|
||||
sidebar_label: SolidStart
|
||||
framework_url: https://start.solidjs.com
|
||||
auth_library: "@auth/core"
|
||||
auth_library_url: https://www.npmjs.com/package/@auth/core
|
||||
example_repo: https://github.com/zitadel/example-auth-solidstart
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
[SolidStart](https://start.solidjs.com) is a full-stack web framework built on top of [SolidJS](https://solidjs.com) that enables you to create performant web applications with a modern development experience. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](/docs/concepts/pkce)** to authenticate users securely and maintain [sessions](https://zitadel.com/docs/concepts/structure/users#sessions) across the app.
|
||||
|
||||
#### Auth library
|
||||
|
||||
This example uses **[@auth/solid-start](https://www.npmjs.com/package/@auth/solid-start)**, the SolidStart adapter for [Auth.js](https://authjs.dev), which builds on **[@auth/core](https://www.npmjs.com/package/@auth/core)**. Auth.js implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](/docs/concepts/pkce), performs [token exchange](https://zitadel.com/docs/apis/openidoauth/grant-types), and exposes helpers for [session state](https://zitadel.com/docs/concepts/structure/users#sessions). The example also uses **[openid-client](https://www.npmjs.com/package/openid-client)** ([GitHub](https://github.com/panva/node-openid-client)) for manual token refresh operations and logout URL construction.
|
||||
|
||||
---
|
||||
|
||||
## What this example demonstrates
|
||||
|
||||
This example shows a complete authentication implementation using [SolidStart](https://start.solidjs.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page and click a login button to authenticate with Zitadel using the secure **[PKCE flow](/docs/concepts/pkce)**. The [Auth.js](https://authjs.dev) library handles the [OAuth 2.0](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) authorization code exchange and manages secure [session storage](https://zitadel.com/docs/concepts/structure/users#sessions) using encrypted [JWT tokens](https://zitadel.com/docs/concepts/tokens). After successful authentication, users are redirected to a protected profile page displaying their user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) like name, email, and custom [Zitadel metadata](https://zitadel.com/docs/apis/openidoauth/claims#reserved-claims).
|
||||
|
||||
The application implements automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. When an [access token](https://zitadel.com/docs/concepts/tokens) expires, the refresh logic seamlessly exchanges the [refresh token](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) for new tokens in the background. [Route protection](https://start.solidjs.com/api/createAsync) is implemented using [SolidStart's server functions](https://start.solidjs.com/api/server$), ensuring only authenticated users can access sensitive areas. The logout flow implements [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/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](https://zitadel.com/docs/guides/manage/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)
|
||||
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/api/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/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](https://zitadel.com/docs/guides/integrate/login/oidc/) configured:
|
||||
|
||||
1. Clone the [repository](https://github.com/zitadel/example-auth-solidstart).
|
||||
2. Create a `.env` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview). 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/auth/callback"
|
||||
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](https://zitadel.com/docs/guides/manage/console/instance-settings) (the **Issuer**)
|
||||
- The **Client ID** you copied when [creating the application](/docs/guides/integrate/login/oidc/pkce-setup)
|
||||
- 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](https://authjs.dev) configuration compatibility
|
||||
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server to verify the authentication flow end-to-end:
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Learn more and resources
|
||||
|
||||
* **Zitadel documentation:** [https://zitadel.com/docs](https://zitadel.com/docs)
|
||||
* **PKCE concept:** /docs/concepts/pkce
|
||||
* **PKCE application 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/)
|
||||
* **SolidStart documentation:** [https://start.solidjs.com](https://start.solidjs.com)
|
||||
* **Auth.js documentation:** [https://authjs.dev](https://authjs.dev)
|
||||
* **@auth/solid-start:** [https://www.npmjs.com/package/@auth/solid-start](https://www.npmjs.com/package/@auth/solid-start)
|
||||
* **@auth/core:** [https://www.npmjs.com/package/@auth/core](https://www.npmjs.com/package/@auth/core)
|
||||
* **openid-client:** [https://www.npmjs.com/package/openid-client](https://www.npmjs.com/package/openid-client)
|
||||
* **Example repository:** [https://github.com/zitadel/example-auth-solidstart](https://github.com/zitadel/example-auth-solidstart)
|
||||
* **All framework examples:** /docs/examples
|
||||
89
docs/docs/sdk-examples/sveltekit.mdx
Normal file
89
docs/docs/sdk-examples/sveltekit.mdx
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
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/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)
|
||||
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/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/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)
|
||||
@@ -1,62 +1,85 @@
|
||||
---
|
||||
title: Vue.js
|
||||
sidebar_label: Vue.js
|
||||
framework_url: https://vuejs.org
|
||||
auth_library: oidc-client-ts
|
||||
auth_library_url: https://www.npmjs.com/package/oidc-client-ts
|
||||
example_repo: https://github.com/zitadel/example-auth-vuejs
|
||||
auth_flow: pkce
|
||||
status: stable
|
||||
---
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="100px">
|
||||
<img width="100px" src="/docs/img/tech/vue.svg" alt="vue"/>
|
||||
</td>
|
||||
<td>
|
||||
<a href="https://vuejs.org/" target="_blank">Vue.js</a> is a JavaScript framework for building user interfaces that is simple, flexible, and versatile.
|
||||
Integrate authentication to your Vue.js application easily by using the <a href="https://github.com/zitadel/zitadel-vue" target="_blank">zitadel-vue</a> SDK
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
## Overview
|
||||
|
||||
### Resources
|
||||
- [SDK with Example App](https://github.com/zitadel/zitadel-vue)
|
||||
- [Step-By-Step Guide](/docs/examples/login/vue)
|
||||
[Vue.js](https://vuejs.org) is a progressive JavaScript framework for building user interfaces with reactive data binding, component composition, and a rich ecosystem. 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 Vue.js application.
|
||||
|
||||
### Vue SDK
|
||||
#### Auth library
|
||||
|
||||
The [zitadel-vue](https://github.com/zitadel/zitadel-vue) SDK is a wrapper around the [vue-oidc-client](https://github.com/soukoku/vue-oidc-client) and abstracts the handling of specific configurations for ZITADEL.
|
||||
This example uses **[vue-oidc-context](https://www.npmjs.com/package/vue-oidc-context)**, a Vue 3 wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**, which implements the [OpenID Connect](https://openid.net/connect/) (OIDC) flow. The underlying [oidc-client-ts](https://github.com/authts/oidc-client-ts) library manages [PKCE](/docs/concepts/pkce), performs [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints), and exposes helpers for [session state](https://zitadel.com/docs/concepts/tokens) management.
|
||||
|
||||
The following features are covered by the SDK:
|
||||
- Authenticate your user with ZITADEL using OIDC
|
||||
- Requesting ZITADEL userinfo endpoint to get user data
|
||||
- Refresh Token
|
||||
- Requesting User Roles from userinfo
|
||||
- Check if user has specified role
|
||||
- Logout
|
||||
---
|
||||
|
||||
The goal is to extend the SDK over the time with the following features:
|
||||
- Integrate ZITADEL APIs to read and manage resources
|
||||
- Build your own login UI using our Session API
|
||||
## What this example demonstrates
|
||||
|
||||
### Example Application
|
||||
This [Vue.js](https://vuejs.org) application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with [PKCE](/docs/concepts/pkce). Users begin on a public landing page where they can initiate sign-in with Zitadel's authorization server. After successful authentication, the app handles the [OAuth callback](https://zitadel.com/docs/apis/openidoauth/endpoints) and redirects users to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).
|
||||
|
||||
The [zitadel-vue](https://github.com/zitadel/zitadel-vue) repository also includes an Example Application ready to start and show how a Vue application looks like with integrated ZITADEL Login.
|
||||
The application uses [vue-oidc-context](https://www.npmjs.com/package/vue-oidc-context) to wrap authentication logic around [Vue Router](https://router.vuejs.org) navigation guards, automatically protecting routes and ensuring only authenticated users can access sensitive areas. The [withAuthenticationRequired](https://github.com/authts/vue-oidc-context#protecting-routes) higher-order component secures individual routes by checking [session state](https://zitadel.com/docs/concepts/tokens) before rendering protected views.
|
||||
|
||||
What does the Example include:
|
||||
- Home Page with Login Button
|
||||
- Authenticating user with OIDC PKCE Flow
|
||||
- Public Page: Accessible without authentication
|
||||
- Private Page: Shows user information of authenticated user, only accessible after login
|
||||
- Administrator Page: Only accessible after login and with specific administrator role for the application
|
||||
- Logout
|
||||
The example includes secure sign-out functionality implementing **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's [end-session endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#end-session), which terminates both the local application session and the Zitadel session. The app demonstrates proper handling of [refresh tokens](https://zitadel.com/docs/concepts/tokens) using the `offline_access` [scope](https://zitadel.com/docs/apis/openidoauth/scopes), and includes comprehensive [error handling](https://github.com/authts/vue-oidc-context#error-handling) for authentication failures.
|
||||
|
||||
### Step-By-Step Guide
|
||||
---
|
||||
|
||||
The [Step-By-Step Guide](/docs/examples/login/vue) leads you through the whole process from configuring the right application in ZITADEL to a ready application with integrated Login.
|
||||
## Getting started
|
||||
|
||||
After completing the Step-By-Step Guide you will have:
|
||||
1. Example Web Application with integrated ZITADEL Login
|
||||
2. Example page accessible by authenticated user showing retrieved user information
|
||||
3. Example administrator page accessible by user with administrator role
|
||||
4. Logout
|
||||
5. Correct setup for your application in ZITADEL
|
||||
### 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/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/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
|
||||
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/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](https://zitadel.com/docs/guides/integrate/login/oidc/), follow these steps:
|
||||
|
||||
1. Clone the [repository](https://github.com/zitadel/example-auth-vuejs).
|
||||
2. Create a `.env` file in the project root and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/overview):
|
||||
```
|
||||
VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
|
||||
VITE_ZITADEL_CLIENT_ID=your_client_id_from_console
|
||||
VITE_ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
|
||||
VITE_ZITADEL_POST_LOGOUT_URL=http://localhost:3000
|
||||
VITE_POST_LOGIN_URL=/profile
|
||||
```
|
||||
Replace these values with:
|
||||
- Your actual [Zitadel instance URL](https://zitadel.com/docs) (the **Issuer**)
|
||||
- The **Client ID** you copied when creating the application in the [PKCE setup](/docs/guides/integrate/login/oidc/pkce-setup)
|
||||
- The **redirect URI** you configured (must match exactly)
|
||||
- The **post-logout redirect URI** for [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
|
||||
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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/)
|
||||
* **Vue.js documentation:** [https://vuejs.org](https://vuejs.org)
|
||||
* **Vue Router documentation:** [https://router.vuejs.org](https://router.vuejs.org)
|
||||
* **vue-oidc-context (wrapper):** [https://www.npmjs.com/package/vue-oidc-context](https://www.npmjs.com/package/vue-oidc-context)
|
||||
* **oidc-client-ts (primary library):** [https://www.npmjs.com/package/oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)
|
||||
* **oidc-client-ts GitHub:** [https://github.com/authts/oidc-client-ts](https://github.com/authts/oidc-client-ts)
|
||||
* **Example repository:** [https://github.com/zitadel/example-auth-vuejs](https://github.com/zitadel/example-auth-vuejs)
|
||||
* **All framework examples:** [/docs/examples](/docs/examples)
|
||||
|
||||
Reference in New Issue
Block a user