diff --git a/docs/docs/sdk-examples/angular.mdx b/docs/docs/sdk-examples/angular.mdx index 5211a8494..44d24895e 100644 --- a/docs/docs/sdk-examples/angular.mdx +++ b/docs/docs/sdk-examples/angular.mdx @@ -1,51 +1,80 @@ --- title: Angular sidebar_label: Angular +framework_url: https://angular.dev +auth_library: "@edgeflare/ngx-oidc" +auth_library_url: https://www.npmjs.com/package/@edgeflare/ngx-oidc +example_repo: https://github.com/zitadel/example-auth-angular +auth_flow: pkce +status: stable --- - - - - - -
- angular logo - - Angular is a popular JavaScript framework for building single-page applications (SPAs) that is known for its two-way data binding, dependency injection, and modular architecture. - Integrate authentication to your Angular application easily by using the zitadel-angular Example. -
+## Overview -### Resources -- [Angular Example Application with ZITADEL Login](https://github.com/zitadel/zitadel-angular) -- [Step-By-Step Guide](/docs/examples/login/angular) -- [ZITADEL Console](https://github.com/zitadel/zitadel/tree/main/console) is built with Angular and can also be used as a reference +[Angular](https://angular.dev) is a TypeScript-based framework for building web applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your Angular application. +#### Auth library -### Angular SDK +This example uses **[@edgeflare/ngx-oidc](https://www.npmjs.com/package/@edgeflare/ngx-oidc)** (built on **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**) to implement the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manage [PKCE](https://oauth.net/2/pkce/) code challenge generation, perform secure token exchange, and provide session management helpers. -ZITADEL does not provide an Angular specific SDK. -But you can integrate ZITADEL to your application by using any OIDC Library such as [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc). +--- -Check out our [Example Application](/docs/sdk-examples/angular#example-application) +## What this example demonstrates -### Example Application +This Angular application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with [PKCE](https://oauth.net/2/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 and redirects users to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims). -The [zitadel-angular](https://github.com/zitadel/zitadel-angular) repository includes an Example Application ready to start and show how an Angular application looks like with integrated ZITADEL Login. +The application integrates authentication logic into Angular routing: protected routes use router guards to automatically redirect unauthenticated users to the sign-in flow, and callback routes complete the PKCE exchange and restore session state. The example requests standard OIDC scopes (`openid`, `profile`, `email`), `offline_access` for refresh tokens, and Zitadel-specific scopes for metadata and role information. -What does the Example include: -- Home Page with Login Button -- Authenticating user with OIDC PKCE Flow -- Private Page: Shows user information of authenticated user, only accessible after login -- Logout +The example includes secure sign-out functionality implementing **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's end-session endpoint, which terminates both the local application session and the Zitadel session, then redirects the user back to the application. -### Step-By-Step Guide +--- -The [Step-By-Step Guide](/docs/examples/login/angular) leads you through the whole process from configuring the right application in ZITADEL to a ready application with integrated Login. +## Getting started -After completing the Step-By-Step Guide you will have: -1. Example Web Application with integrated ZITADEL Login -2. Example page accessible by authenticated user showing retrieved user information -3. Logout -4. Correct setup for your application in ZITADEL +### Prerequisites -![App in console](/img/angular/app-screen.png) +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: + +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method +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 +6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions + +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production 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/login-users): + +1. Clone the [repository](https://github.com/zitadel/example-auth-angular). +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/applications). Use these environment variable names exactly as shown: + ``` + NODE_ENV=development + PORT=3000 + NG_APP_ZITADEL_DOMAIN=https://your-zitadel-domain + NG_APP_ZITADEL_CLIENT_ID=your-zitadel-application-client-id + NG_APP_ZITADEL_CLIENT_SECRET= + NG_APP_ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback + NG_APP_ZITADEL_POST_LOGIN_URL=/profile + NG_APP_ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback + ``` + Replace these values with: + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **NG_APP_ZITADEL_DOMAIN**) + - The **Client ID** you copied when creating the application + - The **redirect URIs** you configured in the PKCE setup (must match exactly) + - The **post-logout redirect URIs** you configured (must match exactly) +3. Install dependencies using [npm](https://www.npmjs.com) and start the development server to verify the authentication flow end-to-end. + +--- + +## Learn more and resources + +* [PKCE concept](https://oauth.net/2/pkce/) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) +* [Angular documentation](https://angular.dev) +* [@edgeflare/ngx-oidc package](https://www.npmjs.com/package/@edgeflare/ngx-oidc) +* [oidc-client-ts package](https://www.npmjs.com/package/oidc-client-ts) +* [Example repository](https://github.com/zitadel/example-auth-angular) diff --git a/docs/docs/sdk-examples/astro.mdx b/docs/docs/sdk-examples/astro.mdx index 15fc86bbb..7ba22f8bf 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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. +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](https://oauth.net/2/pkce/) code generation and verification, token exchange, session management, 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/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). +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](https://oauth.net/2/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/apis/openidoauth/endpoints#token_endpoint). -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 example implements server-side session management with encrypted [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint), 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](/guides/manage/console/organizations-overview), 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/apis/openidoauth/endpoints#token_endpoint) 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/console/organizations), 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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/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](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production deployments, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/): +Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/login-users): 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](/docs/guides/manage/console/applications-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](https://zitadel.com/docs/guides/manage/console/applications). Use these environment variable names exactly as shown: ``` PORT=4321 SESSION_DURATION=3600 @@ -62,7 +62,7 @@ Once you have your [Zitadel application configured](https://zitadel.com/docs/gui NEXTAUTH_URL=http://localhost:4321 ``` Replace these values with: - - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/instance-settings) (the **ZITADEL_DOMAIN**) + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **ZITADEL_DOMAIN**) - The **Client ID** you copied when creating the application - A randomly generated **SESSION_SECRET** using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` - A randomly generated **ZITADEL_CLIENT_SECRET** (required by Auth.js even though PKCE doesn't require it) @@ -73,14 +73,11 @@ Once you have your [Zitadel application configured](https://zitadel.com/docs/gui ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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/django.mdx b/docs/docs/sdk-examples/django.mdx new file mode 100644 index 000000000..169a5ae32 --- /dev/null +++ b/docs/docs/sdk-examples/django.mdx @@ -0,0 +1,81 @@ +--- +title: Django +sidebar_label: Django +framework_url: https://www.djangoproject.com +auth_library: "Authlib" +auth_library_url: https://authlib.org +example_repo: https://github.com/zitadel/example-auth-django +auth_flow: pkce +status: stable +--- + +## Overview + +[Django](https://www.djangoproject.com) is a high-level Python web framework that encourages rapid development and clean, pragmatic design. It provides a robust set of features for web applications, making it one of the most popular choices for building server-side applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application. + +#### Auth library + +This example uses **[Authlib](https://authlib.org)**, the standard authentication library for Python web frameworks. Authlib implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management helpers. The integration uses Authlib's Django client which seamlessly handles OAuth 2.0 flows within Django applications. + +--- + +## What this example demonstrates + +This example shows a complete authentication implementation using [Django](https://www.djangoproject.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/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 implements server-side session management with Django's built-in session framework, storing authentication state securely in signed cookies. Protected routes use the `@require_auth` decorator 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/apis/openidoauth/endpoints#token_endpoint). + +The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles). + +--- + +## Getting started + +### Prerequisites + +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: + +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method +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 +6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions + +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. + +### Run the example + +Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured: + +1. Clone the [repository](https://github.com/zitadel/example-auth-django). +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/applications). **Use these exact environment variable names:** + ``` + PORT=3000 + SESSION_SECRET=your-very-secret-and-strong-session-key + ZITADEL_DOMAIN=https://your-zitadel-domain + ZITADEL_CLIENT_ID=your-zitadel-application-client-id + ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret + ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback + ZITADEL_POST_LOGIN_URL=/profile + ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback + ``` + Replace these values with: + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer) + - The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID` + - The **redirect URI** you configured in the PKCE setup for `ZITADEL_CALLBACK_URL` (must match exactly) + - The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL` + - A strong random string for `SESSION_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`) + - A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`) +3. Install dependencies using [Poetry](https://python-poetry.org) with `poetry install` and start the development server with `poetry run python manage.py runserver localhost:3000` to verify the authentication flow end-to-end. + +--- + +## Learn more and resources + +* [PKCE concept](https://oauth.net/2/pkce/) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) +* [Django documentation](https://www.djangoproject.com) +* [Authlib documentation](https://authlib.org) +* [Example repository](https://github.com/zitadel/example-auth-django) diff --git a/docs/docs/sdk-examples/expressjs.mdx b/docs/docs/sdk-examples/expressjs.mdx index fd3382f46..b5ebdae70 100644 --- a/docs/docs/sdk-examples/expressjs.mdx +++ b/docs/docs/sdk-examples/expressjs.mdx @@ -4,28 +4,28 @@ sidebar_label: Express.js framework_url: https://expressjs.com auth_library: "@auth/express" auth_library_url: https://www.npmjs.com/package/@auth/express -example_repo: https://github.com/zitadel/example-auth-express +example_repo: https://github.com/zitadel/example-auth-expressjs auth_flow: pkce status: stable --- ## Overview -[Express.js](https://expressjs.com) is a fast, unopinionated, minimalist web framework for [Node.js](https://nodejs.org) that provides a robust set of features for building web and mobile applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](/docs/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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. +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](https://oauth.net/2/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 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/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). +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](https://oauth.net/2/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/login-users) 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. +The example includes protected routes using [Express middleware](https://expressjs.com/en/guide/using-middleware.html) that automatically verify session state 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/apis/openidoauth/endpoints#token_endpoint), ensuring users remain authenticated without repeated logins. -Sign-out functionality implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by redirecting to Zitadel's end-session endpoint with the ID token hint, terminating both the local [session](https://zitadel.com/docs/concepts/sessions) and the Zitadel session. The logout flow includes [CSRF protection](https://authjs.dev/guides/basics/securing-pages-and-api-routes) through state parameter validation, and users are redirected to a success page after logout completion. All authentication flows use secure HTTP-only cookies for [session storage](https://authjs.dev/concepts/session-strategies) and implement proper security headers. +Sign-out functionality implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by redirecting to Zitadel's end-session endpoint with the ID token hint, terminating both the local session and the Zitadel session. The logout flow includes [CSRF protection](https://authjs.dev/guides/basics/securing-pages-and-api-routes) through state parameter validation, and users are redirected to a success page after logout completion. All authentication flows use secure HTTP-only cookies for [session storage](https://authjs.dev/concepts/session-strategies) and implement proper security headers. --- @@ -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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/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](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/): +Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/login-users): -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](/docs/guides/manage/console/applications-overview). Use the exact environment variable names from the repository: +1. Clone the [repository](https://github.com/zitadel/example-auth-expressjs). +2. Create a `.env.local` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). 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/manage/console/applications-overview)) + - Your actual Zitadel instance URL (the **Issuer** from the PKCE setup guide) - 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,10 @@ The application will be running at `http://localhost:3000`. ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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) +* [Example repository](https://github.com/zitadel/example-auth-expressjs) diff --git a/docs/docs/sdk-examples/fastapi.mdx b/docs/docs/sdk-examples/fastapi.mdx new file mode 100644 index 000000000..f34cb626b --- /dev/null +++ b/docs/docs/sdk-examples/fastapi.mdx @@ -0,0 +1,82 @@ +--- +title: FastAPI +sidebar_label: FastAPI +framework_url: https://fastapi.tiangolo.com +auth_library: "Authlib" +auth_library_url: https://authlib.org +example_repo: https://github.com/zitadel/example-auth-fastapi +auth_flow: pkce +status: stable +--- + +## Overview + +[FastAPI](https://fastapi.tiangolo.com) is a modern, fast (high-performance) web framework for building APIs with Python based on standard Python type hints. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application. + +#### Auth library + +This example uses **[Authlib](https://authlib.org)**, the standard authentication library for Python web frameworks. Authlib implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management helpers. The integration uses Authlib's Starlette client which seamlessly handles OAuth 2.0 flows within FastAPI applications built on [Starlette](https://www.starlette.io). + +--- + +## What this example demonstrates + +This example shows a complete authentication implementation using [FastAPI](https://fastapi.tiangolo.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/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 implements server-side session management with Starlette's session middleware, storing authentication state securely in encrypted cookies. Protected routes use the `require_auth` dependency 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/apis/openidoauth/endpoints#token_endpoint). + +The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles). + +--- + +## Getting started + +### Prerequisites + +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: + +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method +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 +6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions + +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. + +### Run the example + +Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured: + +1. Clone the [repository](https://github.com/zitadel/example-auth-fastapi). +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/applications). **Use these exact environment variable names:** + ``` + PY_ENV=development + PORT=3000 + SESSION_SECRET=your-very-secret-and-strong-session-key + ZITADEL_DOMAIN=https://your-zitadel-domain + ZITADEL_CLIENT_ID=your-zitadel-application-client-id + ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret + ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback + ZITADEL_POST_LOGIN_URL=/profile + ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback + ``` + Replace these values with: + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer) + - The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID` + - The **redirect URI** you configured in the PKCE setup for `ZITADEL_CALLBACK_URL` (must match exactly) + - The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL` + - A strong random string for `SESSION_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`) + - A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`) +3. Install dependencies using [Poetry](https://python-poetry.org) with `poetry install` and start the development server with `poetry run python run.py` to verify the authentication flow end-to-end. + +--- + +## Learn more and resources + +* [PKCE concept](https://oauth.net/2/pkce/) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) +* [FastAPI documentation](https://fastapi.tiangolo.com) +* [Authlib documentation](https://authlib.org) +* [Example repository](https://github.com/zitadel/example-auth-fastapi) diff --git a/docs/docs/sdk-examples/fastify.mdx b/docs/docs/sdk-examples/fastify.mdx index 834893e21..c2dbaf564 100644 --- a/docs/docs/sdk-examples/fastify.mdx +++ b/docs/docs/sdk-examples/fastify.mdx @@ -11,21 +11,21 @@ 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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. +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](https://oauth.net/2/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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/pkce/), which prevents authorization code interception attacks without requiring client secrets. -The example includes a custom sign-in page that initiates the [OAuth 2.0](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) authentication flow, automatic [callback handling](https://zitadel.com/docs/guides/integrate/login/oidc/) with secure [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints), and [JWT-based session management](https://zitadel.com/docs/concepts/tokens) with [@fastify/cookie](https://www.npmjs.com/package/@fastify/cookie). Protected routes use the `requireAuth` middleware to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/concepts/tokens). +The 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/login-users) with secure token exchange, and [JWT-based session management](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) 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/apis/openidoauth/endpoints#token_endpoint). -The application also demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with ZITADEL's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/concepts/tokens) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [ZITADEL-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles). +The application also demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles). --- @@ -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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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 +6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions -> **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. +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [ZITADEL Application](https://zitadel.com/docs/guides/integrate/login/oidc/) configured: +Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) 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](/docs/guides/manage/console/applications-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](https://zitadel.com/docs/guides/manage/console/applications). **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](/docs/guides/manage/console/overview) for `ZITADEL_DOMAIN` (the issuer) + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) 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,10 @@ Once you have your [ZITADEL Application](https://zitadel.com/docs/guides/integra ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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/flask.mdx b/docs/docs/sdk-examples/flask.mdx new file mode 100644 index 000000000..514aed488 --- /dev/null +++ b/docs/docs/sdk-examples/flask.mdx @@ -0,0 +1,82 @@ +--- +title: Flask +sidebar_label: Flask +framework_url: https://flask.palletsprojects.com +auth_library: "Authlib" +auth_library_url: https://authlib.org +example_repo: https://github.com/zitadel/example-auth-flask +auth_flow: pkce +status: stable +--- + +## Overview + +[Flask](https://flask.palletsprojects.com) is a lightweight WSGI web application framework for Python. It's designed to make getting started quick and easy, with the ability to scale up to complex applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application. + +#### Auth library + +This example uses **[Authlib](https://authlib.org)**, the standard authentication library for Python web frameworks. Authlib implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management helpers. The integration uses Authlib's Flask client which seamlessly handles OAuth 2.0 flows within Flask applications. + +--- + +## What this example demonstrates + +This example shows a complete authentication implementation using [Flask](https://flask.palletsprojects.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/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 implements server-side session management with Flask's built-in session handling, storing authentication state securely in encrypted cookies. Protected routes use the `@require_auth` decorator 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/apis/openidoauth/endpoints#token_endpoint). + +The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles). + +--- + +## Getting started + +### Prerequisites + +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: + +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method +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 +6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions + +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. + +### Run the example + +Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured: + +1. Clone the [repository](https://github.com/zitadel/example-auth-flask). +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/applications). **Use these exact environment variable names:** + ``` + PY_ENV=development + PORT=3000 + SESSION_SECRET=your-very-secret-and-strong-session-key + ZITADEL_DOMAIN=https://your-zitadel-domain + ZITADEL_CLIENT_ID=your-zitadel-application-client-id + ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret + ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback + ZITADEL_POST_LOGIN_URL=/profile + ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback + ``` + Replace these values with: + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer) + - The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID` + - The **redirect URI** you configured in the PKCE setup for `ZITADEL_CALLBACK_URL` (must match exactly) + - The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL` + - A strong random string for `SESSION_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`) + - A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`) +3. Install dependencies using [Poetry](https://python-poetry.org) with `poetry install` and start the development server with `poetry run python run.py` to verify the authentication flow end-to-end. + +--- + +## Learn more and resources + +* [PKCE concept](https://oauth.net/2/pkce/) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) +* [Flask documentation](https://flask.palletsprojects.com) +* [Authlib documentation](https://authlib.org) +* [Example repository](https://github.com/zitadel/example-auth-flask) diff --git a/docs/docs/sdk-examples/hono.mdx b/docs/docs/sdk-examples/hono.mdx index b989f5ab2..cdd719320 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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)**. +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](https://oauth.net/2/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/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. +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](https://oauth.net/2/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](https://oauth.net/2/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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/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](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your Zitadel application configured: 1. Clone the [repository](https://github.com/zitadel/example-auth-hono). -2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-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](https://zitadel.com/docs/guides/manage/console/applications). **Use the exact environment variable names from the repository:** ``` NODE_ENV=development PORT=3000 @@ -60,7 +60,7 @@ Once you have your Zitadel application configured: ZITADEL_POST_LOGOUT_URL=http://localhost:3000 ``` Replace these values with: - - Your actual **Zitadel instance URL** (the Issuer from your [instance settings](https://zitadel.com/docs/guides/manage/console/instance-settings)) + - Your actual **Zitadel instance URL** (the Issuer from your [instance settings](https://zitadel.com/docs/guides/manage/console/default-settings)) - The **Client ID** you copied when creating the application in the PKCE setup - The **redirect URI** you configured in the PKCE setup (must match exactly) - The **post-logout redirect URI** for handling logout callbacks @@ -80,14 +80,11 @@ The application will be running at `http://localhost:3000`. Visit the homepage t ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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/introduction.mdx b/docs/docs/sdk-examples/introduction.mdx index 0e7aea7a6..94e7460cd 100644 --- a/docs/docs/sdk-examples/introduction.mdx +++ b/docs/docs/sdk-examples/introduction.mdx @@ -1,10 +1,10 @@ --- -title: Examples and SDKs for ZITADEL +title: Examples and SDKs for Zitadel sidebar_label: Introduction sidebar_position: 1 --- -You can integrate ZITADEL quickly into your application and be up and running within minutes. +You can integrate Zitadel quickly into your application and be up and running within minutes. To achieve your goals as fast as possible, we provide you with SDKs, Example Repositories and Guides. The SDKs and integration depend on the framework and language you are using. @@ -31,7 +31,7 @@ import { Frameworks } from "../../src/components/frameworks"; framework.client === false || framework.client == null} /> -To further streamline your setup, simply visit the console in ZITADEL where you can select one of the languages or frameworks. This will allow you to instantly set up the configuration for that specific sample in ZITADEL, ensuring you have everything you need to get started right away. +To further streamline your setup, simply visit the console in Zitadel where you can select one of the languages or frameworks. This will allow you to instantly set up the configuration for that specific sample in Zitadel, ensuring you have everything you need to get started right away. ![Console](/img/sdk-examples/console.png) @@ -54,7 +54,7 @@ You might want to check out the following links to find a good library: ## Other example applications - [B2B customer portal](https://github.com/zitadel/zitadel-nextjs-b2b): Showcase the use of personal access tokens in a B2B environment. Uses NextJS Framework. -- [Frontend with backend API](https://github.com/zitadel/example-quote-generator-app): A simple web application using a React front-end and a Python back-end API, both secured using ZITADEL +- [Frontend with backend API](https://github.com/zitadel/example-quote-generator-app): A simple web application using a React front-end and a Python back-end API, both secured using Zitadel - [Introspection](https://github.com/zitadel/examples-api-access-and-token-introspection): Python examples for securing an API and invoking it as a service user - [Fine-grained authorization](https://github.com/zitadel/example-fine-grained-authorization): Leverage actions, custom metadata, and claims for attribute-based access control @@ -125,4 +125,4 @@ drwxr-xr-x 3 ffo ffo 4096 Apr 11 16:49 .. -rw-r--r-- 1 ffo ffo 13568 Apr 11 16:49 v1_pb.rb ``` -Import these files into your project to start interacting with ZITADEL's APIs. +Import these files into your project to start interacting with Zitadel's APIs. diff --git a/docs/docs/sdk-examples/laravel.mdx b/docs/docs/sdk-examples/laravel.mdx new file mode 100644 index 000000000..9fe775ba5 --- /dev/null +++ b/docs/docs/sdk-examples/laravel.mdx @@ -0,0 +1,82 @@ +--- +title: Laravel +sidebar_label: Laravel +framework_url: https://laravel.com +auth_library: "Laravel Socialite" +auth_library_url: https://laravel.com/docs/socialite +example_repo: https://github.com/zitadel/example-auth-laravel +auth_flow: pkce +status: stable +--- + +## Overview + +[Laravel](https://laravel.com) is a web application framework with expressive, elegant syntax. It provides a robust set of features for web applications, making it one of the most popular choices for building server-side applications. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application. + +#### Auth library + +This example uses **[Laravel Socialite](https://laravel.com/docs/socialite)**, the standard authentication library for Laravel applications. Laravel Socialite implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow through a custom Zitadel provider, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management through Laravel's authentication system. + +--- + +## What this example demonstrates + +This example shows a complete authentication implementation using [Laravel](https://laravel.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/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 implements server-side session management with Laravel's built-in session handling, storing authentication state securely in encrypted cookies. Protected routes use Laravel 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/apis/openidoauth/endpoints#token_endpoint). + +The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles). + +--- + +## Getting started + +### Prerequisites + +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: + +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method +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 +6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions + +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. + +### Run the example + +Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured: + +1. Clone the [repository](https://github.com/zitadel/example-auth-laravel). +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/applications). **Use these exact environment variable names:** + ``` + APP_KEY=your-app-key + APP_ENV=local + APP_DEBUG=true + SERVER_URL=http://localhost:3000 + SERVER_PORT=3000 + DB_CONNECTION=sqlite + ZITADEL_DOMAIN=https://your-zitadel-domain + ZITADEL_CLIENT_ID=your-zitadel-application-client-id + ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret + ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback + ``` + Replace these values with: + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer) + - The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID` + - The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL` + - A strong random string for `APP_KEY` (generate using: `php artisan key:generate`) + - A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `php -r "echo bin2hex(random_bytes(32));"`) +3. Install dependencies using [Composer](https://getcomposer.org) with `composer install` and start the development server with `composer run dev` to verify the authentication flow end-to-end. + +--- + +## Learn more and resources + +* [PKCE concept](https://oauth.net/2/pkce/) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) +* [Laravel documentation](https://laravel.com/docs) +* [Laravel Socialite documentation](https://laravel.com/docs/socialite) +* [Example repository](https://github.com/zitadel/example-auth-laravel) diff --git a/docs/docs/sdk-examples/nestjs.mdx b/docs/docs/sdk-examples/nestjs.mdx index 0ce29b4b8..4819fe616 100644 --- a/docs/docs/sdk-examples/nestjs.mdx +++ b/docs/docs/sdk-examples/nestjs.mdx @@ -11,21 +11,21 @@ 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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. +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](https://oauth.net/2/pkce/), performs token exchange, and exposes helpers for [session state](https://zitadel.com/docs/guides/integrate/login/oidc/login-users). 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/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). +This example implements a complete authentication flow using [PKCE](https://oauth.net/2/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/apis/openidoauth/endpoints#token_endpoint). -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. +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/login-users) 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. -The logout implementation demonstrates [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. [CSRF protection](https://owasp.org/www-community/attacks/csrf) during logout is achieved through a state parameter validated in the callback. The example also showcases accessing Zitadel's [UserInfo endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#userinfo) to fetch real-time user data, including [custom claims](https://zitadel.com/docs/apis/openidoauth/claims), [roles](https://zitadel.com/docs/guides/manage/console/roles), and organization membership. +The logout implementation demonstrates [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. [CSRF protection](https://owasp.org/www-community/attacks/csrf) during logout is achieved through a state parameter validated in the callback. The example also showcases accessing Zitadel's [UserInfo endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#userinfo_endpoint) to fetch real-time user data, including [custom claims](https://zitadel.com/docs/apis/openidoauth/claims), [roles](https://zitadel.com/docs/guides/manage/console/roles), and organization membership. All protected routes are secured using the [@mridang/nestjs-auth global guard](https://www.npmjs.com/package/@mridang/nestjs-auth), with the `@Public()` decorator marking routes that don't require authentication. The application uses [Handlebars templates](https://handlebarsjs.com) for server-side rendering and [Tailwind CSS](https://tailwindcss.com) for styling, providing a complete reference implementation for NestJS developers. @@ -35,22 +35,22 @@ 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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -1. Create a new Web application in your Zitadel project -2. Configure it to use the [PKCE authentication method](/docs/guides/integrate/login/oidc/login-users#pkce) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development) 4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`) 5. Copy your **Client ID** for use in the next steps -> **Note:** Make sure to enable **Dev Mode** in the Zitadel Console if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your Zitadel application configured: 1. Clone the [repository](https://github.com/zitadel/example-auth-nestjs). -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:** +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/applications). **Use the exact environment variable names from the repository:** ``` NODE_ENV=development PORT=3000 @@ -85,13 +85,10 @@ Once you have your Zitadel application configured: ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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/nextjs.mdx b/docs/docs/sdk-examples/nextjs.mdx index 8aebbc33f..ed7c2e008 100644 --- a/docs/docs/sdk-examples/nextjs.mdx +++ b/docs/docs/sdk-examples/nextjs.mdx @@ -1,54 +1,83 @@ --- title: Next.js sidebar_label: Next.js +framework_url: https://nextjs.org +auth_library: next-auth +auth_library_url: https://next-auth.js.org +example_repo: https://github.com/zitadel/example-auth-nextjs +auth_flow: pkce +status: stable --- - - - - - -
- next js logo - next js logo - - Next.js is a React-based framework that provides a powerful and flexible set of tools for building high-performance, SEO-friendly web applications. - Get started integrating authentication to your Next.js Application by checking out our zitadel-nextjs Example. -
+## Overview +[Next.js](https://nextjs.org) is a React framework for building full-stack web applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your Next.js application. -### Resources -- [Example App Repository](https://github.com/zitadel/zitadel-nextjs) -- [Step-By-Step Guide](/docs/examples/login/nextjs) -- [B2B customer portal](https://github.com/zitadel/zitadel-nextjs-b2b): Showcase the use of personal access tokens in a B2B environment built with Next.js +#### Auth library -### SDK +This example uses **[next-auth](https://www.npmjs.com/package/next-auth)** with **[openid-client](https://www.npmjs.com/package/openid-client)** to implement the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manage [PKCE](https://oauth.net/2/pkce/) code challenge generation, perform secure token exchange, and provide session management helpers. -ZITADEL does not provide a Next.js specific SDK. -However, for integrating authentication into your Next.js Application you can use [NextAuth ZITADEL Provider](https://next-auth.js.org/providers/zitadel) +--- -Check out our [Example Application](/docs/sdk-examples/nextjs#example-application) +## What this example demonstrates +This Next.js application demonstrates a secure authentication flow using Zitadel with the industry-standard [PKCE flow](https://oauth.net/2/pkce/). Users start on a public landing page, initiate login via the Zitadel authorization server, and after successful authentication are redirected back to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims). -### Example Application +The application implements session management using NextAuth.js with a JWT-based session strategy. It includes automatic callback handling with secure token exchange, route protection for authenticated-only pages, and an example of requesting additional [OIDC scopes](https://zitadel.com/docs/apis/openidoauth/scopes) (including `offline_access` for refresh tokens and Zitadel-specific scopes for metadata and roles). -The [zitadel-nextjs](https://github.com/zitadel/zitadel-nextjs) repository includes an Example Application ready to start and show how a Next.js application looks like with integrated ZITADEL Login. +The logout flow implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** via the end-session endpoint, terminating both the local session and the Zitadel session before redirecting the user back to the application. It also demonstrates automatic token refresh to maintain long-lived sessions without requiring users to re-authenticate. -What does the Example include: -TODO: ?? Update with correct infos -- Home Page with Login Button -- Authenticating user with OIDC PKCE Flow -- Private Page: Shows user information of authenticated user, only accessible after login -- Logout +--- -### Step-By-Step Guide +## Getting started -The [Step-By-Step Guide](/docs/examples/login/nextjs) leads you through the whole process from configuring the right application in ZITADEL to a ready application with integrated Login. +### Prerequisites -After completing the Step-By-Step Guide you will have: -TODO: ?? Updated with correct infos -1. Example Web Application with integrated ZITADEL Login -2. Example page accessible by authenticated user showing retrieved user information -3. Logout -4. Correct setup for your application in ZITADEL +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method +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/api/auth/logout/callback`) +5. Copy your **Client ID** for use in the next steps +6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions + +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production 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/login-users): + +1. Clone the [repository](https://github.com/zitadel/example-auth-nextjs). +2. Create a `.env.local` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). Use these environment variable names exactly as shown: + ``` + NODE_ENV=development + PORT=3000 + SESSION_SECRET=your-very-secret-and-strong-session-key + SESSION_DURATION=3600 + ZITADEL_DOMAIN=https://your-zitadel-domain + ZITADEL_CLIENT_ID=your-zitadel-application-client-id + ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret + ZITADEL_CALLBACK_URL=http://localhost:3000/api/auth/callback/zitadel + ZITADEL_POST_LOGIN_URL=/profile + ZITADEL_POST_LOGOUT_URL=http://localhost:3000/api/auth/logout/callback + NEXTAUTH_URL=http://localhost:3000 + ``` + Replace these values with: + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **ZITADEL_DOMAIN**) + - The **Client ID** you copied when creating the application + - A randomly generated **SESSION_SECRET** using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"` + - A randomly generated **ZITADEL_CLIENT_SECRET** (required by Auth.js / NextAuth.js even though PKCE doesn't require it) + - The **redirect URIs** you configured in the PKCE setup (must match exactly) +3. Install dependencies using [npm](https://www.npmjs.com) by running `npm install`, then start the development server with `npm run dev` to verify the authentication flow end-to-end at `http://localhost:3000`. + +--- + +## Learn more and resources + +* [PKCE concept](https://oauth.net/2/pkce/) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) +* [Next.js documentation](https://nextjs.org) +* [NextAuth.js documentation](https://next-auth.js.org/) +* [Example repository](https://github.com/zitadel/example-auth-nextjs) diff --git a/docs/docs/sdk-examples/nuxtjs.mdx b/docs/docs/sdk-examples/nuxtjs.mdx index f52391cee..a10beec5f 100644 --- a/docs/docs/sdk-examples/nuxtjs.mdx +++ b/docs/docs/sdk-examples/nuxtjs.mdx @@ -11,19 +11,19 @@ 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/pkce/), perform token exchange, and handle [session management](https://authjs.dev/concepts/session-strategies). --- ## 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/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). +This [Nuxt.js](https://nuxt.com) application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with the **[PKCE flow](https://oauth.net/2/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. +The example implements secure [session management](https://authjs.dev/concepts/session-strategies) using [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) capabilities through [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/docs/guides/manage/console/applications-overview). **Use these exact environment variable names:** +2. Create a `.env` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **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](/docs/guides/manage/console/console-overview#overview)) + - Your actual Zitadel instance URL (the **Issuer** from your [Zitadel instance settings](https://zitadel.com/docs/guides/manage/console/overview)) - The **Client ID** you copied when creating the application - A randomly generated **NUXT_AUTH_SECRET** for session encryption (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`) - The **callback URI** you configured in the PKCE setup (must match exactly) @@ -76,13 +76,10 @@ The application will be running at `http://localhost:3000` where you can test th ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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/python-django.mdx b/docs/docs/sdk-examples/python-django.mdx deleted file mode 100644 index daecc7403..000000000 --- a/docs/docs/sdk-examples/python-django.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Python Django -sidebar_label: Python Django ---- - - - - - - -
- python logo - - Django is a high-level Python web framework that encourages rapid development and clean, pragmatic design. - Get started integrating authentication to your Django API Application by checking out our example-python-django-oauth or your Django Web application by checking out our example-python-django-oidc Example. -
- - -### Resources -- [Example API App Repository](https://github.com/zitadel/example-python-django-oauth) -- [API App Step-By-Step Guide](/docs/examples/secure-api/python-django) -- [Example Web App Repository](https://github.com/zitadel/example-python-django-oidc) -- [Web App Step-By-Step Guide](/docs/examples/login/python-django) - -### Django SDK - -ZITADEL does not provide a Python Django specific SDK. -But you can integrate ZITADEL to your application by using any OIDC Library such as [mozilla-django-oidc](https://github.com/mozilla/mozilla-django-oidc) or [authlib](https://github.com/lepture/authlib). - -### Examples Application - -What does the API Application Example include: -- REST API Application secured with OAuth2 -- Public Endpoint: Accessible without authentication -- Private Endpoint: Accessible with a token -- Administrator Endpoint: Accessible with a token of a user with admin role - -[Example API App](https://github.com/zitadel/example-python-django-oauth) - -What does the Web Application Example include: -1. Example Web Application with integrated ZITADEL Login -2. Example page accessible by authenticated user showing retrieved user information -3. Example page accessible by authenticated user showing polls - - Votes for polls can only be done if authenticated - - New polls can be created by user with admin role -4. Logout -5. Correct setup for your application in ZITADEL - -[Example Web App](https://github.com/zitadel/example-python-django-oidc) - -### Step-By-Step Guide - -After completing the Step-By-Step Guide for an API you will have: -1. Example REST API checking tokens against ZITADEL with OAuth2 -2. Public Endpoint accessible by any user -3. Private Endpoint accessible by authenticated user -4. Private Endpoint accessible by user with role 'admin' -5. Correct setup for your application in ZITADEL - -[API App Step-By-Step Guide](/docs/examples/secure-api/python-django) - -After completing the Step-By-Step Guide for an Web application you will have: -1. Example Web Application with integrated ZITADEL Login -2. Example page accessible by authenticated user showing retrieved user information -3. Example page accessible by authenticated user showing polls - - Votes for polls can only be done if authenticated - - New polls can be created by user with admin role -4. Logout -5. Correct setup for your application in ZITADEL - -[Web App Step-By-Step Guide](/docs/examples/login/python-django) \ No newline at end of file diff --git a/docs/docs/sdk-examples/python-flask.mdx b/docs/docs/sdk-examples/python-flask.mdx deleted file mode 100644 index 816bf2e9a..000000000 --- a/docs/docs/sdk-examples/python-flask.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Python Flask -sidebar_label: Python Flask ---- - - - - - - -
- python logo - python logo - - Flask is a lightweight and easy-to-use microframework for Python web development. - Get started integrating authentication to your Flask API Application by checking out our example-api-python3-flask Example. -
- - -### Resources -- [Example App Repository](https://github.com/zitadel/example-api-python3-flask) -- [API APP Step-By-Step Guide](/docs/examples/secure-api/python-flask) -- [Frontend with backend API](https://github.com/zitadel/example-quote-generator-app): A simple web application using a React front-end and a Python back-end API, both secured using ZITADEL -- [Fine-grained authorization](https://github.com/zitadel/example-fine-grained-authorization): Leverage actions, custom metadata, and claims for attribute-based access control - -### Flask SDK - -ZITADEL does not provide a Python Flask specific SDK. -But you can integrate ZITADEL to your application by using any OIDC Library such as [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc). - -Check out our [Example Application](/docs/sdk-examples/angular#example-application) - - -### Examples Application - -What does the API Application Example include: -- REST API Application secured with OAuth2 -- Public Endpoint: Accessible without authentication -- Private Endpoint: Accessible with a token -- Administrator Endpoint: Accessible with a token of a user with admin role - -[Example API App](https://github.com/zitadel/example-api-python3-flask) - -### Step-By-Step Guide - -After completing the Step-By-Step Guide you will have: -1. Example REST API checking tokens against ZITADEL with OAuth2 -2. Public Endpoint accessible by any user -3. Private Endpoint accessible by authenticated user -4. Private Endpoint accessible by user with role 'admin' -5. Correct setup for your application in ZITADEL - -[API APP Step-By-Step Guide](/docs/examples/secure-api/python-flask) \ No newline at end of file diff --git a/docs/docs/sdk-examples/qwik.mdx b/docs/docs/sdk-examples/qwik.mdx index b8627e5fc..b0780d888 100644 --- a/docs/docs/sdk-examples/qwik.mdx +++ b/docs/docs/sdk-examples/qwik.mdx @@ -11,21 +11,21 @@ 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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. +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](https://oauth.net/2/pkce/), performs token exchange, and exposes helpers for session state. The core library handles authentication across multiple frameworks and provides secure [token storage](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) 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/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. +This [Qwik](https://qwik.dev) application showcases a complete authentication implementation using [Zitadel](https://zitadel.com/docs) with the [Authorization Code Flow with PKCE](https://oauth.net/2/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/apis/openidoauth/endpoints#token_endpoint), and manages sessions with [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-jwt-response) 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](/docs/guides/manage/console/organizations-overview) and [project roles](/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](https://zitadel.com/docs/guides/manage/console/organizations) and [project roles](https://zitadel.com/docs/guides/manage/console/projects). -Sign-out functionality implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through ZITADEL's end-session endpoint, ensuring that users are logged out from both the application and ZITADEL's [single sign-on session](https://zitadel.com/docs/concepts/sessions). The logout process includes [CSRF protection](https://zitadel.com/docs/guides/integrate/login/oidc/logout#csrf-protection) using state parameters validated through secure cookies, followed by proper cleanup of session data and redirection back to the application. +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. 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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/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](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [ZITADEL Application](/docs/guides/manage/console/applications-overview) configured: +Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) 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](/docs/guides/manage/console/applications-overview): +2. Create a `.env.local` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications): ``` VITE_PORT=3000 VITE_SESSION_SECRET=your-very-secret-and-strong-session-key @@ -60,7 +60,7 @@ Once you have your [ZITADEL Application](/docs/guides/manage/console/application VITE_ZITADEL_POST_LOGOUT_URL=http://localhost:3000/api/auth/logout/callback ``` Replace these values with: - - Your actual Zitadel instance URL (the **Issuer** from your [application settings](https://zitadel.com/docs/guides/integrate/login/oidc/)) + - Your actual Zitadel instance URL (the **Issuer** from your [application settings](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)) - The **Client ID** you copied when creating the application - A randomly generated session secret (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`) - A randomly generated client secret value (Auth.js requires this for internal configuration) @@ -78,13 +78,10 @@ The application will be available at `http://localhost:3000`. ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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 9962f0789..73e5f7774 100644 --- a/docs/docs/sdk-examples/react.mdx +++ b/docs/docs/sdk-examples/react.mdx @@ -11,21 +11,21 @@ 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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. +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](https://oauth.net/2/pkce/) code challenge generation, performs secure [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint), 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/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). +This [React](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/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/apis/openidoauth/endpoints#token_endpoint), 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. -The example leverages [React Router](https://reactrouter.com) for client-side navigation and [Vite](https://vite.dev) as the build tool, demonstrating modern React development patterns with [TypeScript](https://www.typescriptlang.org). All authentication state management, including [token refresh](https://zitadel.com/docs/concepts/tokens) with offline access, is handled automatically by the [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) library under the hood. +The example leverages [React Router](https://reactrouter.com) for client-side navigation and [Vite](https://vite.dev) as the build tool, demonstrating modern React development patterns with [TypeScript](https://www.typescriptlang.org). All authentication state management, including [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) with offline access, is handled automatically by the [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) library under the hood. --- @@ -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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/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](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your Zitadel application configured: 1. Clone the [repository](https://github.com/zitadel/example-auth-react). -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:** +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/applications). **Use these exact environment variable names:** ``` VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud VITE_ZITADEL_CLIENT_ID=your_client_id_from_console @@ -58,9 +58,9 @@ VITE_POST_LOGIN_URL=/profile 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/)) +- Your actual Zitadel instance URL (the **Issuer** from your [Zitadel application settings](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)) - The **Client ID** you copied when creating the application -- The **redirect URI** you configured in the [PKCE setup](/docs/guides/manage/console/applications-overview) (must match exactly) +- The **redirect URI** you configured in the PKCE setup (must match exactly) - The **post-logout redirect URI** you configured 3. Install dependencies using [npm](https://www.npmjs.com) and start the development server: ```bash @@ -74,14 +74,11 @@ The application will be running at `http://localhost:3000` where you can test th ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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 ec69f2fd0..8048b569d 100644 --- a/docs/docs/sdk-examples/solidstart.mdx +++ b/docs/docs/sdk-examples/solidstart.mdx @@ -11,19 +11,19 @@ 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/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. +[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](https://oauth.net/2/pkce/)** to authenticate users securely and maintain [sessions](https://authjs.dev/concepts/session-strategies) 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/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. +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](https://oauth.net/2/pkce/), performs [token exchange](https://zitadel.com/docs/apis/openidoauth/grant-types), and exposes helpers for [session state](https://authjs.dev/concepts/session-strategies). 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/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). +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](https://oauth.net/2/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://authjs.dev/concepts/session-strategies) using encrypted [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint). 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. +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/apis/openidoauth/endpoints#token_endpoint) 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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/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](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [ZITADEL Application](/docs/guides/manage/console/applications-overview) configured: +Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) 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](/docs/guides/manage/console/applications-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](https://zitadel.com/docs/guides/manage/console/applications). Use the exact environment variable names from the repository: ``` NODE_ENV=development PORT=3000 @@ -61,8 +61,8 @@ Once you have your [ZITADEL Application](/docs/guides/manage/console/application NEXTAUTH_URL="http://localhost:3000" ``` Replace these values with: - - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/instance-settings) (the **Issuer**) - - The **Client ID** you copied when [creating the application](/docs/guides/manage/console/applications-overview) + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **Issuer**) + - The **Client ID** you copied when creating the application - The **redirect URIs** you configured in the PKCE setup (must match exactly) - A secure random string for `SESSION_SECRET` (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`) - A secure random string for `ZITADEL_CLIENT_SECRET` for [Auth.js](https://authjs.dev) configuration compatibility @@ -76,15 +76,12 @@ Once you have your [ZITADEL Application](/docs/guides/manage/console/application ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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/spring.mdx b/docs/docs/sdk-examples/spring.mdx new file mode 100644 index 000000000..6014bcf62 --- /dev/null +++ b/docs/docs/sdk-examples/spring.mdx @@ -0,0 +1,107 @@ +--- +title: Spring Boot +sidebar_label: Spring Boot +framework_url: https://spring.io/projects/spring-boot +auth_library: "Spring Security" +auth_library_url: https://spring.io/projects/spring-security +example_repo: https://github.com/zitadel/example-auth-spring +auth_flow: pkce +status: stable +--- + +## Overview + +[Spring Boot](https://spring.io/projects/spring-boot) is a powerful, production-ready framework for building Java applications. This example shows how to integrate **Zitadel** into a Spring Boot web application using **OpenID Connect (OIDC)** and the **Authorization Code Flow + PKCE**. + +It demonstrates a common web app pattern: users start on a public landing page, authenticate with Zitadel via a login button, and are then redirected to a protected profile page that displays user information. Logout is also implemented to end both the local session and the Zitadel session. + +#### Auth library + +This example uses **[Spring Security](https://spring.io/projects/spring-security)**, the standard framework for authentication and access control in Spring applications. Spring Security supports OIDC natively and manages the PKCE flow for you. + +--- + +## What this example demonstrates + +This example shows a complete authentication implementation using Spring Security’s OAuth 2.0 / OIDC support: + +- **Public landing page** (`/`) accessible without authentication. +- **Sign-in with Zitadel** via Spring Security’s OAuth2 login entrypoint. +- **Route protection** so authenticated access is required for protected routes (e.g. `/profile`). +- **Profile page** that renders the authenticated user’s OIDC claims. +- **Server-side session management** handled by the servlet container + Spring Security. +- **Federated logout** that clears the local session and triggers RP-initiated logout against Zitadel, returning the user to a post-logout callback route. + +--- + +## Getting started + +### Prerequisites + +Before you begin, ensure you have the following: + +#### System Requirements + +- Java Development Kit (JDK) 17 or later +- Maven (or use the included `mvnw` wrapper) + +#### Account Setup + +You’ll need a Zitadel account and an application configured for a Web app using Authorization Code + PKCE. + +> **Important:** Configure the following URLs in your Zitadel application settings: +> +> - **Redirect URIs:** `http://localhost:3000/auth/callback` +> - **Post Logout Redirect URIs:** `http://localhost:3000/auth/logout/callback` +> +> These URLs must exactly match what your Spring Boot application uses. For production, add your production URLs. + +### Run the example + +1. Clone the repository. +2. Copy `.env.example` to `.env` and fill in your Zitadel details. + +```dotenv +# Port number where your Spring Boot server will listen for incoming HTTP requests. +PORT=3000 + +# Session timeout in seconds. Users will be automatically logged out after this +# duration of inactivity. 3600 seconds = 1 hour. +SESSION_DURATION=3600 + +# Your Zitadel instance domain URL. Include the full https:// URL. +ZITADEL_DOMAIN="https://your-zitadel-domain" + +# Application Client ID from your Zitadel application settings. +ZITADEL_CLIENT_ID="your-client-id" + +# Provide a randomly generated string here. +ZITADEL_CLIENT_SECRET="your-randomly-generated-client-secret" +``` + +3. Build and start the server: + +```bash +# 1. Clone the repository +git clone git@github.com:zitadel/example-auth-spring.git +cd example-auth-spring + +# 2. Build the project and download dependencies +mvn clean install + +# 3. Start the development server +mvn spring-boot:run +``` + +4. Open `http://localhost:3000` and walk through login → profile → logout. + +--- + +## Learn more and resources + +* [PKCE concept](https://oauth.net/2/pkce/) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) +* [Spring Boot documentation](https://spring.io/projects/spring-boot) +* [Spring Security documentation](https://spring.io/projects/spring-security) +* [Example repository](https://github.com/zitadel/example-auth-spring) diff --git a/docs/docs/sdk-examples/sveltekit.mdx b/docs/docs/sdk-examples/sveltekit.mdx index a06a80429..2fcaa6e4d 100644 --- a/docs/docs/sdk-examples/sveltekit.mdx +++ b/docs/docs/sdk-examples/sveltekit.mdx @@ -11,19 +11,19 @@ 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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). +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](https://oauth.net/2/pkce/)**. After successful authentication, they're redirected to a protected profile page that displays their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims). -The example demonstrates route protection using [SvelteKit's server-side load functions](https://kit.svelte.dev/docs/load) that verify [session state](https://zitadel.com/docs/concepts/tokens) before rendering protected pages. Authentication state is managed through [@auth/sveltekit hooks](https://www.npmjs.com/package/@auth/sveltekit), which integrate with [SvelteKit's hooks system](https://kit.svelte.dev/docs/hooks) to provide session data throughout your application. The implementation includes automatic [access token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. +The 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/apis/openidoauth/endpoints#token_endpoint) before rendering protected pages. Authentication state is managed through [@auth/sveltekit hooks](https://www.npmjs.com/package/@auth/sveltekit), which integrate with [SvelteKit's hooks system](https://kit.svelte.dev/docs/hooks) to provide session data throughout your application. The implementation includes automatic [access token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The logout flow implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** with proper CSRF protection, terminating both the local application session and the Zitadel session before redirecting users back to your application. Custom error pages provide user-friendly messages for authentication failures, and the example includes comprehensive security headers configured through [SvelteKit's hooks](https://kit.svelte.dev/docs/hooks). @@ -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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/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](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example Once you have your Zitadel application configured: 1. Clone the [repository](https://github.com/zitadel/example-auth-sveltekit). -2. Create a `.env.local` file in the project root and configure it with the values from your [ZITADEL Application](/docs/guides/manage/console/applications-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](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:** ``` SESSION_SECRET=your-very-secret-and-strong-session-key SESSION_DURATION=3600 @@ -77,13 +77,10 @@ Once you have your Zitadel application configured: ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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/symfony.mdx b/docs/docs/sdk-examples/symfony.mdx index 297f75748..bfe9c1e7f 100644 --- a/docs/docs/sdk-examples/symfony.mdx +++ b/docs/docs/sdk-examples/symfony.mdx @@ -1,53 +1,79 @@ --- -title: Symfony PHP Framework -sidebar_label: Symfony PHP +title: Symfony +sidebar_label: Symfony +framework_url: https://symfony.com +auth_library: "Symfony Security" +auth_library_url: https://symfony.com/doc/current/security.html +example_repo: https://github.com/zitadel/example-auth-symfony +auth_flow: pkce +status: stable --- - - - - - -
- php logo - - Symfony is a high-performance PHP framework that provides a solid foundation for building scalable and maintainable web applications. - Integrate authentication to your Symfony application easily by using the example-symfony-oidc Example. -
+## Overview -### Resources -- [Example Web App with ZITADEL Login](https://github.com/zitadel/example-symfony-oidc) -- [Step-By-Step Guide](/docs/examples/login/symfony) +[Symfony](https://symfony.com) is a set of reusable PHP components and a PHP framework for web projects. It provides a robust set of features for web applications, making it one of the most popular choices for building server-side applications. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application. -### PHP SDK +#### Auth library -ZITADEL does not provide a Symfony specific SDK. -But you can integrate ZITADEL to your application by using any OIDC Library such as [symfony-oidc](https://github.com/Drenso/symfony-oidc). +This example uses **[Symfony Security](https://symfony.com/doc/current/security.html)**, the standard authentication component for Symfony applications. Symfony Security implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow through a custom authenticator, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management through Symfony's firewall system. -Check out our [Example Application](/docs/sdk-examples/symfony#example-application) +--- -### Example Application +## What this example demonstrates -The [example-symfony-oidc](https://github.com/zitadel/example-symfony-oidc) repository includes an Example Application ready to start and show how a Symfony application looks like with integrated ZITADEL Login. +This example shows a complete authentication implementation using [Symfony](https://symfony.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/pkce/), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) after successful authentication. -What does the Example include: -- OIDC Code flow with User Info call after authentication. -- Fully integrated with Symfony security and firewall. -- User Role mapping -- Persistent user data using local sqlite file. See DATABASE_URL in .env. -- Public page at / -- Authenticated /profile page for all users. -- Authenticated /admin page for admin role users. -- Logout +The application implements server-side session management with Symfony's security system, storing authentication state securely through the framework's user provider pattern. Protected routes use Symfony Security's firewall configuration 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/apis/openidoauth/endpoints#token_endpoint). -### Step-By-Step Guide +The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles). -The [Step-By-Step Guide](/docs/examples/login/symfony) leads you through the whole process from configuring the right application in ZITADEL to a ready application with integrated Login. +--- -After completing the Step-By-Step Guide you will have: -1. Example Web Application with integrated ZITADEL Login -2. Example page accessible without authentication -3. Example page accessible by authenticated user showing retrieved user information -4. Example administrator page accessible by user with administrator role -5. Logout -6. Correct setup for your application in ZITADEL +## Getting started + +### Prerequisites + +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: + +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method +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 +6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions + +> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. + +### Run the example + +Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured: + +1. Clone the [repository](https://github.com/zitadel/example-auth-symfony). +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/applications). **Use these exact environment variable names:** + ``` + APP_SECRET=your-app-secret-key + SERVER_URL=http://localhost:3000 + SERVER_PORT=3000 + ZITADEL_DOMAIN=https://your-zitadel-domain + ZITADEL_CLIENT_ID=your-zitadel-application-client-id + ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret + ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback + ``` + Replace these values with: + - Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer) + - The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID` + - The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL` + - A strong random string for `APP_SECRET` (generate using: `php -r "echo bin2hex(random_bytes(32));"`) + - A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `php -r "echo bin2hex(random_bytes(32));"`) +3. Install dependencies using [Composer](https://getcomposer.org) with `composer install` and start the development server with `composer run dev` to verify the authentication flow end-to-end. + +--- + +## Learn more and resources + +* [PKCE concept](https://oauth.net/2/pkce/) +* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) +* [Symfony documentation](https://symfony.com/doc) +* [Symfony Security documentation](https://symfony.com/doc/current/security.html) +* [Example repository](https://github.com/zitadel/example-auth-symfony) diff --git a/docs/docs/sdk-examples/vue.mdx b/docs/docs/sdk-examples/vue.mdx index be21013c9..31f17c97a 100644 --- a/docs/docs/sdk-examples/vue.mdx +++ b/docs/docs/sdk-examples/vue.mdx @@ -11,21 +11,21 @@ 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/guides/integrate/login/oidc/login-users#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](https://oauth.net/2/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/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. +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](https://oauth.net/2/pkce/), performs token exchange, and exposes helpers for [session state](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) 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/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). +This [Vue.js](https://vuejs.org) application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with [PKCE](https://oauth.net/2/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. +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/apis/openidoauth/endpoints#token_endpoint) before rendering protected views. -The example includes secure sign-out functionality implementing **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's [end-session endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#end-session), which terminates both the local application session and the Zitadel session. The app demonstrates proper handling of [refresh tokens](https://zitadel.com/docs/concepts/tokens) using the `offline_access` [scope](https://zitadel.com/docs/apis/openidoauth/scopes), and includes comprehensive [error handling](https://github.com/authts/vue-oidc-context#error-handling) for authentication failures. +The example includes secure sign-out functionality implementing **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's [end-session endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#end_session_endpoint), which terminates both the local application session and the Zitadel session. The app demonstrates proper handling of [refresh tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) using the `offline_access` [scope](https://zitadel.com/docs/apis/openidoauth/scopes), and includes comprehensive [error handling](https://github.com/authts/vue-oidc-context#error-handling) for authentication failures. --- @@ -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](/docs/guides/manage/console/console-overview). Follow the **[Application Setup guide](/docs/guides/manage/console/applications-overview)** to: +Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to: -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) +1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects) +2. Configure it to use the PKCE authentication method 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](/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](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode. ### Run the example -Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/), follow these steps: +Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/login-users), 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](/docs/guides/manage/console/applications-overview): +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/applications): ``` VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud VITE_ZITADEL_CLIENT_ID=your_client_id_from_console @@ -57,8 +57,8 @@ VITE_ZITADEL_POST_LOGOUT_URL=http://localhost:3000 VITE_POST_LOGIN_URL=/profile ``` Replace these values with: -- Your actual [Zitadel instance URL](https://zitadel.com/docs) (the **Issuer**) -- The **Client ID** you copied when creating the application in the [PKCE setup](/docs/guides/manage/console/applications-overview) +- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **Issuer**) +- The **Client ID** you copied when creating the application in the PKCE setup - The **redirect URI** you configured (must match exactly) - The **post-logout redirect URI** for [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) 3. Install dependencies using [npm](https://www.npmjs.com) and start the development server: @@ -71,15 +71,12 @@ npm run dev ## Learn more and resources -* [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) +* [PKCE concept](https://oauth.net/2/pkce/) * [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) -* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/) +* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) * [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/frameworks.json b/docs/frameworks.json index 0adec6380..b1e622db7 100644 --- a/docs/frameworks.json +++ b/docs/frameworks.json @@ -65,7 +65,7 @@ "id": "spring", "title": "Spring", "imgSrcDark": "/docs/img/tech/spring.svg", - "docsLink": "/docs/sdk-examples/java" + "docsLink": "/docs/sdk-examples/spring" }, { "title": "NestJS", @@ -81,15 +81,22 @@ }, { "id": "django", - "title": "Python Django", + "title": "Django", "imgSrcDark": "/docs/img/tech/django.svg", - "docsLink": "/docs/sdk-examples/python-django" + "docsLink": "/docs/sdk-examples/django" }, { - "title": "Python Flask", + "id": "flask", + "title": "Flask", "imgSrcDark": "/docs/img/tech/flask.svg", "imgSrcLight": "/docs/img/tech/flask.svg", - "docsLink": "/docs/sdk-examples/python-flask" + "docsLink": "/docs/sdk-examples/flask" + }, + { + "id": "fastapi", + "title": "FastAPI", + "imgSrcDark": "/docs/img/tech/fastapi.svg", + "docsLink": "/docs/sdk-examples/fastapi" }, { "id": "react", @@ -125,12 +132,6 @@ "docsLink": "https://github.com/maennchen/zitadel_api", "external": true }, - { - "title": "FastAPI", - "imgSrcDark": "/docs/img/tech/fastapi.svg", - "docsLink": "https://github.com/cleanenergyexchange/fastapi-zitadel-auth", - "external": true - }, { "title": "NextAuth", "imgSrcDark": "/docs/img/tech/nextjs.svg", @@ -170,5 +171,59 @@ "imgSrcDark": "/docs/img/tech/javascript.svg", "docsLink": "https://github.com/zitadel/zitadel-vanilla-js", "external": true + }, + { + "id": "astro", + "title": "Astro", + "imgSrcDark": "/docs/img/tech/astro.svg", + "docsLink": "/docs/sdk-examples/astro" + }, + { + "id": "expressjs", + "title": "Express.js", + "imgSrcDark": "/docs/img/tech/expressjs.svg", + "docsLink": "/docs/sdk-examples/expressjs" + }, + { + "id": "fastify", + "title": "Fastify", + "imgSrcDark": "/docs/img/tech/fastify.svg", + "docsLink": "/docs/sdk-examples/fastify" + }, + { + "id": "hono", + "title": "Hono", + "imgSrcDark": "/docs/img/tech/hono.svg", + "docsLink": "/docs/sdk-examples/hono" + }, + { + "id": "nuxtjs", + "title": "Nuxt.js", + "imgSrcDark": "/docs/img/tech/nuxtjs.svg", + "docsLink": "/docs/sdk-examples/nuxtjs" + }, + { + "id": "qwik", + "title": "Qwik", + "imgSrcDark": "/docs/img/tech/qwik.svg", + "docsLink": "/docs/sdk-examples/qwik" + }, + { + "id": "solidstart", + "title": "SolidStart", + "imgSrcDark": "/docs/img/tech/solidstart.svg", + "docsLink": "/docs/sdk-examples/solidstart" + }, + { + "id": "sveltekit", + "title": "SvelteKit", + "imgSrcDark": "/docs/img/tech/sveltekit.svg", + "docsLink": "/docs/sdk-examples/sveltekit" + }, + { + "id": "laravel", + "title": "Laravel", + "imgSrcDark": "/docs/img/tech/laravel.svg", + "docsLink": "/docs/sdk-examples/laravel" } ] diff --git a/docs/sidebars.js b/docs/sidebars.js index 26afabfe1..9b30f3c0a 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -311,13 +311,9 @@ module.exports = { label: "Python", items: [ "sdk-examples/client-libraries/python", - "sdk-examples/python-flask", - "sdk-examples/python-django", - { - type: "link", - label: "FastAPI", - href: "https://github.com/cleanenergyexchange/fastapi-zitadel-auth", - }, + "sdk-examples/flask", + "sdk-examples/django", + "sdk-examples/fastapi", ], }, { @@ -330,6 +326,7 @@ module.exports = { label: "Java", items: [ "sdk-examples/java", + "sdk-examples/spring", "sdk-examples/client-libraries/java", ], }, @@ -338,6 +335,7 @@ module.exports = { label: "PHP", items: [ "sdk-examples/symfony", + "sdk-examples/laravel", "sdk-examples/client-libraries/php", ], }, diff --git a/docs/static/img/tech/astro.svg b/docs/static/img/tech/astro.svg new file mode 100644 index 000000000..f1860e300 --- /dev/null +++ b/docs/static/img/tech/astro.svg @@ -0,0 +1,2 @@ + +file_type_astro \ No newline at end of file diff --git a/docs/static/img/tech/expressjs.svg b/docs/static/img/tech/expressjs.svg new file mode 100644 index 000000000..72ec0689e --- /dev/null +++ b/docs/static/img/tech/expressjs.svg @@ -0,0 +1,2 @@ + + \ No newline at end of file diff --git a/docs/static/img/tech/fastify.svg b/docs/static/img/tech/fastify.svg new file mode 100644 index 000000000..4b9f33afd --- /dev/null +++ b/docs/static/img/tech/fastify.svg @@ -0,0 +1,10 @@ + + + + + + + + + diff --git a/docs/static/img/tech/hono.svg b/docs/static/img/tech/hono.svg new file mode 100644 index 000000000..c2c0bacc8 --- /dev/null +++ b/docs/static/img/tech/hono.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/docs/static/img/tech/laravel.svg b/docs/static/img/tech/laravel.svg new file mode 100644 index 000000000..b2b420418 --- /dev/null +++ b/docs/static/img/tech/laravel.svg @@ -0,0 +1,12 @@ + + + + + + + + + diff --git a/docs/static/img/tech/nuxtjs.svg b/docs/static/img/tech/nuxtjs.svg new file mode 100644 index 000000000..35578a0f9 --- /dev/null +++ b/docs/static/img/tech/nuxtjs.svg @@ -0,0 +1,2 @@ + +file_type_nuxt \ No newline at end of file diff --git a/docs/static/img/tech/qwik.svg b/docs/static/img/tech/qwik.svg new file mode 100644 index 000000000..d78c001ce --- /dev/null +++ b/docs/static/img/tech/qwik.svg @@ -0,0 +1,5 @@ + + + + + diff --git a/docs/static/img/tech/solidstart.svg b/docs/static/img/tech/solidstart.svg new file mode 100644 index 000000000..8a8988c4f --- /dev/null +++ b/docs/static/img/tech/solidstart.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/static/img/tech/sveltekit.svg b/docs/static/img/tech/sveltekit.svg new file mode 100644 index 000000000..c4cdf5448 --- /dev/null +++ b/docs/static/img/tech/sveltekit.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + +