From ee17b7a07409d8abcd8aee22d852f7e5c64f780b Mon Sep 17 00:00:00 2001 From: Mridang Agarwalla Date: Tue, 4 Nov 2025 11:20:38 +0700 Subject: [PATCH] docs: added the docs for the missing examples (#11005) # 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 --- docs/docs/sdk-examples/astro.mdx | 86 +++++++++++++++++++ docs/docs/sdk-examples/expressjs.mdx | 91 ++++++++++++++++++++ docs/docs/sdk-examples/fastify.mdx | 86 +++++++++++++++++++ docs/docs/sdk-examples/hono.mdx | 93 ++++++++++++++++++++ docs/docs/sdk-examples/nestjs.mdx | 117 +++++++++++++++++--------- docs/docs/sdk-examples/nuxtjs.mdx | 88 +++++++++++++++++++ docs/docs/sdk-examples/qwik.mdx | 90 ++++++++++++++++++++ docs/docs/sdk-examples/solidstart.mdx | 90 ++++++++++++++++++++ docs/docs/sdk-examples/sveltekit.mdx | 89 ++++++++++++++++++++ docs/docs/sdk-examples/vue.mdx | 111 ++++++++++++++---------- 10 files changed, 859 insertions(+), 82 deletions(-) create mode 100644 docs/docs/sdk-examples/astro.mdx create mode 100644 docs/docs/sdk-examples/expressjs.mdx create mode 100644 docs/docs/sdk-examples/fastify.mdx create mode 100644 docs/docs/sdk-examples/hono.mdx create mode 100644 docs/docs/sdk-examples/nuxtjs.mdx create mode 100644 docs/docs/sdk-examples/qwik.mdx create mode 100644 docs/docs/sdk-examples/solidstart.mdx create mode 100644 docs/docs/sdk-examples/sveltekit.mdx diff --git a/docs/docs/sdk-examples/astro.mdx b/docs/docs/sdk-examples/astro.mdx new file mode 100644 index 00000000000..8b31c15d826 --- /dev/null +++ b/docs/docs/sdk-examples/astro.mdx @@ -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) diff --git a/docs/docs/sdk-examples/expressjs.mdx b/docs/docs/sdk-examples/expressjs.mdx new file mode 100644 index 00000000000..16dd3829469 --- /dev/null +++ b/docs/docs/sdk-examples/expressjs.mdx @@ -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 diff --git a/docs/docs/sdk-examples/fastify.mdx b/docs/docs/sdk-examples/fastify.mdx new file mode 100644 index 00000000000..316fc43a381 --- /dev/null +++ b/docs/docs/sdk-examples/fastify.mdx @@ -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 diff --git a/docs/docs/sdk-examples/hono.mdx b/docs/docs/sdk-examples/hono.mdx new file mode 100644 index 00000000000..fd1589f1017 --- /dev/null +++ b/docs/docs/sdk-examples/hono.mdx @@ -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) diff --git a/docs/docs/sdk-examples/nestjs.mdx b/docs/docs/sdk-examples/nestjs.mdx index 9238d823f78..06c04560e28 100644 --- a/docs/docs/sdk-examples/nestjs.mdx +++ b/docs/docs/sdk-examples/nestjs.mdx @@ -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 --- - - - - - -
- nest js logo - - NestJS 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 zitadel-nodejs-nestjs Example. -
+## 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) \ No newline at end of file +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) diff --git a/docs/docs/sdk-examples/nuxtjs.mdx b/docs/docs/sdk-examples/nuxtjs.mdx new file mode 100644 index 00000000000..dd63c1c4f3e --- /dev/null +++ b/docs/docs/sdk-examples/nuxtjs.mdx @@ -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) diff --git a/docs/docs/sdk-examples/qwik.mdx b/docs/docs/sdk-examples/qwik.mdx new file mode 100644 index 00000000000..26c6c2ae668 --- /dev/null +++ b/docs/docs/sdk-examples/qwik.mdx @@ -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 diff --git a/docs/docs/sdk-examples/solidstart.mdx b/docs/docs/sdk-examples/solidstart.mdx new file mode 100644 index 00000000000..a17b50f9e34 --- /dev/null +++ b/docs/docs/sdk-examples/solidstart.mdx @@ -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 diff --git a/docs/docs/sdk-examples/sveltekit.mdx b/docs/docs/sdk-examples/sveltekit.mdx new file mode 100644 index 00000000000..1f21bdbbc53 --- /dev/null +++ b/docs/docs/sdk-examples/sveltekit.mdx @@ -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) diff --git a/docs/docs/sdk-examples/vue.mdx b/docs/docs/sdk-examples/vue.mdx index 237b4c64a68..f7aa876ce22 100644 --- a/docs/docs/sdk-examples/vue.mdx +++ b/docs/docs/sdk-examples/vue.mdx @@ -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 --- - - - - - -
- vue - - Vue.js 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 zitadel-vue SDK -
+## 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 -![View Example App](/img/vue/app-screen.png) +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)