From d7a9e9d48bc5441d3cb5924d16313c1b5feab8ba Mon Sep 17 00:00:00 2001 From: Federico Coppede Date: Sat, 10 Jan 2026 19:42:37 -0300 Subject: [PATCH] docs: fix PKCE broken reference (#11324) This PR fixes the broken reference to the PKCE reference --- .../domain-verification.component.html | 2 +- .../modules/domains/domains.component.html | 2 +- docs/docs/apis/openidoauth/endpoints.mdx | 2 +- docs/docs/concepts/features/actions.md | 2 +- docs/docs/concepts/features/passkeys.md | 2 +- docs/docs/concepts/features/selfservice.md | 2 +- .../docs/examples/secure-api/nodejs-nestjs.md | 2 +- docs/docs/examples/secure-api/pylon.mdx | 2 +- .../examples/secure-api/python-django.mdx | 2 +- .../docs/examples/secure-api/python-flask.mdx | 2 +- .../guides/integrate/back-channel-logout.mdx | 2 +- .../guides/integrate/login/hosted-login.mdx | 2 +- .../login/oidc/authmethods/_pkce.mdx | 2 + .../integrate/services/google-workspace.md | 2 +- docs/docs/guides/integrate/token-exchange.mdx | 2 +- .../manage/console/default-settings.mdx | 2 +- .../guides/manage/console/organizations.mdx | 2 +- .../solution-scenarios/domain-discovery.mdx | 4 +- docs/docs/sdk-examples/astro.mdx | 40 ++++++++--------- docs/docs/sdk-examples/expressjs.mdx | 38 ++++++++-------- docs/docs/sdk-examples/fastify.mdx | 40 ++++++++--------- docs/docs/sdk-examples/hono.mdx | 38 ++++++++-------- docs/docs/sdk-examples/nestjs.mdx | 32 +++++++------- docs/docs/sdk-examples/nuxtjs.mdx | 36 +++++++-------- docs/docs/sdk-examples/qwik.mdx | 40 ++++++++--------- docs/docs/sdk-examples/react.mdx | 40 ++++++++--------- docs/docs/sdk-examples/solidstart.mdx | 44 +++++++++---------- docs/docs/sdk-examples/sveltekit.mdx | 36 +++++++-------- docs/docs/sdk-examples/vue.mdx | 42 +++++++++--------- docs/docs/self-hosting/manage/cache.md | 2 +- 30 files changed, 234 insertions(+), 232 deletions(-) diff --git a/console/src/app/modules/domains/domain-verification/domain-verification.component.html b/console/src/app/modules/domains/domain-verification/domain-verification.component.html index cfd8df365c..f7c435c4b6 100644 --- a/console/src/app/modules/domains/domain-verification/domain-verification.component.html +++ b/console/src/app/modules/domains/domain-verification/domain-verification.component.html @@ -3,7 +3,7 @@

{{ 'ORG.PAGES.ORGDOMAIN.TITLE' | translate: { value: domain?.domainName } }}

{{ 'ORG.DOMAINS.TITLE' | translate }} diff --git a/docs/docs/apis/openidoauth/endpoints.mdx b/docs/docs/apis/openidoauth/endpoints.mdx index 0733f478ee..4eaf109e62 100644 --- a/docs/docs/apis/openidoauth/endpoints.mdx +++ b/docs/docs/apis/openidoauth/endpoints.mdx @@ -398,7 +398,7 @@ curl --request POST \ The Token Exchange grant implements [RFC 8693, OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693) and can be used to exchange tokens to a different scope, audience or subject. Changing the subject of an authenticated token is called impersonation or delegation. ZITADEL also provides a [token exchange guide](/docs/guides/integrate/token-exchange) with more details on using the Token Exchange Grant. :::info -Token Exchange is currently an experimental [beta](/docs/support/software-release-cycles-support#beta) feature. Be sure to enable it on the [feature API](/docs/guides/integrate/token-exchange#feature-api) before using it. +Token Exchange is currently an experimental [beta](https://help.zitadel.com/zitadel-software-release-cycle#beta) feature. Be sure to enable it on the [feature API](/docs/guides/integrate/token-exchange#feature-api) before using it. ::: #### Request parameters diff --git a/docs/docs/concepts/features/actions.md b/docs/docs/concepts/features/actions.md index 6de4dfe0e7..ebd58041df 100644 --- a/docs/docs/concepts/features/actions.md +++ b/docs/docs/concepts/features/actions.md @@ -34,6 +34,6 @@ Within the JavaScript code, you can read and manipulate the state. ## Further reading - [Assign users a role after they register using an external identity provider](/guides/manage/customize/behavior) -- [Actions reference](/guides/manage/console/actions-overview#action) +- [Actions reference](/guides/manage/console/actions-overview) - [Actions Marketplace: Find example actions to use in ZITADEL](https://github.com/zitadel/actions) - [Example use cases](/apis/actions/code-examples) diff --git a/docs/docs/concepts/features/passkeys.md b/docs/docs/concepts/features/passkeys.md index c6232ec433..46fa0d1e43 100644 --- a/docs/docs/concepts/features/passkeys.md +++ b/docs/docs/concepts/features/passkeys.md @@ -26,7 +26,7 @@ Imagine signing in without passwords! Passkeys, replacing traditional passwords, ### Developer Resources * **Documentation:** Passkeys Guide: [https://zitadel.com/docs/guides/integrate/login-ui/passkey](/docs/guides/integrate/login-ui/passkey) -* **Create Passkey Registration Link API:** [https://zitadel.com/docs/guides/manage/user/reg-create-user](/docs/guides/manage/user/reg-create-user) +* [Create Passkey Registration Link API](/docs/guides/manage/user/reg-create-user) ### Notes diff --git a/docs/docs/concepts/features/selfservice.md b/docs/docs/concepts/features/selfservice.md index dbccd090ce..aaf904f68c 100644 --- a/docs/docs/concepts/features/selfservice.md +++ b/docs/docs/concepts/features/selfservice.md @@ -11,7 +11,7 @@ It is important to understand that, depending on your use case, there will exist - `Users` are the end-users of your application. Like with any CIAM solution, users should be able to perform tasks like register/join, update their profile, manage authenticators etc. There are certain actions that can be executed pre-login, yet others require the user to have a valid session. - `Managers` are users with a [special manager role](../../guides/manage/console/managers) within ZITADEL and can perform administrative actions such as system configuration or granting access rights to users. -All self-service interfaces are available in different [languages](/guides/manage/customize/texts#internationalization). +All self-service interfaces are available in different [languages](/guides/manage/customize/texts#internationalization--i18n). :::info ZITADEL covers the typical "CIAM" self-service capabilities as well as delegated access management for multi-tenancy scenarios. Please refer to the section [Managers](#managers). diff --git a/docs/docs/examples/secure-api/nodejs-nestjs.md b/docs/docs/examples/secure-api/nodejs-nestjs.md index 54da814225..72cc1d74cc 100644 --- a/docs/docs/examples/secure-api/nodejs-nestjs.md +++ b/docs/docs/examples/secure-api/nodejs-nestjs.md @@ -25,7 +25,7 @@ Make sure you have Node.js and npm installed on your machine. ### ZITADEL Configuration for the API -1. Create a ZITADEL instance and a project by following the steps [here](/docs/guides/start/quickstart#2-create-your-first-instance). +1. Create a ZITADEL instance and a project by following the steps [here](/docs/guides/start/quickstart#3-create-your-first-instance). 2. Set up an API application within your project: - Create a new application of type "API" with authentication method "Private Key". diff --git a/docs/docs/examples/secure-api/pylon.mdx b/docs/docs/examples/secure-api/pylon.mdx index c8a3cd4635..6d10017c59 100644 --- a/docs/docs/examples/secure-api/pylon.mdx +++ b/docs/docs/examples/secure-api/pylon.mdx @@ -261,7 +261,7 @@ export default app; ### Call the API To call the API you need an access token, which is then verified by ZITADEL. -Please follow [this guide here](/docs/guides/integrate/token-introspection/private-key-jwt#get-an-access-token), ignoring the first step as we already have the `.json`-key-file from the serviceaccount. +Please follow [this guide here](/docs/guides/integrate/token-introspection/private-key-jwt), ignoring the first step as we already have the `.json`-key-file from the serviceaccount. :::info You can also create a PAT for the serviceuser and use it to test the API. For this, follow [this guide](/docs/guides/integrate/service-users/personal-access-token#create-a-service-user-with-a-pat). diff --git a/docs/docs/examples/secure-api/python-django.mdx b/docs/docs/examples/secure-api/python-django.mdx index f571c30f57..bc9be84625 100644 --- a/docs/docs/examples/secure-api/python-django.mdx +++ b/docs/docs/examples/secure-api/python-django.mdx @@ -145,7 +145,7 @@ python manage.py runserver ### Call the API To call the API you need an access token, which is then verified by ZITADEL. -Please follow [this guide here](/docs/guides/integrate/token-introspection/private-key-jwt#get-an-access-token), ignoring the first step as we already have the `.json`-key-file from the serviceaccount. +Please follow [this guide here](/docs/guides/integrate/token-introspection/private-key-jwt), ignoring the first step as we already have the `.json`-key-file from the serviceaccount. Optionally set the token as an environment variable: ``` diff --git a/docs/docs/examples/secure-api/python-flask.mdx b/docs/docs/examples/secure-api/python-flask.mdx index bc99a12733..7616670d9a 100644 --- a/docs/docs/examples/secure-api/python-flask.mdx +++ b/docs/docs/examples/secure-api/python-flask.mdx @@ -31,7 +31,7 @@ In order to run the example you need to have `python3` and `pip3` installed. You need to setup a couple of things in ZITADEL. -1. If you don't have an instance yet, please go ahead and create an instance as explained [here](/docs/guides/start/quickstart#2-create-your-first-instance). Also, create a new project by following the steps [here](/docs/guides/start/quickstart#2-create-your-first-instance). +1. If you don't have an instance yet, please go ahead and create an instance as explained [here](/docs/guides/start/quickstart#3-create-your-first-instance). Also, create a new project by following the steps [here](/docs/guides/start/quickstart#4-create-your-first-project-and-app). 2. You must create an API application in your project. Follow [this guide](/docs/guides/manage/console/applications-overview) to create a new application of type "API" with authentication method "Basic". Save both the ClientID and ClientSecret after you create the application. diff --git a/docs/docs/guides/integrate/back-channel-logout.mdx b/docs/docs/guides/integrate/back-channel-logout.mdx index 6f635320bb..4c2bfb6c29 100644 --- a/docs/docs/guides/integrate/back-channel-logout.mdx +++ b/docs/docs/guides/integrate/back-channel-logout.mdx @@ -8,7 +8,7 @@ and can be used to notify clients about session termination at the OpenID Provid back-channel logout is implemented inside ZITADEL and gives some usage examples. :::info -Back-Channel Logout is currently an experimental [beta](/docs/support/software-release-cycles-support#beta) feature. +Back-Channel Logout is currently an experimental [beta](https://help.zitadel.com/zitadel-software-release-cycle#beta) feature. Be sure to enable it on the [feature API](#feature-api) before using it. We highly recommend also enabling the `webkey` feature on your instance. This will prevent issues with automatic key rotation. ::: diff --git a/docs/docs/guides/integrate/login/hosted-login.mdx b/docs/docs/guides/integrate/login/hosted-login.mdx index 7daf98d352..9b9e3f432b 100644 --- a/docs/docs/guides/integrate/login/hosted-login.mdx +++ b/docs/docs/guides/integrate/login/hosted-login.mdx @@ -38,7 +38,7 @@ Overall, ZITADEL's hosted login page simplifies the authentication process for d ### Flexible usernames Different login name formats can be used on ZITADEL's hosted login page to select a user. -Login methods can be a user's username, containing the username and an [organization domain](/docs/guides/manage/console/organizations#domain-verification-and-primary-domain), their email addresses, or their phone numbers. +Login methods can be a user's username, containing the username and an [organization domain](/docs/guides/manage/console/organizations-overview#usernames-and-domains), their email addresses, or their phone numbers. By default, all of these login methods are allowed and can be adjusted by [Managers](/docs/concepts/structure/managers) to meet their requirements. ### Support for multiple authentication methods diff --git a/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx b/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx index ea1a2522d2..ad502e753a 100644 --- a/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx +++ b/docs/docs/guides/integrate/login/oidc/authmethods/_pkce.mdx @@ -19,6 +19,8 @@ on /authorize with at least the following parameters: We recommend always using two additional parameters `state` and `nonce`. The former enables you to transfer a state through the authentication process. The latter is used to bind the client session with the id_token and to mitigate replay attacks. +### PKCE + PKCE stands for Proof Key for Code Exchange. So other than "normal" code exchange, the PKCE does not authenticate using client_id and client_secret but an additional code. You will have to generate a random string, hash it and send this hash on the authorization_endpoint. On the token_endpoint you will then send the plain string for the authorization to compute diff --git a/docs/docs/guides/integrate/services/google-workspace.md b/docs/docs/guides/integrate/services/google-workspace.md index b2f4444481..18b3647e01 100644 --- a/docs/docs/guides/integrate/services/google-workspace.md +++ b/docs/docs/guides/integrate/services/google-workspace.md @@ -21,7 +21,7 @@ At this time Google supports SSO with OpenID Connect only for few providers. Prerequisites: - You need to have a domain registered with your Google Workspace account to configure SSO profiles -- Make sure that you [verify the same domain also in your ZITADEL organization and set it as primary domain](/docs/guides/manage/console/organizations#domain-verification-and-primary-domain) +- Make sure that you [verify the same domain also in your ZITADEL organization and set it as primary domain](/docs/guides/manage/console/organizations-overview#primary-domain) - A user in Google Workspace (eg, road.runner@acme.com) - A user in ZITADEL with the same username (eg, road.runner@acme.com); make sure you verify the domain to set the username. This is different than the user's email address diff --git a/docs/docs/guides/integrate/token-exchange.mdx b/docs/docs/guides/integrate/token-exchange.mdx index 663fae5533..fcb58c20fd 100644 --- a/docs/docs/guides/integrate/token-exchange.mdx +++ b/docs/docs/guides/integrate/token-exchange.mdx @@ -10,7 +10,7 @@ import TokenExchangeResponse from "../../apis/openidoauth/_token_exchange_respon The Token Exchange grant implements [RFC 8693, OAuth 2.0 Token Exchange](https://www.rfc-editor.org/rfc/rfc8693) and can be used to exchange tokens to a different scope, audience or subject. Changing the subject of an authenticated token is called impersonation or delegation. This guide will explain how token exchange is implemented inside ZITADEL and gives some usage examples. :::info -Token Exchange is currently an [experimental beta](/docs/support/software-release-cycles-support#beta) feature. Be sure to enable it on the [feature API](#feature-api) before using it. +Token Exchange is currently an [experimental beta](https://help.zitadel.com/zitadel-software-release-cycle#beta) feature. Be sure to enable it on the [feature API](#feature-api) before using it. Test the feature and add improvement or bug reports directly to the [github repository](https://github.com/zitadel/zitadel) or let us know your general feedback in the [discord thread](https://discord.com/channels/927474939156643850/1333448892083208262)! ::: diff --git a/docs/docs/guides/manage/console/default-settings.mdx b/docs/docs/guides/manage/console/default-settings.mdx index 448596c717..9df60e8b99 100644 --- a/docs/docs/guides/manage/console/default-settings.mdx +++ b/docs/docs/guides/manage/console/default-settings.mdx @@ -272,7 +272,7 @@ If you enable this setting, all loginnames will be suffixed with the organizatio If this is enabled all created domains on an organization must be verified per dns/acme challenge. -More about how to verify a domain [here](/guides/manage/console/organizations#domain-verification-and-primary-domain). +More about how to verify a domain [here](/guides/manage/console/organizations-overview#domain-verification-guide). If it is set to false, all registered domain will automatically be created as verified and the users will be able to use the domain for login. ### SMTP Sender Address matches Custom Domain diff --git a/docs/docs/guides/manage/console/organizations.mdx b/docs/docs/guides/manage/console/organizations.mdx index 47ce2a7fd3..2b41fb2727 100644 --- a/docs/docs/guides/manage/console/organizations.mdx +++ b/docs/docs/guides/manage/console/organizations.mdx @@ -109,7 +109,7 @@ Those settings are the same as your default settings. - [**Identity Providers**](./default-settings#identity-providers): Define IDPs which are available for all organizations - [**Password Complexity**](./default-settings#password-complexity): Requirements for Passwords ex. Symbols, Numbers, min length and more. - [**Lockout**](./default-settings#lockout): Set the maximum attempts a user can try to enter the password or any (T)OTP method. When the number is exceeded, the user gets locked out and has to be unlocked. -- [**Verified domains**](/docs/guides/manage/console/organizations#verify-your-domain-name): This is where you manage your organization specific domains which can be used to build usernames +- [**Verified domains**](/docs/guides/manage/console/organizations-overview#usernames-and-domains): This is where you manage your organization specific domains which can be used to build usernames - [**Domain settings**](./default-settings#domain-settings): Whether users use their email or the generated username to login. Other Validation, SMTP settings - [**Branding**](./default-settings#branding): Appearance of the login interface. - [**Message Texts**](./default-settings#message-texts): Text and internationalization for emails diff --git a/docs/docs/guides/solution-scenarios/domain-discovery.mdx b/docs/docs/guides/solution-scenarios/domain-discovery.mdx index 712833f06d..701029f2ab 100644 --- a/docs/docs/guides/solution-scenarios/domain-discovery.mdx +++ b/docs/docs/guides/solution-scenarios/domain-discovery.mdx @@ -36,7 +36,7 @@ You can also configure these settings on the default organization (see below) an ### Default Organization -Set **CIAM** as [default organization](/docs/guides/manage/console/organizations#default-organization). +Set **CIAM** as [default organization](/docs/guides/manage/console/organizations-overview#default-organization). You will find the overview of all organizations under the "Organizations" tab on the Default Settings. The default organization will hold all unmatched users, ie. all users that are not specifically in the organizations **Alpha** or **Beta** in the example. @@ -89,7 +89,7 @@ Make sure to [Force MFA](/docs/guides/manage/console/default-settings#multifacto ### Verify domains Switch to the organization **Alpha** and navigate to the settings and "Verified domains". -Verify the domain alpha.com following the [organization guide](/docs/guides/manage/console/organizations#domain-verification-and-primary-domain). +Verify the domain alpha.com following the [organization guide](/docs/guides/manage/console/organizations-overview#usernames-and-domains). Do the same for the **Beta** organization. diff --git a/docs/docs/sdk-examples/astro.mdx b/docs/docs/sdk-examples/astro.mdx index e4f2927ab4..15fc86bbb2 100644 --- a/docs/docs/sdk-examples/astro.mdx +++ b/docs/docs/sdk-examples/astro.mdx @@ -11,21 +11,21 @@ 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. +[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/guides/integrate/login/oidc/login-users#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. +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/guides/integrate/login/oidc/login-users#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). +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/guides/integrate/login/oidc/login-users#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). +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](/guides/manage/console/organizations-overview), and [role assignments](https://zitadel.com/docs/guides/manage/console/roles). --- @@ -33,22 +33,22 @@ The application includes complete [logout functionality](https://zitadel.com/doc ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#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/console-overview) if you're using HTTP URLs during local development. For production deployments, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/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/console-overview). Use these environment variable names exactly as shown: +2. Create a `.env` file based on `.env.example` and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). Use these environment variable names exactly as shown: ``` PORT=4321 SESSION_DURATION=3600 @@ -73,14 +73,14 @@ Once you have your [Zitadel application configured](https://zitadel.com/docs/gui ## 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) +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [Astro documentation](https://astro.build) +* [Auth.js documentation](https://authjs.dev) +* [@auth/core package](https://www.npmjs.com/package/@auth/core) +* [auth-astro adapter](https://www.npmjs.com/package/auth-astro) +* [Example repository](https://github.com/zitadel/example-auth-astro) +* [All framework examples](/docs/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/expressjs.mdx b/docs/docs/sdk-examples/expressjs.mdx index b825b32692..fd3382f460 100644 --- a/docs/docs/sdk-examples/expressjs.mdx +++ b/docs/docs/sdk-examples/expressjs.mdx @@ -11,17 +11,17 @@ 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. +[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/guides/integrate/login/oidc/login-users#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. +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/guides/integrate/login/oidc/login-users#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). +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/guides/integrate/login/oidc/login-users#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. @@ -33,22 +33,22 @@ Sign-out functionality implements **[federated logout](https://zitadel.com/docs/ ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/console-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#pkce) 3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development) 4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`) 5. Copy your **Client ID** for use in the next steps -> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your [Zitadel application configured](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/console-overview). Use the exact environment variable names from the repository: +2. Create a `.env.local` file and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). Use the exact environment variable names from the repository: ``` NODE_ENV=development PORT=3000 @@ -62,7 +62,7 @@ Once you have your [Zitadel application configured](https://zitadel.com/docs/gui 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)) + - Your actual Zitadel instance URL (the **Issuer** from the [PKCE setup guide](/docs/guides/manage/console/applications-overview)) - 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) @@ -79,13 +79,13 @@ 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 +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](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/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/fastify.mdx b/docs/docs/sdk-examples/fastify.mdx index 5b6e868d22..834893e210 100644 --- a/docs/docs/sdk-examples/fastify.mdx +++ b/docs/docs/sdk-examples/fastify.mdx @@ -11,17 +11,17 @@ 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. +[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/guides/integrate/login/oidc/login-users#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. +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/guides/integrate/login/oidc/login-users#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. +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/guides/integrate/login/oidc/login-users#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). @@ -33,23 +33,23 @@ The application also demonstrates proper **[federated logout](https://zitadel.co ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [ZITADEL project](https://zitadel.com/docs/guides/manage/console/projects-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#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/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [ZITADEL application](https://zitadel.com/docs/guides/integrate/login/oidc/) configured: +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/console-overview). **Use these exact environment variable names:** +2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). **Use these exact environment variable names:** ``` NODE_ENV=development PORT=3000 @@ -63,7 +63,7 @@ Once you have your [ZITADEL application](https://zitadel.com/docs/guides/integra ZITADEL_POST_LOGOUT_URL=http://localhost:3000 ``` Replace these values with: - - Your actual [ZITADEL instance URL](https://zitadel.com/docs/guides/manage/console/console-overview) for `ZITADEL_DOMAIN` (the issuer) + - Your actual [ZITADEL instance URL](/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` @@ -74,13 +74,13 @@ Once you have your [ZITADEL application](https://zitadel.com/docs/guides/integra ## 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 +* [ZITADEL documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](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/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/hono.mdx b/docs/docs/sdk-examples/hono.mdx index 2db6aefa39..b989f5ab2b 100644 --- a/docs/docs/sdk-examples/hono.mdx +++ b/docs/docs/sdk-examples/hono.mdx @@ -11,17 +11,17 @@ status: stable ## Overview -[Hono](https://hono.dev) is a small, simple, and ultra fast 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. +[Hono](https://hono.dev) is a small, simple, and ultra fast 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/guides/integrate/login/oidc/login-users#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)**. +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/guides/integrate/login/oidc/login-users#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. +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/guides/integrate/login/oidc/login-users#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/guides/integrate/login/oidc/login-users#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. @@ -31,22 +31,22 @@ The implementation uses [Handlebars templates](https://handlebarsjs.com/) for se ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#pkce) 3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development) 4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`) 5. Copy your **Client ID** for use in the next steps -> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your Zitadel application configured: 1. Clone the [repository](https://github.com/zitadel/example-auth-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/console-overview). **Use the exact environment variable names from the repository:** +2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). **Use the exact environment variable names from the repository:** ``` NODE_ENV=development PORT=3000 @@ -80,14 +80,14 @@ The application will be running at `http://localhost:3000`. Visit the homepage t ## 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) +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](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) +* [Auth.js](https://authjs.dev) +* [Auth.js Hono adapter](https://www.npmjs.com/package/@hono/auth-js) +* [Example repository](https://github.com/zitadel/example-auth-hono) +* [All framework examples](/docs/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/nestjs.mdx b/docs/docs/sdk-examples/nestjs.mdx index 55c26188d2..0ce29b4b82 100644 --- a/docs/docs/sdk-examples/nestjs.mdx +++ b/docs/docs/sdk-examples/nestjs.mdx @@ -11,17 +11,17 @@ status: stable ## 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. +[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/guides/integrate/login/oidc/login-users#pkce)** to authenticate users securely and maintain sessions across your NestJS application. #### Auth library -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. +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/guides/integrate/login/oidc/login-users#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. --- ## What this example demonstrates -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). +This example implements a complete authentication flow using [PKCE](/docs/guides/integrate/login/oidc/login-users#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). 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. @@ -35,10 +35,10 @@ All protected routes are secured using the [@mridang/nestjs-auth global guard](h ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: 1. Create a new Web application in your Zitadel project -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#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 @@ -50,7 +50,7 @@ Before running this example, you need to create and configure a PKCE application 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/console-overview). **Use the exact environment variable names from the repository:** +2. Create a `.env` file in the project root and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). **Use the exact environment variable names from the repository:** ``` NODE_ENV=development PORT=3000 @@ -85,13 +85,13 @@ Once you have your Zitadel application configured: ## 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) +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [Framework docs](https://nestjs.com) +* [Auth library (@auth/core)](https://www.npmjs.com/package/@auth/core) +* [NestJS auth module](https://www.npmjs.com/package/@mridang/nestjs-auth) +* [Example repository](https://github.com/zitadel/example-auth-nestjs) +* [All framework examples](/docs/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/nuxtjs.mdx b/docs/docs/sdk-examples/nuxtjs.mdx index 4c739bf68e..f52391cee8 100644 --- a/docs/docs/sdk-examples/nuxtjs.mdx +++ b/docs/docs/sdk-examples/nuxtjs.mdx @@ -11,17 +11,17 @@ 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. +[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/guides/integrate/login/oidc/login-users#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). +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/guides/integrate/login/oidc/login-users#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). +This [Nuxt.js](https://nuxt.com) application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with the **[PKCE flow](/docs/guides/integrate/login/oidc/login-users#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. @@ -31,10 +31,10 @@ The example implements secure [session management](https://zitadel.com/docs/conc ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#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 @@ -46,7 +46,7 @@ Before running this example, you need to create and configure a PKCE application 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/console-overview). **Use these exact environment variable names:** +2. Create a `.env` file and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). **Use these exact environment variable names:** ``` PORT=3000 SESSION_DURATION=3600 @@ -59,7 +59,7 @@ Once you have your Zitadel application configured: 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/console-overview)) + - Your actual Zitadel instance URL (the **Issuer** from your [ZITADEL instance settings](/docs/guides/manage/console/console-overview#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) @@ -76,13 +76,13 @@ The application will be running at `http://localhost:3000` where you can test th ## 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) +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [Framework docs](https://nuxt.com) +* [@sidebase/nuxt-auth](https://www.npmjs.com/package/@sidebase/nuxt-auth) +* [NextAuth.js/Auth.js](https://next-auth.js.org) +* [Example repository](https://github.com/zitadel/example-auth-nuxtjs) +* [All framework examples](/docs/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/qwik.mdx b/docs/docs/sdk-examples/qwik.mdx index b783028b77..b8627e5fcb 100644 --- a/docs/docs/sdk-examples/qwik.mdx +++ b/docs/docs/sdk-examples/qwik.mdx @@ -11,19 +11,19 @@ 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. +[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/guides/integrate/login/oidc/login-users#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. +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/guides/integrate/login/oidc/login-users#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. +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/guides/integrate/login/oidc/login-users#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-overview) and [project roles](https://zitadel.com/docs/guides/manage/console/projects-overview). +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](/docs/guides/manage/console/organizations-overview) and [project roles](/docs/guides/manage/console/projects-overview). 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. @@ -33,22 +33,22 @@ Sign-out functionality implements **[federated logout](https://zitadel.com/docs/ ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#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/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [Zitadel application](https://zitadel.com/docs/guides/integrate/login/oidc/) configured: +Once you have your [ZITADEL Application](/docs/guides/manage/console/applications-overview) 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/console-overview): +2. Create a `.env.local` file and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview): ``` VITE_PORT=3000 VITE_SESSION_SECRET=your-very-secret-and-strong-session-key @@ -78,13 +78,13 @@ 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 +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](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/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/react.mdx b/docs/docs/sdk-examples/react.mdx index 2e474a3ccb..9962f0789a 100644 --- a/docs/docs/sdk-examples/react.mdx +++ b/docs/docs/sdk-examples/react.mdx @@ -11,17 +11,17 @@ status: stable ## Overview -[React](https://react.dev) is a JavaScript library for building user interfaces with component composition, declarative views, 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 React application. +[React](https://react.dev) is a JavaScript library for building user interfaces with component composition, declarative views, and a rich ecosystem. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](/docs/guides/integrate/login/oidc/login-users#pkce)** to authenticate users securely and maintain sessions across your React application. #### Auth library -This example uses **[react-oidc-context](https://www.npmjs.com/package/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**. The underlying [oidc-client-ts](https://github.com/authts/oidc-client-ts) library implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manages [PKCE](/docs/concepts/pkce) code challenge generation, performs secure [token exchange](https://zitadel.com/docs/concepts/tokens), and exposes React hooks for managing authentication state throughout your application. +This example uses **[react-oidc-context](https://www.npmjs.com/package/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**. The underlying [oidc-client-ts](https://github.com/authts/oidc-client-ts) library implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manages [PKCE](/docs/guides/integrate/login/oidc/login-users#pkce) code challenge generation, performs secure [token exchange](https://zitadel.com/docs/concepts/tokens), and exposes React hooks for managing authentication state throughout your application. --- ## What this example demonstrates -This [React](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](/docs/concepts/pkce) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://www.npmjs.com/package/react-oidc-context), which redirects them to [Zitadel's authorization endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints) for authentication. After successful authentication, the application handles the OAuth callback, exchanges the authorization code for [access tokens](https://zitadel.com/docs/concepts/tokens), and establishes a secure [session](https://zitadel.com/docs/apis/openidoauth/endpoints). +This [React](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](/docs/guides/integrate/login/oidc/login-users#pkce) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://www.npmjs.com/package/react-oidc-context), which redirects them to [Zitadel's authorization endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints) for authentication. After successful authentication, the application handles the OAuth callback, exchanges the authorization code for [access tokens](https://zitadel.com/docs/concepts/tokens), and establishes a secure [session](https://zitadel.com/docs/apis/openidoauth/endpoints). Protected routes are secured using [react-oidc-context's](https://www.npmjs.com/package/react-oidc-context) `withAuthenticationRequired` higher-order component, which automatically redirects unauthenticated users to the login flow. The profile page displays user information retrieved from [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims), including profile details, email, and metadata. The application implements complete [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) functionality, properly terminating both the local session and the Zitadel session through the end-session endpoint. @@ -33,22 +33,22 @@ The example leverages [React Router](https://reactrouter.com) for client-side na ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/integrate/login/oidc/) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#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 -> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your Zitadel application configured: 1. Clone the [repository](https://github.com/zitadel/example-auth-react). -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/console-overview). **Use these exact environment variable names:** +2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). **Use these exact environment variable names:** ``` VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud VITE_ZITADEL_CLIENT_ID=your_client_id_from_console @@ -60,7 +60,7 @@ VITE_PORT=3000 Replace these values with: - Your actual Zitadel instance URL (the **Issuer** from your [Zitadel application settings](https://zitadel.com/docs/guides/integrate/login/oidc/)) - The **Client ID** you copied when creating the application -- The **redirect URI** you configured in the [PKCE setup](/docs/guides/integrate/login/oidc/pkce-setup) (must match exactly) +- The **redirect URI** you configured in the [PKCE setup](/docs/guides/manage/console/applications-overview) (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 @@ -74,14 +74,14 @@ The application will be running at `http://localhost:3000` where you can test th ## 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/) -* **React documentation:** https://react.dev -* **react-oidc-context:** https://www.npmjs.com/package/react-oidc-context -* **oidc-client-ts:** https://www.npmjs.com/package/oidc-client-ts -* **React Router:** https://reactrouter.com -* **Example repository:** https://github.com/zitadel/example-auth-react -* **All framework examples:** /docs/examples +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [React documentation](https://react.dev) +* [react-oidc-context](https://www.npmjs.com/package/react-oidc-context) +* [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) +* [React Router](https://reactrouter.com) +* [Example repository](https://github.com/zitadel/example-auth-react) +* [All framework examples](/docs/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/solidstart.mdx b/docs/docs/sdk-examples/solidstart.mdx index cd7c152f05..ec69f2fd03 100644 --- a/docs/docs/sdk-examples/solidstart.mdx +++ b/docs/docs/sdk-examples/solidstart.mdx @@ -11,17 +11,17 @@ 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/guides/manage/console/default-settings#login-lifetimes) across the app. +[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/guides/integrate/login/oidc/login-users#pkce)** to authenticate users securely and maintain [sessions](/docs/guides/manage/console/default-settings#login-lifetimes) 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/guides/manage/console/default-settings#login-lifetimes). 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. +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/guides/integrate/login/oidc/login-users#pkce), performs [token exchange](https://zitadel.com/docs/apis/openidoauth/grant-types), and exposes helpers for [session state](/docs/guides/manage/console/default-settings#login-lifetimes). 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/guides/manage/console/default-settings#login-lifetimes) 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). +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/guides/integrate/login/oidc/login-users#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](/docs/guides/manage/console/default-settings#login-lifetimes) 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. @@ -31,22 +31,22 @@ The application implements automatic [token refresh](https://zitadel.com/docs/ap ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#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/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [Zitadel application](https://zitadel.com/docs/guides/integrate/login/oidc/) configured: +Once you have your [ZITADEL Application](/docs/guides/manage/console/applications-overview) 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/console-overview). Use the exact environment variable names from the repository: +2. Create a `.env` file and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). Use the exact environment variable names from the repository: ``` NODE_ENV=development PORT=3000 @@ -62,7 +62,7 @@ Once you have your [Zitadel application](https://zitadel.com/docs/guides/integra ``` 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 **Client ID** you copied when [creating the application](/docs/guides/manage/console/applications-overview) - 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 @@ -76,15 +76,15 @@ Once you have your [Zitadel application](https://zitadel.com/docs/guides/integra ## 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 +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [SolidStart documentation](https://start.solidjs.com) +* [Auth.js documentation](https://authjs.dev) +* [@auth/solid-start](https://www.npmjs.com/package/@auth/solid-start) +* [@auth/core](https://www.npmjs.com/package/@auth/core) +* [openid-client](https://www.npmjs.com/package/openid-client) +* [Example repository](https://github.com/zitadel/example-auth-solidstart) +* [All framework examples](/docs/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/sveltekit.mdx b/docs/docs/sdk-examples/sveltekit.mdx index cc9d33144a..a06a80429b 100644 --- a/docs/docs/sdk-examples/sveltekit.mdx +++ b/docs/docs/sdk-examples/sveltekit.mdx @@ -11,17 +11,17 @@ 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. +[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/guides/integrate/login/oidc/login-users#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. +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/guides/integrate/login/oidc/login-users#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). +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/guides/integrate/login/oidc/login-users#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. @@ -33,22 +33,22 @@ The logout flow implements **[federated logout](https://zitadel.com/docs/guides/ ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#pkce) 3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development) 4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`) 5. Copy your **Client ID** for use in the next steps -> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your Zitadel application configured: 1. Clone the [repository](https://github.com/zitadel/example-auth-sveltekit). -2. Create a `.env.local` file in the project root and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/console-overview). **Use these exact environment variable names:** +2. Create a `.env.local` file in the project root and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview). **Use these exact environment variable names:** ``` SESSION_SECRET=your-very-secret-and-strong-session-key SESSION_DURATION=3600 @@ -77,13 +77,13 @@ Once you have your Zitadel application configured: ## 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) +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [SvelteKit documentation](https://kit.svelte.dev) +* [Auth.js (SvelteKit)](https://www.npmjs.com/package/@auth/sveltekit) +* [Auth.js Core](https://www.npmjs.com/package/@auth/core) +* [Example repository](https://github.com/zitadel/example-auth-sveltekit) +* [All framework examples](/docs/sdk-examples/introduction) diff --git a/docs/docs/sdk-examples/vue.mdx b/docs/docs/sdk-examples/vue.mdx index 9061bbd45d..be21013c95 100644 --- a/docs/docs/sdk-examples/vue.mdx +++ b/docs/docs/sdk-examples/vue.mdx @@ -11,17 +11,17 @@ status: stable ## Overview -[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.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/guides/integrate/login/oidc/login-users#pkce)** to authenticate users securely and maintain sessions across your Vue.js application. #### Auth library -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. +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/guides/integrate/login/oidc/login-users#pkce), performs [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints), and exposes helpers for [session state](https://zitadel.com/docs/concepts/tokens) management. --- ## What this example demonstrates -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). +This [Vue.js](https://vuejs.org) application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with [PKCE](/docs/guides/integrate/login/oidc/login-users#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 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. @@ -33,22 +33,22 @@ The example includes secure sign-out functionality implementing **[federated log ### Prerequisites -Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/console-overview). Follow the **[PKCE Application Setup guide](/docs/guides/integrate/login/oidc/pkce-setup)** to: +Before running this example, you need to create and configure a PKCE application in the [ZITADEL Console](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: -1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/console-overview) -2. Configure it to use the [PKCE authentication method](/docs/concepts/pkce) +1. Create a new Web application in your [ZITADEL Project](/docs/guides/manage/console/projects-overview) +2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#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/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Console](/docs/guides/manage/console/console-overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your [Zitadel application configured](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/console-overview): +2. Create a `.env` file in the project root and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-overview): ``` VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud VITE_ZITADEL_CLIENT_ID=your_client_id_from_console @@ -58,7 +58,7 @@ 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 **Client ID** you copied when creating the application in the [PKCE setup](/docs/guides/manage/console/applications-overview) - 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: @@ -71,15 +71,15 @@ 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) +* [Zitadel documentation](https://zitadel.com/docs) +* [PKCE concept](/docs/guides/integrate/login/oidc/login-users#pkce) +* [PKCE application setup](/docs/guides/manage/console/applications-overview) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [Vue.js documentation](https://vuejs.org) +* [Vue Router documentation](https://router.vuejs.org) +* [vue-oidc-context (wrapper)](https://www.npmjs.com/package/vue-oidc-context) +* [oidc-client-ts (primary library)](https://www.npmjs.com/package/oidc-client-ts) +* [oidc-client-ts GitHub](https://github.com/authts/oidc-client-ts) +* [Example repository](https://github.com/zitadel/example-auth-vuejs) +* [All framework examples](/docs/sdk-examples/introduction) diff --git a/docs/docs/self-hosting/manage/cache.md b/docs/docs/self-hosting/manage/cache.md index 6feb8be778..484aad048e 100644 --- a/docs/docs/self-hosting/manage/cache.md +++ b/docs/docs/self-hosting/manage/cache.md @@ -6,7 +6,7 @@ sidebar_label: Caches [Beta] ZITADEL supports the use of a caches to speed up the lookup of frequently needed objects. As opposed to HTTP caches which might reside between ZITADEL and end-user applications, the cache build into ZITADEL uses active invalidation when an object gets updated. Another difference is that HTTP caches only cache the result of a complete request and the built-in cache stores objects needed for the internal business logic. For example, each request made to ZITADEL needs to retrieve and set [instance](/docs/concepts/structure/instance) information in middleware. :::info -Caches is currently an [experimental beta](/docs/support/software-release-cycles-support#beta) feature. +Caches is currently an [experimental beta](https://help.zitadel.com/zitadel-software-release-cycle#beta) feature. Test the feature and add improvement or bug reports directly to the [github repository](https://github.com/zitadel/zitadel) or let us know your general feedback in the [discord thread](https://discord.com/channels/927474939156643850/1332343909900222506)! :::