From 574e23e834bf2e50b2bf9ebf0ea4d36fed9fdf82 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabienne=20B=C3=BChler?= Date: Wed, 11 Mar 2026 14:57:15 +0100 Subject: [PATCH] fix: Separate Example Applications and SDKs/Integrations more clearly (#11569) # Which Problems Are Solved The distinction between Example Applications and SDKs has not been clear. In the SDKs section a lot of Example applications where listed. Also In the SDKs it was not really clear what the SDKs actually are. Also some examples and skds are outdated and not well maintained anymore. # How the Problems Are Solved - Moved all example app guides to the Example Applications Section - Restructured SDKs Nav --> SDKs & Integrations: Frontend & Mobile, Backend & API, Management API Clients - Removed unnecessary / outdated guides - Remove ids in framework.json for frameworks which shouldn't be rendered in console ## Todos: - Update SDKs Introduction page - Add links to common oidc libs for most used frameworks --------- Co-authored-by: Mridang Agarwalla --- apps/docs/components/github-code-block.tsx | 44 ++ .../examples/introduction/backend/index.mdx | 3 +- .../examples/introduction/frontend/index.mdx | 6 +- .../examples/introduction/fullstack/index.mdx | 14 +- .../examples/introduction/webapp/index.mdx | 6 +- apps/docs/content/examples/login/angular.mdx | 171 -------- apps/docs/content/examples/login/flutter.mdx | 2 + apps/docs/content/examples/login/go.mdx | 2 +- .../content/examples/login/java-spring.mdx | 177 -------- .../content/examples/login/nextjs-b2b.mdx | 4 +- apps/docs/content/examples/login/nextjs.mdx | 196 --------- .../content/examples/login/python-django.mdx | 242 ----------- apps/docs/content/examples/login/react.mdx | 121 ------ apps/docs/content/examples/login/symfony.mdx | 409 ------------------ apps/docs/content/examples/login/vue.mdx | 130 ------ apps/docs/content/examples/secure-api/go.mdx | 4 +- .../examples/secure-api/java-spring.mdx | 19 +- .../examples/secure-api/nodejs-nestjs.mdx | 5 +- .../content/examples/secure-api/pylon.mdx | 2 +- .../examples/secure-api/python-django.mdx | 30 +- .../examples/secure-api/python-flask.mdx | 4 +- .../solution-scenarios/introduction/index.mdx | 1 + .../sdk-examples/_oidc-libraries-table.mdx | 25 ++ apps/docs/content/sdk-examples/flutter.mdx | 68 --- apps/docs/content/sdk-examples/hono.mdx | 2 +- .../content/sdk-examples/introduction.mdx | 30 +- .../content/sdk-examples/oidc-libraries.mdx | 10 + apps/docs/content/sdk-examples/solidstart.mdx | 2 +- apps/docs/content/sdk-examples/sveltekit.mdx | 4 +- apps/docs/css/custom.css | 4 + apps/docs/frameworks.json | 93 +++- apps/docs/lib/sidebar-data.ts | 185 ++++---- apps/docs/redirects.json | 45 ++ 33 files changed, 364 insertions(+), 1696 deletions(-) create mode 100644 apps/docs/components/github-code-block.tsx delete mode 100644 apps/docs/content/examples/login/angular.mdx delete mode 100644 apps/docs/content/examples/login/java-spring.mdx delete mode 100644 apps/docs/content/examples/login/nextjs.mdx delete mode 100644 apps/docs/content/examples/login/python-django.mdx delete mode 100644 apps/docs/content/examples/login/react.mdx delete mode 100644 apps/docs/content/examples/login/symfony.mdx delete mode 100644 apps/docs/content/examples/login/vue.mdx create mode 100644 apps/docs/content/sdk-examples/_oidc-libraries-table.mdx delete mode 100644 apps/docs/content/sdk-examples/flutter.mdx create mode 100644 apps/docs/content/sdk-examples/oidc-libraries.mdx diff --git a/apps/docs/components/github-code-block.tsx b/apps/docs/components/github-code-block.tsx new file mode 100644 index 000000000..9dd8e5e8e --- /dev/null +++ b/apps/docs/components/github-code-block.tsx @@ -0,0 +1,44 @@ +// components/github-code-block.tsx +import { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock'; + +export async function GithubCodeBlock({ url }: { url: string }) { + // 1. Parse the URL to get the raw content URL and line fragments + const urlObj = new URL(url); + const rawUrl = url + .replace('github.com', 'raw.githubusercontent.com') + .replace('/blob/', '/'); + + // Extract line numbers from hash (e.g., #L10-L20 or #L5) + const lineMatch = urlObj.hash.match(/L(\d+)(?:-L(\d+))?/); + const startLine = lineMatch ? parseInt(lineMatch[1], 10) : null; + const endLine = lineMatch ? (lineMatch[2] ? parseInt(lineMatch[2], 10) : startLine) : null; + + // 2. Fetch the content + const response = await fetch(rawUrl); + let code = await response.text(); + + // 3. Optional: Extract specific lines + if (startLine !== null && endLine !== null) { + const lines = code.split('\n'); + const selectedLines = lines.slice(startLine - 1, endLine); + + // Remove common indentation (dedent) + const minIndent = selectedLines.reduce((min, line) => { + if (line.trim().length === 0) return min; + const indent = line.match(/^\s*/)?.[0].length ?? 0; + return Math.min(min, indent); + }, Infinity); + + code = selectedLines + .map(line => line.slice(minIndent === Infinity ? 0 : minIndent)) + .join('\n'); + } + + const lang = url.split('.').pop()?.split('#')[0] || 'text'; + + return ( + + 
{code}
+ + ); +} \ No newline at end of file diff --git a/apps/docs/content/examples/introduction/backend/index.mdx b/apps/docs/content/examples/introduction/backend/index.mdx index fd7969973..f591680d2 100644 --- a/apps/docs/content/examples/introduction/backend/index.mdx +++ b/apps/docs/content/examples/introduction/backend/index.mdx @@ -13,8 +13,7 @@ import { FileText, Folder, Link as LinkIcon } from 'lucide-react'; } /> } /> - } /> - } /> } /> } /> + } /> diff --git a/apps/docs/content/examples/introduction/frontend/index.mdx b/apps/docs/content/examples/introduction/frontend/index.mdx index c7c6fab27..5677953a2 100644 --- a/apps/docs/content/examples/introduction/frontend/index.mdx +++ b/apps/docs/content/examples/introduction/frontend/index.mdx @@ -11,8 +11,8 @@ import { Card, Cards } from 'fumadocs-ui/components/card'; import { FileText, Folder, Link as LinkIcon } from 'lucide-react'; + } /> + } /> } external /> - } /> - } /> - } /> + } /> diff --git a/apps/docs/content/examples/introduction/fullstack/index.mdx b/apps/docs/content/examples/introduction/fullstack/index.mdx index 3e105464a..467cda5c2 100644 --- a/apps/docs/content/examples/introduction/fullstack/index.mdx +++ b/apps/docs/content/examples/introduction/fullstack/index.mdx @@ -11,6 +11,18 @@ import { Card, Cards } from 'fumadocs-ui/components/card'; import { FileText, Folder, Link as LinkIcon } from 'lucide-react'; - } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> + } /> } /> + } /> + } /> + } /> + } /> diff --git a/apps/docs/content/examples/introduction/webapp/index.mdx b/apps/docs/content/examples/introduction/webapp/index.mdx index 46f7f23fe..6d87fcd92 100644 --- a/apps/docs/content/examples/introduction/webapp/index.mdx +++ b/apps/docs/content/examples/introduction/webapp/index.mdx @@ -11,8 +11,8 @@ import { Card, Cards } from 'fumadocs-ui/components/card'; import { FileText, Folder, Link as LinkIcon } from 'lucide-react'; - } /> - } /> - } /> + } /> } /> + } /> + } /> diff --git a/apps/docs/content/examples/login/angular.mdx b/apps/docs/content/examples/login/angular.mdx deleted file mode 100644 index 9e06a0d6c..000000000 --- a/apps/docs/content/examples/login/angular.mdx +++ /dev/null @@ -1,171 +0,0 @@ ---- -title: ZITADEL with Angular -description: "Integrate ZITADEL into Angular applications using OIDC and PKCE for user authentication." -sidebar_label: Angular ---- - -This integration guide demonstrates the recommended way to incorporate ZITADEL into your Angular application. -It explains how to enable user login in your application and how to fetch data from the user info endpoint. - -By the end of this guide, your application will have login functionality and will be able to access the current user's profile. - -> This documentation references our [example](https://github.com/zitadel/zitadel-angular) on GitHub. Please note that we wrote the ZITADEL Management Console in Angular, so you can also use that as a reference. - -## Set up application and obtain keys - -Before we begin developing our application, we need to perform a few setup steps in the ZITADEL Console. -You'll need to provide some information about your app. We recommend creating a new app to start from scratch. Navigate to your Project, then add a new application at the top of the page. -Select the **User Agent** application type and continue. -We recommend that you use [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all SPA applications. - -![Create app in management console](../../../public/img/angular/app-create.png) - -### Redirect URIs - -The Redirect URIs field tells ZITADEL where it's allowed to redirect users after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI. -The Post-logout redirect send the users back to a route on your application after they have logged out. - -> If you are following along with the [example](https://github.com/zitadel/zitadel-angular), set the dev mode to `true`, the Redirect URIs to `http://localhost:4200/auth/callback` and Post redirect URI to `http://localhost:4200/signedout`. - -Continue and create the application. - -### Client ID - -After successful creation of the app, a pop-up will appear displaying the app's client ID. Copy the client ID, as you will need it to configure your Angular application. - -## Angular setup - -Now that you have configured your web application on the ZITADEL side, you can proceed with the integration of your Angular application. - -### Install Angular dependencies - -To connect with ZITADEL, you need to install an OAuth/OIDC client. Run the following command: - -```bash -npm install angular-oauth2-oidc -``` - -### Create and configure the auth module - -Add _OAuthModule_ to your Angular imports in _AppModule_ and provide the _AuthConfig_ in the providers' section. Also, ensure that you import the _HTTPClientModule_. - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/app.module.ts -``` - -Set _openid_, _profile_ and _email_ as scope, _code_ as responseType, and oidc to _true_. Then create an authentication service to provide the functions to authenticate your user. - -You can use Angular’s schematics to do so: - -```bash -ng g service services/authentication -``` - -Copy the following code to your service. This code provides a function `authenticate()`, which redirects the user to ZITADEL. After a successful login, ZITADEL redirects the user back to the redirect URI configured in _AuthModule_ and ZITADEL Console. Ensure that both correspond, otherwise ZITADEL will throw an error. - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/services/authentication.service.ts -``` - -Our example includes a _StatehandlerService_ that redirects the user back to the route from which they initially came. If you don't need such behavior, you can omit the following line from the `authenticate()` method above. - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/services/authentication.service.ts#L45 -``` -If you decide to use the _StatehandlerService_, include it in the `app.module`. Ensure it gets initialized first using Angular’s `APP_INITIALIZER`. You can find the service implementation in the [example](https://github.com/zitadel/zitadel-angular). - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/app.module.ts#L26-L30 -``` - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/app.module.ts#L55-L78 -``` - -### Add login to your application - -To log in a user, you need a component or a guard. - -- A component could provide a button that initiates the login flow when clicked. -- A guard initiates a login flow when a user without a stored valid access token attempts to access a protected route. - -The use of these components depends heavily on your application. In most cases, you need both. - -Generate a component like this: - -```bash -ng g component components/login -``` - -Inject the _AuthenticationService_ and call `authenticate()` on some click event. - -Do the same for the guard: -```bash -ng g guard guards/auth -``` - -This code shows the _AuthGuard_ used in ZITADEL Console. - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/guards/auth.guard.ts -``` - -Add the guard to your _RouterModule_ similar to this: - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/app-routing.module.ts#L9-L31 -``` - -> Note: Make sure you redirect the user from your callback URL to a guarded page, so the `authenticate()` method is called again, and the access token is stored. - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/app-routing.module.ts#L19-L21 -``` - -### Add logout to your application - -Call `auth.signout()` to log out the current user. Keep in mind that you can also configure a logout redirect URI if you want your users to be redirected after logout. - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/components/user/user.component.ts#L20-L22 -``` - -### Display user information - -To fetch user data, you need to call the ZITADEL's user info endpoint. This data contains sensitive information and artifacts related to the current user's identity and the scopes you defined in your _AuthConfig_. -Our _AuthenticationService_ already includes a method called _getOIDCUser()_. You can call it wherever you need this information. - -```ts reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/components/user/user.component.ts -``` - -And in your HTML file: - -```html reference -https://github.com/zitadel/zitadel-angular/blob/main/src/app/components/user/user.component.html -``` - -### Refresh token - -If you want to add a refresh token to your application, navigate to the management console application and check the box in the settings section. -Then add `offline_access` to the scopes and add the following line: - -``` -this.oauthService.setupAutomaticSilentRefresh(); -``` - -This line automatically refreshes a token before it expires. - -## Completion - -Congratulations! You have successfully integrated your Angular application with ZITADEL! - -If you get stuck, consider checking out our [example](https://github.com/zitadel/zitadel-angular) application. This application includes all the functionalities mentioned in this quick-start. You can start by cloning the repository and replacing the _AuthConfig_ in the _AppModule_ with your own settings. If you face issues, contact us or raise an issue on [GitHub](https://github.com/zitadel/zitadel). - -![App in management console](../../../public/img/angular/app-screen.png) - -### What's next? - -Now that you have enabled authentication, it's time for you to add authorization to your application using ZITADEL APIs. To do this, you can refer to the [docs](/apis/introduction) or check out the ZITADEL Management Console code on [GitHub](https://github.com/zitadel/zitadel) which uses gRPC to access data. - -For more information on how to create an Angular application, you can refer to [Angular](https://angular.io/start). If you want to learn more about the OAuth/OIDC library used above, consider reading the docs at [angular-oauth2-oidc](https://github.com/manfredsteyer/angular-oauth2-oidc). diff --git a/apps/docs/content/examples/login/flutter.mdx b/apps/docs/content/examples/login/flutter.mdx index 6bea9b636..7e95822ab 100644 --- a/apps/docs/content/examples/login/flutter.mdx +++ b/apps/docs/content/examples/login/flutter.mdx @@ -5,6 +5,8 @@ sidebar_label: Flutter --- +# Flutter Web App + This guide demonstrates how you integrate **ZITADEL** into a Flutter app. It refers to our example on [GitHub](https://github.com/zitadel/zitadel_flutter) At the end of the guide you have a mobile application for **Android**, **iOS** and **Web** with the ability to authenticate users via ZITADEL. diff --git a/apps/docs/content/examples/login/go.mdx b/apps/docs/content/examples/login/go.mdx index aaac601ba..5167a3cd6 100644 --- a/apps/docs/content/examples/login/go.mdx +++ b/apps/docs/content/examples/login/go.mdx @@ -1,5 +1,5 @@ --- -title: ZITADEL with Go +title: Go Web Application Login with ZITADEL description: "Integrate ZITADEL for user login and profile retrieval in Go web applications." sidebar_label: Go --- diff --git a/apps/docs/content/examples/login/java-spring.mdx b/apps/docs/content/examples/login/java-spring.mdx deleted file mode 100644 index 547e4f504..000000000 --- a/apps/docs/content/examples/login/java-spring.mdx +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: ZITADEL with Java Spring Boot -description: "Integrate ZITADEL into Java Spring Boot applications for user login and profile retrieval using OIDC." -sidebar_label: Java Spring Boot ---- - -This integration guide demonstrates the recommended way to incorporate ZITADEL into your Spring Boot web application. -It explains how to enable user login in your application and how to fetch data from the user info endpoint. - -By the end of this guide, your application will have login functionality and will be able to access the current user's profile. - - -This documentation references our [example](https://github.com/zitadel/zitadel-java) on GitHub. -You can either create your own application or directly run the example by providing the necessary arguments. - - -## Set up application - -Before we begin developing our application, we need to perform a few setup steps in the ZITADEL Console. -You'll need to provide some information about your app. We recommend creating a new app to start from scratch. Navigate to your Project, then add a new application at the top of the page. -Select the **Web** application type and continue. - -![Create app in management console](../../../public/img/java-spring/app-create.png) - -We recommend that you use [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all applications. - -![Create app in management console - set auth method](../../../public/img/java-spring/app-create-auth.png) - -### Redirect URIs - -The Redirect URIs field tells ZITADEL where it's allowed to redirect users after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI. -The Post-logout redirect send the users back to a route on your application after they have logged out. - - -If you are following along with the [example](https://github.com/zitadel/zitadel-java), set the dev mode to `true`, the Redirect URIs to `http://localhost:18080/webapp/login/oauth2/code/zitadel` and Post redirect URI to `http://localhost:18080/webapp`. - - -![Create app in management console - set redirectURI](../../../public/img/java-spring/app-create-redirect.png) - -Continue and create the application. - -### Client ID - -After successful creation of the app, a pop-up will appear displaying the app's client ID. Copy the client ID, as you will need it to configure your Java application. - -![Create app in management console - copy client_id](../../../public/img/java-spring/app-create-clientid.png) - -## Spring setup - -Now that you have configured your web application on the ZITADEL side, you can proceed with the integration of your Spring application. -This guide will reference the [example repository](https://github.com/zitadel/zitadel-java) and explain the necessary steps taken in there. -If your starting from scratch, you can use the Spring Initializer with the [following setup](https://start.spring.io/#!type=maven-project&language=java&platformVersion=3.2.1&packaging=jar&jvmVersion=17&dependencies=web,thymeleaf,security,oauth2-client,lombok) as a base. - -### Support classes - -To be able to take the most out of ZITADELs RBAC, we first need to create a GrantedAuthoritiesMapper, that will map the role claims (`urn:zitadel:iam:org:project:roles`) -into Spring Security `authiorities`, which can be used later on to determine the granted permissions. - -So in your application, create a 'support/zitadel' package and in there the `ZitadelGrantedAuthoritiesMapper.java`: - -```java reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/support/zitadel/ZitadelGrantedAuthoritiesMapper.java -``` - -The following two classes will provide you the possibility to access and use the user's token for requests to another API, e.g. the Spring Boot API example. - -Directly create them in the `support` package. - -```java reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/support/TokenAccessor.java -``` - -```java reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/support/AccessTokenInterceptor.java -``` - -### Application server settings - -As we have now our support classes, we can now create and configure the application server (and API client) itself. - -In a new `config` package, create first the `WebClientConfig.java`, which will provide a RestTemplate using the previously created AccessTokenInterceptor: - -```java reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/config/WebClientConfig.java -``` - -Additionally also create the `WebSecurityConfig.java` in the same package. This class will take care of the authentication, redirecting the user to the login, -mapping the claims (using the ZitadelGrantedAuthoritiesMapper) and also provide the possibility for logout: - -```java reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/config/WebSecurityConfig.java -``` - -For the authentication (and the server in general) to work, the application needs some settings, so please provide the following to your `application.yml` (resources folder): - -```yaml reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/resources/application.yml -``` - -Note that both the `issuer-uri` as well as the `client-id` are only placeholders. You can either change them in here using the values provided by ZITADEL -or pass them later on as arguments when starting the application. - -### Add pages to your application - -To be able to serve these pages create a `templates` directory in the `resources` folder. -Now create three HTML files in the new `templates` folder and copy the content of the examples: - -**index.html** - -The home page will display the Userinfo from the authentication context and the granted roles / Spring security authorities. - -```html reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/resources/templates/index.html -``` - -**fragments.html** - -The navigation to switch between the home and tasks page and allows the user to logout. - -```html reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/resources/templates/fragments.html -``` - -**tasks.html** - -The tasks page allows to interact with the Spring Boot API example and display / add new tasks. - -```html reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/resources/templates/tasks.html -``` - -**UiController** - -To serve these pages and handler their actions, you finally need a `UiController.java`: - -```java reference -https://github.com/zitadel/zitadel-java/blob/main/web/src/main/java/demo/web/UiController.java -``` - -### Start your application - -In case you've created your own application and depending on your development setup you might need to build the application first: - -```bash -mvn clean package -DskipTests -``` - -You will need to provide the `issuer-uri` (your Custom Domain) and the `client-id` previously created: - -```bash -java \ - -Dspring.security.oauth2.client.provider.zitadel.issuer-uri= \ - -Dspring.security.oauth2.client.registration.zitadel.client-id= \ - -jar web/target/web-0.0.2-SNAPSHOT.jar -``` - -This could look like: - -```bash -java \ - -Dspring.security.oauth2.client.provider.zitadel.issuer-uri=https://my-domain.zitadel.cloud \ - -Dspring.security.oauth2.client.registration.zitadel.client-id=243861220627644836@example \ - -jar web/target/web-0.0.2-SNAPSHOT.jar -``` - -If you then visit on [http://localhost:18080/webapp](http://localhost:18080/webapp) you should directly be redirected to your ZITADEL instance. -After login with your existing user you will be presented the profile page: - -![](../../../public/img/java-spring/app-profile.png) - -## Completion - -Congratulations! You have successfully integrated your Spring Boot web application with ZITADEL! - -If you get stuck, consider checking out our [example](https://github.com/zitadel/zitadel-java) application. -This application includes all the functionalities mentioned in this quickstart. -You can directly start it with your own settings. If you face issues, contact us or raise an issue on [GitHub](https://github.com/zitadel/zitadel-java/issues). diff --git a/apps/docs/content/examples/login/nextjs-b2b.mdx b/apps/docs/content/examples/login/nextjs-b2b.mdx index d64c06fc9..38b56818c 100644 --- a/apps/docs/content/examples/login/nextjs-b2b.mdx +++ b/apps/docs/content/examples/login/nextjs-b2b.mdx @@ -1,9 +1,11 @@ --- -title: ZITADEL with Next.js – A B2B Scenario +title: Next.js Multi-tenant B2B Application with ZITADEL description: "Authenticate users across multiple organizations using ZITADEL and the Next.js B2B template." sidebar_label: Next.js – B2B --- +# Next.js Web App with B2B Scenario + This is our ZITADEL [Next.js](https://nextjs.org/) B2B template. It shows how to authenticate as a user with multiple organizations. The application shows your users' roles in the selected organizations, other projects your organization is allowed to use, and other users who have roles to use the application. If you need more info on B2B use cases, consider reading our guide for the [B2B solution scenario](/guides/solution-scenarios/b2b). diff --git a/apps/docs/content/examples/login/nextjs.mdx b/apps/docs/content/examples/login/nextjs.mdx deleted file mode 100644 index 91eafa189..000000000 --- a/apps/docs/content/examples/login/nextjs.mdx +++ /dev/null @@ -1,196 +0,0 @@ ---- -title: ZITADEL with Next.js -description: "Integrate ZITADEL authentication in Next.js applications using OIDC and the Authorization Code flow." -sidebar_label: Next.js ---- - -This is our Zitadel [Next.js](https://nextjs.org/) template. It shows how to authenticate as a user and retrieve user information from the OIDC endpoint. - -> The template code is part of our zitadel-nextjs repo. Take a look [here](https://github.com/zitadel/zitadel-nextjs). - -## Getting Started - -### Install dependencies - -To install the dependencies type: - -```bash -yarn install -``` - -then to run the app: - -```bash -yarn dev -``` - -then open [http://localhost:3000](http://localhost:3000) with your browser to see the result. - -## Setup Application and Get Keys - -Before we can start building our application, we have to do a few setup steps in ZITADEL Console. -You will need to provide some information about your app. - -Navigate to your Project, then add a new application at the top of the page. -Select Web application type and continue. -We use [Authorization Code](/apis/openidoauth/grant-types#authorization-code)for our NextJS application. -Select `CODE` in the next step. This makes sure you still get a secret. Note that the secret never gets exposed on the browser and is therefore kept in a confidential environment. - -![Create app in management console](../../../public/img/nextjs/app-create.png) -### Redirect URIs - -With the Redirect URIs field, you tell ZITADEL where it is allowed to redirect users to after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI. - -> If you are following along with the [example](https://github.com/zitadel/zitadel-nextjs), set dev mode to `true` and the Redirect URIs to `http://localhost:3000/api/auth/callback/zitadel`. - -If you want to redirect the users back to a route on your application after they have logged out, add an optional redirect in the Post Logout URIs field. - -Continue and create the application. - -### Client ID - -After successful app creation, a pop-up will appear, showing the app's client ID. Copy the client ID, as you will need it to configure your NextJS app. - -## NextJS Setup - -Now that you have your web application configured on the ZITADEL side, you can go ahead and integrate your NextJS app. - -### Setup - -NextAuth.js exposes a REST API which is used by your application. -To setup your auth, create a file called `src/lib/auth.ts`. -You can directly import the ZITADEL provider from [next-auth](https://next-auth.js.org/providers/zitadel). - -```ts reference -https://github.com/zitadel/example-auth-nextjs/blob/main/src/lib/auth.ts -``` - -You can overwrite the profile callback, just append it to the ZITADEL provider. - -```ts -// ... -ZitadelProvider({ - issuer: process.env.ZITADEL_ISSUER, - clientId: process.env.ZITADEL_CLIENT_ID, - clientSecret: process.env.ZITADEL_CLIENT_SECRET, - async profile(profile) { - return { - id: profile.sub, - name: profile.name, - firstName: profile.given_name, - lastName: profile.family_name, - email: profile.email, - loginName: profile.preferred_username, - image: profile.picture, - }; - }, -}), -// ... -``` - -If you want to request a refresh token, you can overwrite the JWT callback and add the `offline_access` scope. - -```ts -// ... -async function refreshAccessToken(token: JWT): Promise { - try { - const issuer = await Issuer.discover(process.env.ZITADEL_ISSUER ?? ''); - const client = new issuer.Client({ - client_id: process.env.ZITADEL_CLIENT_ID || '', - token_endpoint_auth_method: 'none', - }); - - const { refresh_token, access_token, expires_at } = await client.refresh(token.refreshToken as string); - - return { - ...token, - accessToken: access_token, - expiresAt: (expires_at ?? 0) * 1000, - refreshToken: refresh_token, // Fall back to old refresh token - }; - } catch (error) { - console.error('Error during refreshAccessToken', error); - - return { - ...token, - error: 'RefreshAccessTokenError', - }; - } -} - -// ... -ZitadelProvider({ - issuer: process.env.ZITADEL_ISSUER, - clientId: process.env.ZITADEL_CLIENT_ID, - clientSecret: process.env.ZITADEL_CLIENT_SECRET, - async profile(profile) { - return { - id: profile.sub, - name: profile.name, - firstName: profile.given_name, - lastName: profile.family_name, - email: profile.email, - loginName: profile.preferred_username, - image: profile.picture, - }; - }, -}), -// ... -``` - -To be able to connect to ZITADEL, make sure to add `http://localhost:3000/api/auth/callback/zitadel` as redirect url to your app. -For simplicity reasons we set the default to the one that next-auth provides us. You'll be able to change the redirect later if you want to. - -Hit Create, then in the detail view of your application make sure to enable dev mode. Dev mode ensures that you can start an auth flow from a non https endpoint for testing. - -Now go to Token settings and check the checkbox for **User Info inside ID Token** to get your users name directly on authentication. - -### Environment - -Create a file `.env` in the root of the project and add the following keys to it. -You can find your Issuer Url on the application detail page in console. - -```bash reference -https://github.com/zitadel/zitadel-nextjs/blob/main/.env.example -``` - -next-auth requires a secret for all providers, so just define a random value here. - -### User interface - -Now we can start editing the homepage by modifying `src/app/profile/page.tsx`. On the homepage, your authenticated user or a Signin button is shown. - -Add the following component to render the UI elements: - -```ts reference - -https://github.com/zitadel/example-auth-nextjs/blob/main/src/app/profile/page.tsx -``` - -Note that the signIn method requires the id of our provider which is in our case `zitadel`. - -### Userinfo API - -To show user information, you can either use the idToken data, or call the userinfo endpoint. -In this example, we call the userinfo endpoint to load user data. -To implement the API, you can create a file under the `src/app/api/userinfo/` folder and call it `route.ts`. -The file should look like the following. - -```ts reference -https://github.com/zitadel/zitadel-nextjs/blob/main/src/app/api/userinfo/route.ts -``` - -### Session state - -To allow session state to be shared between pages - which improves performance, reduces network traffic and avoids component state changes while rendering - you can use the NextAuth.js Provider in `src/app/providers.tsx`. -Take a look at the template `providers.tsx`. - -```ts reference -https://github.com/zitadel/zitadel-nextjs/blob/main/src/app/providers.tsx -``` - -Last thing: create a `page.tsx` in `src/app/profile/` which renders the callback page. - -```ts reference -https://github.com/zitadel/zitadel-nextjs/blob/main/src/app/profile/page.tsx -``` diff --git a/apps/docs/content/examples/login/python-django.mdx b/apps/docs/content/examples/login/python-django.mdx deleted file mode 100644 index 0d8ca4414..000000000 --- a/apps/docs/content/examples/login/python-django.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -title: ZITADEL with Django Python -description: "Integrate ZITADEL into Python Django applications for user login and role mapping using OIDC." -sidebar_label: Django ---- - -import SetupPython from '../imports/_setup_python.mdx'; -import SetupDjango from '../imports/_setup_django.mdx'; -import SetupDotenv from '../imports/_setup_dotenv.mdx'; - -This integration guide demonstrates the recommended way to incorporate ZITADEL into your Django Python application. -It explains how to enable user login in your application and how to incorporate the ZITADEL users into the existing AuthenticationBackend. - -By the end of this guide, your application will have login functionality with basic role mapping, admin console and polls as described in the Django guide. - - -This documentation references our [example](https://github.com/zitadel/example-django-python-oidc) on GitHub. - - -## ZITADEL setup - -Before we can start building our application, we have to do a few setup steps in ZITADEL Management Console. - -### Project roles - -The Example expects [user roles](/guides/integrate/retrieve-user-roles) to be returned after login. -This example expects 3 different roles: -- `admin`: superuser with permissions to use the admin console -- `staff`: user with permissions to see results of the polls -- `user`: normal user with permission to vote on the existing polls - -In your project settings make sure the "Assert Roles On Authentication" is enabled. - -![Project settings in management console](../../../public/img/django/project-settings.png) - -In the project Role tab, add 3 special roles: - -- `admin` -- `staff` -- `user` - -If none of the roles is provided as a user, the user in Django will not be created. - -![Project roles in management console](../../../public/img/django/project-roles.png) - -Finally, we can assign the roles to users in the project's `Role Assignments` tab. - -![Project role assignments in management console](../../../public/img/django/project-authorizations.png) - -### Set up application and obtain secrets - -Next you will need to provide some information about your app. - -In your Project, add a new application at the top of the page. -Select Web application type and continue. -We use [Authorization Code](/apis/openidoauth/grant-types#authorization-code) for our Django application. - -![Create app in management console](../../../public/img/django/app-create.png) - -Select `CODE` in the next step. This makes sure you still get a secret. Note that the secret never gets exposed on the browser and is therefore kept in a confidential environment. Safe the generated secret for later use. - -![Configure app authentication method in management console](../../../public/img/django/app-auth-method.png) - -With the Redirect URIs field, you tell ZITADEL where it is allowed to redirect users to after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI. - -For the example application we are writing use: - -- `http://localhost:8000/oidc/callback/` as Redirect URI -- `http://localhost:8000/oidc/logout/` as post-logout URI. - -![Configure app redirects management console](../../../public/img/django/app-redirects.png) - -After the final step you are presented with a client ID and secret. -Copy and paste them to a safe location for later use by the application. -The secret will not be displayed again, but you can regenerate one if you loose it. - -## Setup new Django application - -### Setup Python - - - -### Install dependencies - -For this example we need the following dependencies: -- `django`: to create an API with django -- `python-dotenv`: to use environment variables in the settings -- `mozilla-django-oidc`: client-side OIDC functionality - -For the dependencies we need a requirements.txt-file with the following content: - -```python reference -https://github.com/zitadel/example-python-django-oidc/blob/main/requirements.txt -``` - -Then install all dependencies with: -```bash -python -m pip install -U requirements.txt -``` - -The used base is the "Writing your first Django app" from the Django documentation under [https://docs.djangoproject.com/en/5.0/intro/](https://docs.djangoproject.com/en/5.0/intro/), -which has documented additional parts in to use [mozilla-django-oidc](https://github.com/mozilla/mozilla-django-oidc) to integrate ZITADEL as AuthenticationBackend. - - -Skip this step if you are connecting ZITADEL to an existing application. - - -## Define the Django app - -### Create the settings.py to include mozilla-django-oidc - -To use the mozilla-django-oidc as AuthenticationBackend, there are several things to add to the settings.py, as described in the [documentation "Add settings to settings.py"](https://mozilla-django-oidc.readthedocs.io/en/stable/installation.html#add-settings-to-settings-py): - -Add INSTALLED_APPS: - -```python -INSTALLED_APPS = [ - ... - "mozilla_django_oidc", # Load after auth - ... -] -``` - -Add MIDDLEWARE: - -```python -MIDDLEWARE = [ - #... - "mozilla_django_oidc.middleware.SessionRefresh", -] -``` - -Add AUTHENTICATION_BACKENDS: - -```python -AUTHENTICATION_BACKENDS = ( - "mysite.backend.PermissionBackend", -) -``` - -Add settings: - -```python reference -https://github.com/zitadel/example-python-django-oidc/blob/main/mysite/settings.py#L130-L174 -``` - -and create a ".env"-file in the root folder with the settings: - -```bash -ZITADEL_PROJECT = "ID of the project you created the application in ZITADEL" -OIDC_RP_CLIENT_ID = "ClientID provided by the created application in ZITADEL" -OIDC_RP_CLIENT_SECRET = "ClientSecret provided by the created application in ZITADEL" -OIDC_OP_BASE_URL = "Base URL to the ZITADEL instance" -``` - -which should then look something like this: - -```bash -ZITADEL_PROJECT = "249703732336418457" -OIDC_RP_CLIENT_ID = "249703852243222581@python" -OIDC_RP_CLIENT_SECRET = "Zy3OOHaMBTj2sfamW77Vak5BeQ3nEpOf7suPKTnJKaScMh0lPJqUeDOZmgL3bds0" -OIDC_OP_BASE_URL = "https://example.zitadel.cloud" -``` - -### AuthenticationBackend definition - -To create and update the users regarding the roles given in the authentications in ZITADEL a Subclass of OIDCAuthenticationBackend has to be created: - -```python reference -https://github.com/zitadel/example-python-django-oidc/blob/main/mysite/backend.py -``` - -Which handles the users differently depending on if there are roles associated to: -- `admin` -> superuser -- `staff` -> staff -- `user` -> user -- `no role` -> no user gets created - -### URLs - -To handle the callback and logout the urls have to be added to the urls.py: -```python -urlpatterns = [ - #... - path("oidc/", include("mozilla_django_oidc.urls")), -] -``` - -So it should like something like this: -```python reference -https://github.com/zitadel/example-python-django-oidc/blob/main/mysite/urls.py#L21-L28 -``` - -## Configure and run the application - - -Never store and commit secrets in the ".env" or settings.py file - - -### Authentication and authorization - -To check the authentication and authorization, the views in the polls application are extended with decorators: - -```python reference -https://github.com/zitadel/example-python-django-oidc/blob/main/mysite/views.py -``` - -- `@method_decorator(login_required, name="dispatch")`: means that the user has to be logged in Django, which only happens if you have one of the 3 roles("admin", "staff" or "user") -- `@method_decorator(staff_member_required, name="dispatch")`: means you have to have at least a staff user ("admin" or "staff") -- `/admin/`: all admin sides are only accessible if you have a superuser with the role "admin" - - -Additional permission checks could be done with "permission_required" from "django.contrib.auth.decorators" also described in the [Django documentation](https://docs.djangoproject.com/en/5.0/topics/auth/customizing/#custom-permissions). - - -### DB - -Create and run migrations: - -```bash -python manage.py migrate -``` - -### Run - -You can use a local Django server to test the application. - -```bash -python manage.py runserver -``` - -Visit http://localhost:8000/polls or http://localhost:8000/admin and click around. - -## Completion - -Congratulations! You have successfully integrated your Python Django application with ZITADEL! - -If you get stuck, consider checking out our [example](https://github.com/zitadel/example-python-django-oidc) application. This application includes all the functionalities mentioned in this quick-start. You can start by cloning the repository and defining the settings in the settings.py. If you face issues, contact us or raise an issue on [GitHub](https://github.com/zitadel/example-python-django-oidc/issues). - -### What's next? - -Now that you have enabled authentication, it's time for you to add more authorizations to your application using ZITADEL APIs. To do this, you can refer to the [docs](/apis/introduction) or check out the ZITADEL Management Console code on [GitHub](https://github.com/zitadel/zitadel) which uses gRPC and OpenAPI to access data. diff --git a/apps/docs/content/examples/login/react.mdx b/apps/docs/content/examples/login/react.mdx deleted file mode 100644 index 5778cf219..000000000 --- a/apps/docs/content/examples/login/react.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: ZITADEL with React -description: "Integrate ZITADEL into React applications for user login and profile management using OIDC and PKCE." -sidebar_label: React ---- - -This integration guide demonstrates the recommended way to incorporate ZITADEL into your React application. -It explains how to enable user login in your application and how to fetch data from the user info endpoint. - -By the end of this guide, your application will have login functionality and will be able to access the current user's profile. - - -This documentation references our [example](https://github.com/zitadel/zitadel-react) on GitHub. -It also uses the @zitadel/react package with its default settings. - - -## Set up application and obtain keys - -Before we begin developing our application, we need to perform a few setup steps in the ZITADEL Console. -You'll need to provide some information about your app. -We recommend creating a new app to start from scratch. -Navigate to your project, then add a new application at the top of the page. -Select the **User Agent** application type and continue. -We recommend that you use [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all single page applications. - -![Create app in management console](../../../public/img/react/app-create.png) - -### Redirect URIs - -The redirect URIs field tells ZITADEL where it's allowed to redirect users after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI. -The post logout redirect sends your users back to a public route on your application after they have logged out. - - -If you are following along with the [example](https://github.com/zitadel/zitadel-react), set the dev mode switch to `true`. -Configure a redirect URIs to \http://localhost:3000/callback and a post redirect URI to \http://localhost:3000/. - - -Continue and create the application. - -### Copy Client ID - -After successful creation of the app, make sure copy the client ID, as you will need it to configure your React application. - -## Create a project role "admin" and assign it to your user - -Also note the Project ID, as you will need it to configure your React application. - -![](../../../public/img/react/project-role.png) - -![](../../../public/img/react/project-authz.png) - -If you want to read your users roles from the user info endpoint, make sure to enable the checkbox in your project. - -## React setup - -Now that you have configured your web application on the ZITADEL side, you can proceed with the integration of your React application. - -### Install React dependencies - -To conveniently connect with ZITADEL, you can install the [@zitadel/react NPM package](https://www.npmjs.com/package/@zitadel/react). Run the following command: - -```bash -yarn add @zitadel/react -``` - -### Create and configure the auth service - -The @zitadel/react package provides a `createZitadelAuth()` function which sets some defaults and initializes the underlying [oidc-client-ts](https://github.com/authts/oidc-client-ts) `UserManager` class. -You can overwrite all the defaults with the arguments you pass to `createZitadelAuth()`. - -Export the object returned from `createZitadelAuth()` - -### Initialize user manager - -```ts reference -https://github.com/zitadel/zitadel-react/blob/main/src/App.tsx -``` - -### Add two new components to your application - -First, add the component which prompts the user to login. - -```ts reference -https://github.com/zitadel/zitadel-react/blob/main/src/components/Login.tsx -``` - -Then create the component for the page where the users will be redirected. -It loads the user info endpoint once the code flow completes and prints all the information. - -```ts reference -https://github.com/zitadel/zitadel-react/blob/main/src/components/Callback.tsx -``` - -You can now read a user's role to show protected areas of the application. - -### Run - -Finally, you can start your application by running the following: - -``` -yarn start -``` - -## Completion - -Congratulations! You have successfully integrated your React application with ZITADEL! - -If you get stuck, consider checking out the [ZITADEL React example application](https://github.com/zitadel/zitadel-react). -This application includes all the functionalities mentioned in this quickstart. -You can start by cloning the repository and changing the arguments to `createZitadelAuth` to fit your requirements. -If you face issues, contact us or [raise an issue on GitHub](https://github.com/zitadel/zitadel-react/issues). - -![App in management console](../../../public/img/react/app-screen.png) - -### What's next? - -Now that you have enabled authentication, you are ready to add authorization to your application by using ZITADEL APIs. -To do this, [refer to the API docs](/apis/introduction) or check out [the ZITADEL Management Console code on GitHub](https://github.com/zitadel/zitadel) which uses gRPC to access data. - -For more information on how to create a React application, you can refer to [Create React App](https://github.com/facebook/create-react-app). -If you want to learn more about the libraries wrapped by [@zitadel/react](https://www.npmjs.com/package/@zitadel/react), read the docs for [oidc-client-ts](https://github.com/authts/oidc-client-ts). diff --git a/apps/docs/content/examples/login/symfony.mdx b/apps/docs/content/examples/login/symfony.mdx deleted file mode 100644 index 512f02ea0..000000000 --- a/apps/docs/content/examples/login/symfony.mdx +++ /dev/null @@ -1,409 +0,0 @@ ---- -title: ZITADEL with Symfony PHP -description: "Integrate ZITADEL into Symfony PHP applications for user login and profile management using OIDC." -sidebar_label: Symfony ---- - -This integration guide demonstrates the recommended way to incorporate ZITADEL into your Symfony PHP application. -It explains how to enable user login in your application and how to fetch data from the user info endpoint. - -By the end of this guide, your application will have login functionality with basic role mapping, access the current user's profile and a user list accessible by admins. - - -This documentation references our [example](https://github.com/zitadel/example-symfony-oidc) on GitHub. - - -## ZITADEL setup - -Before we can start building our application, we have to do a few setup steps in ZITADEL Console. - -### Project roles - -The Example expects [user roles](/guides/integrate/retrieve-user-roles) to be returned after login. -Symfony uses `ROLE_USER` format. -The application will take care of upper-casing and prefixing for us. -Inside ZITADEL, you can use regular lower-case role names without prefixes, if you prefer. - -> Symfony automatically assigns `ROLE_USER` to any authenticated user. - -In your project settings make sure the "Assert Roles On Authentication" is enabled. - -![Project settings in management console](../../../public/img/symfony/project-settings.png) - -In the project Role tab, add 2 special roles: - - - `admin`: Assigned to users that need access to the user list. - - `foo`: Random role for display purposes - -A `user` role is not required. This role is assumed by default for any authenticated user in Symfony. - -![Project roles in management console](../../../public/img/symfony/project-roles.png) - -Finally, we can assign the roles to users in the project's "Role Assignments" section. - -![Project role assignments in management console](../../../public/img/symfony/project-authorizations.png) - -### Set up application and obtain secrets - -Next you will need to provide some information about your app. - -In your Project, add a new application at the top of the page. -Select Web application type and continue. -We use [Authorization Code](/apis/openidoauth/grant-types#authorization-code)for our Symfony application. - -![Create app in management console](../../../public/img/symfony/app-create.png) - -Select `CODE` in the next step. This makes sure you still get a secret. Note that the secret never gets exposed on the browser and is therefore kept in a confidential environment. Safe the generated - -![Configure app authentication method in management console](../../../public/img/symfony/app-auth-method.png) - -With the Redirect URIs field, you tell ZITADEL where it is allowed to redirect users to after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI. - -For the example application we are writing use: - -- `http://localhost:8000/login_check` as Redirect URI -- `http://localhost:8000/logout` as post-logout URI. - -![Configure app redirects management console](../../../public/img/symfony/app-redirects.png) - -After the final step you are presented with a client ID and secret. -Copy and paste them to a safe location for later use by the application. -The secret will not be displayed again, but you can regenerate one if you loose it. - -## Setup new Symfony application - -Now that you have configured your web application on the ZITADEL side, you can proceed with the integration of your Symfony application. -The example is build on a [generated Symfony web app](https://symfony.com/doc/current/setup.html#creating-symfony-applications), using the following command: - - -Skip this step if you are connecting ZITADEL to an existing application. - - -```bash -symfony new my_project_directory --version="7.0.*" --webapp -cd my_project_directory -``` - - -The remainder of this guide assumes a Symfony project which already includes all web app bundles, such as security, routing and ORM. -If you are using this guide against an existing project you must make sure the required bundles are installed using the `composer require` command. - - -### Install Symfony dependencies - -To connect with ZITADEL through OpenID connect, you need to install the [Symfony OIDC bundle](https://github.com/Drenso/symfony-oidc). Run the following command: - -```bash -composer require drenso/symfony-oidc-bundle -``` - -## Define the Symfony app - -### Create a User class - -First, we need to create a User class for the database, so we can persist user info between requests. In this case you don't need password authentication. -Email addresses are not unique for ZITADEL users. There can be multiple user accounts with the same email address. -See [User Constraints](/guides/manage/console/users-overview#considerations) for more details. -We will use the User Info `sub` claim as unique "display" name for the user. `sub` equals the unique User ID from ZITADEL. -This creates a User Repository and Entity that implements the `UserInterface`: - - -You can skip this step, if you already have an existing User object in your project. - - -```bash -php bin/console make:user - - The name of the security user class (e.g. User) [User]: - > User - - Do you want to store user data in the database (via Doctrine)? (yes/no) [yes]: - > yes - - Enter a property name that will be the unique "display" name for the user (e.g. email, username, uuid) [email]: - > sub - - Will this app need to hash/check user passwords? Choose No if passwords are not needed or will be checked/hashed by some other system (e.g. a single sign-on server). - - Does this app need to hash/check user passwords? (yes/no) [yes]: - > no -``` - -Next, extend the User Entity with properties that we will obtain from ZITADEL and use in the application later. - -> None of the following properties are required for authentication, but show how we can map User Info to a Symfony User Entity later. You can adjust the properties how you wish for your application. - -```bash -php bin/console make:entity - - Class name of the entity to create or update (e.g. GrumpyElephant): - > User - - Your entity already exists! So let's add some new fields! - - New property name (press to stop adding fields): - > display_name - - Field type (enter ? to see all types) [string]: - > string - - Field length [255]: - > 255 - - Can this field be null in the database (nullable) (yes/no) [no]: - > yes - - updated: src/Entity/User.php - - Add another property? Enter the property name (or press to stop adding fields): - > full_name - - Field type (enter ? to see all types) [string]: - > string - - Field length [255]: - > - - Can this field be null in the database (nullable) (yes/no) [no]: - > yes - - updated: src/Entity/User.php - - Add another property? Enter the property name (or press to stop adding fields): - > email - - Field type (enter ? to see all types) [string]: - > string - - Field length [255]: - > 255 - - Can this field be null in the database (nullable) (yes/no) [no]: - > yes - - updated: src/Entity/User.php - - Add another property? Enter the property name (or press to stop adding fields): - > email_verified - - Field type (enter ? to see all types) [string]: - > boolean - - Can this field be null in the database (nullable) (yes/no) [no]: - > yes - - updated: src/Entity/User.php - - Add another property? Enter the property name (or press to stop adding fields): - > created_at - - Field type (enter ? to see all types) [datetime_immutable]: - > datetime_immutable - - Can this field be null in the database (nullable) (yes/no) [no]: - > no - - updated: src/Entity/User.php - - Add another property? Enter the property name (or press to stop adding fields): - > updated_at - - Field type (enter ? to see all types) [datetime_immutable]: - > datetime_immutable - - Can this field be null in the database (nullable) (yes/no) [no]: - > no - - updated: src/Entity/User.php - - Add another property? Enter the property name (or press to stop adding fields): - > - - Success! -``` - -Now edit `src/Entity/User.php` to add some methods to pretty-print user data later in this example. Add import near the top of the file: - -```php -use DateTimeInterface; -``` - -And extend the User class with this methods: - -```php -class User implements UserInterface -{ - ... - - public function implodeRoles(): string - { - return implode(', ', $this->getRoles()); - } - - public function formatCreatedAt(): string - { - return $this->created_at->format(DateTimeInterface::W3C); - } - - public function formatUpdatedAt(): string - { - return $this->updated_at->format(DateTimeInterface::W3C); - } -} -``` - -When you are done, the User Entity should look something like: - -```php reference -https://github.com/zitadel/example-symfony-oidc/blob/main/src/Entity/User.php -``` - -Edit the User Repository to have a `findOneBySub` method, used later for OIDC User Info updates. - -```php reference -https://github.com/zitadel/example-symfony-oidc/blob/main/src/Repository/UserRepository.php -``` - -### Create a Security Provider - -Next you will need to create a Security Provider that integrates the OIDC flow between Symfony and ZITADEL. -Create a `ZitadelUserProvider` which implements `UserProviderInterface`, `OidcUserProviderInterface` and `LoggerAwareInterface`. -`LoggerAwareInterface` is optional if you want debug logging. - -> We called this a `ZitadelUserProvider` because it carries a custom scope and claim mapping from ZITADEL roles to the Symfony role system. - -```php reference -https://github.com/zitadel/example-symfony-oidc/blob/main/src/Security/ZitadelUserProvider.php -``` - -You can customize the User Info that is obtained and stored by adjusting the `SCOPES` constant, the `updateUserEntity` method and the User Entity. - -### Controllers and templates - -We need to create a couple of Controllers and templates to define the app. - -#### Index - -The index controller serves a public page on the `/` route and provides some basic links to the authenticated sections of the app. - -```php reference -https://github.com/zitadel/example-symfony-oidc/blob/main/src/Controller/IndexController.php -``` - -The index template: - -```twig reference -https://github.com/zitadel/example-symfony-oidc/blob/main/templates/index.html.twig -``` - -#### Login - -The login controller initiates the OIDC login flow by creating a Auth request and redirecting the user to ZITADEL. - -```php reference -https://github.com/zitadel/example-symfony-oidc/blob/main/src/Controller/LoginController.php -``` - -#### Profile - -The profile controller displays User Info of the currently authenticated user. -Any authenticated user will have access to this page. - -```php reference -https://github.com/zitadel/example-symfony-oidc/blob/main/src/Controller/ProfileController.php -``` - -The profile template maps the User Entity to a HTML page. - -```twig reference -https://github.com/zitadel/example-symfony-oidc/blob/main/templates/profile.html.twig -``` - -#### User list - -The user list controller displays all users from the database that were created during OIDC login. -Only users with an administrator role will have access to this page. - -```php reference -https://github.com/zitadel/example-symfony-oidc/blob/main/src/Controller/UserListController.php -``` - -```twig reference -https://github.com/zitadel/example-symfony-oidc/blob/main/templates/user_list.html.twig -``` - -## Configure and run the application - - -Never store and commit secrets in a `.env` file. Use a `env.local` file instead and make sure the file is in `.gitignore`. - - -### Database - -Make sure you have a database configured in `.env` or `.env.local`. This example uses a local sqlite file to simplify setup: - -```sh -DATABASE_URL="sqlite:///%kernel.project_dir%/var/data.db" -``` - -Create and run migrations: - -```bash -php bin/console make:migration -php bin/console doctrine:migrations:migrate -``` - -### Security - -A firewall needs to be defined along with roles based access control rules. -In the following example we define the `zitadel_user_provider` as the security class we wrote earlier. We configure the main firewall to use the `zitadel_user_provider` and listen for logout requests on the `/logout` path. We tell the oidc module to enable End Session support. - -In the `access_control` section we protect the `/users` and `/profile` routes based on roles. Roles are mapped from ZITADEL to Symfony in the `ZitadelUserProvider` we wrote earlier. - -```yaml reference -https://github.com/zitadel/example-symfony-oidc/blob/main/config/packages/security.yaml -``` - -### OIDC - -The generated [`dresno_oidc.yaml`](https://github.com/zitadel/example-symfony-oidc/blob/main/config/packages/drenso_oidc.yaml) file can be edited to customize behavior of the OIDC bundle. For this example we stick with the default and use environment variables to connect to ZITADEL. - -Edit `.env.local` to contain the details from the [Application setup section](#set-up-application-and-obtain-keys). - -```sh -OIDC_WELL_KNOWN_URL="https://tims-zitadel-instance-oj7iry.zitadel.cloud/.well-known/openid-configuration" -OIDC_CLIENT_ID="248680248240075805@dev" -OIDC_CLIENT_SECRET="BJPhEJULSUXseC4geqg5Yg4wWMoy7RgZKar86mbIpt8ZekC5kixMzYGcXLDeeJv7" -``` - -> The well-known URL needs to be adjusted to your own Custom Domain. - -Activate the route that is used as callback by the OIDC bundle: - -```yaml reference -https://github.com/zitadel/example-symfony-oidc/blob/main/config/routes.yaml#L6-L7 -``` - -### Run - -You can use a local Symfony server to test the application. - -```bash -symfony server:start --no-tls -``` - -Visit http://localhost:8000 and click around. -When you go to profile, you will be redirected to login your user on ZITADEL. -After login, you should see some profile data of the current user. -Upon clicking logout, you are redirected to the homepage. -Now you can click "users" and log in with an account that has the administrator role. - -## Completion - -Congratulations! You have successfully integrated your Symfony application with ZITADEL! - -If you get stuck, consider checking out our [example](https://github.com/zitadel/example-symfony-oidc) application. This application includes all the functionalities mentioned in this quick-start. You can start by cloning the repository and defining a `.env.local` with your settings. If you face issues, contact us or raise an issue on [GitHub](https://github.com/zitadel/example-symfony-oidc/issues). - -### What's next? - -Now that you have enabled authentication, it's time for you to add more authorizations to your application using ZITADEL APIs. To do this, you can refer to the [docs](/apis/introduction) or check out the ZITADEL Management Console code on [GitHub](https://github.com/zitadel/zitadel) which uses gRPC and OpenAPI to access data. diff --git a/apps/docs/content/examples/login/vue.mdx b/apps/docs/content/examples/login/vue.mdx deleted file mode 100644 index 80fa1c2dd..000000000 --- a/apps/docs/content/examples/login/vue.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: ZITADEL with Vue -description: "Integrate ZITADEL with a Vue application to enable secure user login and fetch user profile data using OIDC" -sidebar_label: Vue ---- - -This integration guide demonstrates the recommended way to incorporate ZITADEL into your Vue application. -It explains how to enable user login in your application and how to fetch data from the user info endpoint. - -By the end of this guide, your application will have login functionality and will be able to access the current user's profile. - - -This documentation references our [example](https://github.com/zitadel/zitadel-vue) on GitHub. -It also uses the @zitadel/vue package with its default settings. - - -## Set up application and obtain keys - -Before we begin developing our application, we need to perform a few setup steps in the ZITADEL Management Console. -You'll need to provide some information about your app. -We recommend creating a new app to start from scratch. -Navigate to your project, then add a new application at the top of the page. -Select the **User Agent** application type and continue. -We recommend that you use [Proof Key for Code Exchange (PKCE)](/apis/openidoauth/grant-types#proof-key-for-code-exchange) for all single page applications. - -![Create app in management console](../../../public/img/vue/app-create.png) - -### Redirect URIs - -The redirect URIs field tells ZITADEL where it's allowed to redirect users after authentication. For development, you can set dev mode to `true` to enable insecure HTTP and redirect to a `localhost` URI. -The post logout redirect sends your users back to a public route on your application after they have logged out. - - -If you are following along with the [example](https://github.com/zitadel/zitadel-vue), set the dev mode switch to `true`. -Configure a redirect URIs to *http://localhost:5173/auth/signinwin/zitadel* and a post redirect URI to *http://localhost:5173/*. - - -Continue and create the application. - -### Refresh Token and Client ID - -After the successful creation of the app, make sure you tick the checkbox to enable refresh tokens. -Also, copy the client ID, as you will need it to configure your Vue application. - -![](../../../public/img/vue/tick-refresh-token.png) - -## Create a project role "admin" and assign it to your user - -Also note the Project ID, as you will need it to configure your Vue application. - -![](../../../public/img/vue/project-role.png) - -![](../../../public/img/vue/project-authz.png) - -## Vue setup - -Now that you have configured your web application on the ZITADEL side, you can proceed with the integration of your Vue application. - -### Install Vue dependencies - -To conveniently connect with ZITADEL, you can install the [@zitadel/vue NPM package](https://www.npmjs.com/package/@zitadel/vue). Run the following command: - -```bash -npm install --save @zitadel/vue -``` - -### Create and configure the auth service - -The @zitadel/vue package provides a `createZITADELAuth()` function which sets some defaults and calls the underlying [vue-oidc-client packages](https://github.com/soukoku/vue-oidc-client) `createOidcAuth()` function. -You can overwrite all the defaults with the arguments you pass to `createZITADELAuth()`. - -Export the object returned from `createZITADELAuth()` - -```ts reference -https://github.com/zitadel/zitadel-vue/blob/main/src/services/zitadelAuth.ts -``` - -### Register the auth service in your global variables when bootstrapping Vue - -```ts reference -https://github.com/zitadel/zitadel-vue/blob/main/src/main.ts -``` - -### Add three new views to your application - -The restricted admin view will only be shown if the user is authenticated and has the role "admin" in the apps project in ZITADEL. - -```ts reference -https://github.com/zitadel/zitadel-vue/blob/main/src/views/AdminView.vue -``` - -The restricted login view is shown to all authenticated users. -It prints all the information it gets from the token and from the user info endpoint. - -```ts reference -https://github.com/zitadel/zitadel-vue/blob/main/src/views/LoginView.vue -``` - -The public no access view is shown to authenticated users who navigate to a page they don't have access to based on their roles. - -```ts reference -https://github.com/zitadel/zitadel-vue/blob/main/src/views/NoAccessView.vue -``` - -### Add protected routes to your new pages as well as a Signout link - -Note that we conditionally render the admin view or the no access view based on the user's roles. - -```ts reference -https://github.com/zitadel/zitadel-vue/blob/main/src/router/index.ts -``` - -## Completion - -Congratulations! You have successfully integrated your Vue application with ZITADEL! - -If you get stuck, consider checking out the [ZITADEL Vue example application](https://github.com/zitadel/zitadel-vue). -This application includes all the functionalities mentioned in this quickstart. -You can start by cloning the repository and change the arguments to createZITADELAuth so they fit your requirements. -If you face issues, contact us or [raise an issue on GitHub](https://github.com/zitadel/zitadel-vue/issues). - -![App in management console](../../../public/img/vue/app-screen.png) - -### What's next? - -Now that you have enabled authentication, you are ready to call add authorization to your application using ZITADEL APIs. -To do this, [refer to the API docs](/apis/introduction) or check out [the ZITADEL Management Console code on GitHub](https://github.com/zitadel/zitadel) which uses gRPC to access data. - -For more information on how to create an Vue application, you can refer to [Vue](https://vuejs.org/guide/quick-start.html). -If you want to learn more about the libraries wrapped by [@zitadel/vue](https://www.npmjs.com/package/@zitadel/vue), [read the docs for vue-oidc-client](https://github.com/soukoku/vue-oidc-client/wiki/V1-Docs). diff --git a/apps/docs/content/examples/secure-api/go.mdx b/apps/docs/content/examples/secure-api/go.mdx index cdaf7cea4..84b343b9a 100644 --- a/apps/docs/content/examples/secure-api/go.mdx +++ b/apps/docs/content/examples/secure-api/go.mdx @@ -1,7 +1,7 @@ --- -title: ZITADEL with Go +title: Secure Go API Application with ZITADEL description: "Secure Go APIs using OAuth 2.0 Token Introspection with ZITADEL and role-based authorization." -sidebar_label: Go +sidebar_label: Go API --- This integration guide shows you how to integrate **ZITADEL** into your Go API. It demonstrates how to secure your API using diff --git a/apps/docs/content/examples/secure-api/java-spring.mdx b/apps/docs/content/examples/secure-api/java-spring.mdx index b434294d5..787f001b9 100644 --- a/apps/docs/content/examples/secure-api/java-spring.mdx +++ b/apps/docs/content/examples/secure-api/java-spring.mdx @@ -1,8 +1,9 @@ --- -title: ZITADEL with Java Spring Boot +title: Secure Java Spring Boot API Application with ZITADEL description: "Secure Java Spring Boot APIs using OAuth 2.0 Token Introspection with ZITADEL." sidebar_label: Java Spring Boot --- +import { GithubCodeBlock } from '@/components/github-code-block'; This integration guide shows you how to integrate **ZITADEL** into your Java Spring Boot API. It demonstrates how to secure your API using OAuth 2 Token Introspection. @@ -44,9 +45,7 @@ into Spring Security `authiorities`, which can be used later on to determine the So in your application, create a `support/zitadel` package and in there the `CustomAuthorityOpaqueTokenIntrospector.java`: -```java reference -https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/support/zitadel/CustomAuthorityOpaqueTokenIntrospector.java -``` + ### Application server settings @@ -56,15 +55,11 @@ In a new `config` package, create the `WebSecurityConfig.java`. This class will take care of the authorization by require the calls on `/api/tasks` to be authorized. Any other endpoint will be public by default. It will also use the just created CustomAuthorityOpaqueTokenIntrospector for the introspection call: -```java reference -https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/config/WebSecurityConfig.java -``` + For the authorization (and the server in general) to work, the application needs some settings, so please provide the following to your `application.yml` (resources folder): -```yaml reference -https://github.com/zitadel/zitadel-java/blob/main/api/src/main/resources/application.yml -``` + Note that the `introspection-uri`, `client-id` and `client-secret` are only placeholders. You can either change them in here using the values provided by ZITADEL or pass them later on as arguments when starting the application. @@ -80,9 +75,7 @@ If authorization is required, the token must not be expired and the API has to b For tests we will use a Personal Access Token or the [Java Spring web example](../login/java-spring). -```java reference -https://github.com/zitadel/zitadel-java/blob/main/api/src/main/java/demo/app/api/ExampleController.java -``` + ## Test API diff --git a/apps/docs/content/examples/secure-api/nodejs-nestjs.mdx b/apps/docs/content/examples/secure-api/nodejs-nestjs.mdx index f4b5538e4..24cce0ef7 100644 --- a/apps/docs/content/examples/secure-api/nodejs-nestjs.mdx +++ b/apps/docs/content/examples/secure-api/nodejs-nestjs.mdx @@ -1,11 +1,14 @@ --- -title: ZITADEL with Node.js +title: Secure Nest.js API Application with ZITADEL description: "Secure Node.js APIs in NestJS by validating access tokens with ZITADEL's introspection endpoint." sidebar_label: NestJS --- ## ZITADEL with Node.js (NestJS) +Community Contribution This example was created by a member of the ZITADEL community. It’s a great resource for seeing how others are building, but please note it is maintained by the community rather than the ZITADEL core team. + + This documentation section guides you through the process of integrating ZITADEL into your Node.js backend using the NestJS framework. The provided example demonstrates authentication using an OIDC (OAuth2) token introspection strategy with a ZITADEL service account for machine-to-machine communication. ## Overview diff --git a/apps/docs/content/examples/secure-api/pylon.mdx b/apps/docs/content/examples/secure-api/pylon.mdx index b82737e3f..872140b60 100644 --- a/apps/docs/content/examples/secure-api/pylon.mdx +++ b/apps/docs/content/examples/secure-api/pylon.mdx @@ -1,5 +1,5 @@ --- -title: ZITADEL with Pylon +title: Secure Pylon API Application with ZITADEL description: "Integrate ZITADEL with Pylon services by validating tokens and checking permissions for secure API endpoints" sidebar_label: Pylon --- diff --git a/apps/docs/content/examples/secure-api/python-django.mdx b/apps/docs/content/examples/secure-api/python-django.mdx index 4b9814ad0..033bc2dbc 100644 --- a/apps/docs/content/examples/secure-api/python-django.mdx +++ b/apps/docs/content/examples/secure-api/python-django.mdx @@ -1,13 +1,14 @@ --- -title: ZITADEL with Django Python +title: Secure Django (Python) API Application with ZITADEL description: "Integrate ZITADEL with Django Python to validate tokens and check permissions for secure API access using OIDC protocol standards" -sidebar_label: Django +sidebar_label: Django API --- import AppJWT from '../imports/_app_jwt.mdx'; import ServiceAccountJWT from '../imports/_serviceaccount_jwt.mdx'; import ServiceAccountRole from '../imports/_serviceaccount_role.mdx'; import SetupPython from '../imports/_setup_python.mdx'; +import { GithubCodeBlock } from '@/components/github-code-block'; This integration guide demonstrates the recommended way to incorporate ZITADEL into your Django Python application. It explains how to check the token validity in the API and how to check for permissions. @@ -15,7 +16,7 @@ It explains how to check the token validity in the API and how to check for perm By the end of this guide, your application will have three different endpoints that are public, private (valid token) and private-scoped (valid token with a specific role). -This documentation references our [example](https://github.com/zitadel/example-django-python-oauth) on GitHub. +This documentation references our [example](https://github.com/zitadel/example-python-django-oauth) on GitHub. ## ZITADEL setup @@ -62,9 +63,7 @@ For this example we need the following dependencies: For the dependencies we need a requirements.txt-file with the following content: -```python reference -https://github.com/zitadel/example-python-django-oauth/blob/main/requirements.txt -``` + Then install all dependencies with: ```bash @@ -82,9 +81,7 @@ django-admin startproject myapi . There is info needed for the introspection calls, which we put into the settings.py: -```python reference -https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/settings.py#L125-L133 -``` + and create a ".env"-file in the root folder with the settings as an example: ```bash @@ -106,25 +103,16 @@ API_PRIVATE_KEY_FILE_PATH = '/tmp/example/250719519163548112.json' To validate the tokens, we need a validator which can be called in the event of API-calls. validator.py: - -```python reference -https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/validator.py -``` + ### Requests and URLs We define 3 different endpoints which differ in terms of requirements. views.py: - -```python reference -https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/views.py -``` + To handle endpoints the urls have to be added to the urls.py: - -```python reference -https://github.com/zitadel/example-python-django-oauth/blob/main/myapi/urls.py -``` + ### DB diff --git a/apps/docs/content/examples/secure-api/python-flask.mdx b/apps/docs/content/examples/secure-api/python-flask.mdx index 164dda7ff..670061c10 100644 --- a/apps/docs/content/examples/secure-api/python-flask.mdx +++ b/apps/docs/content/examples/secure-api/python-flask.mdx @@ -1,7 +1,7 @@ --- -title: ZITADEL with Python +title: Secure Flask (Python) API Application with ZITADEL description: "Secure Python Flask APIs with ZITADEL token validation and role-based access control." -sidebar_label: Python +sidebar_label: Flask API --- This example shows you how to secure a Python3 Flask API with both authentication and authorization using ZITADEL. diff --git a/apps/docs/content/guides/solution-scenarios/introduction/index.mdx b/apps/docs/content/guides/solution-scenarios/introduction/index.mdx index 5fb126a6d..e08668bcf 100644 --- a/apps/docs/content/guides/solution-scenarios/introduction/index.mdx +++ b/apps/docs/content/guides/solution-scenarios/introduction/index.mdx @@ -16,4 +16,5 @@ import { FileText, Folder, Link as LinkIcon } from 'lucide-react'; } /> } /> } /> + } /> diff --git a/apps/docs/content/sdk-examples/_oidc-libraries-table.mdx b/apps/docs/content/sdk-examples/_oidc-libraries-table.mdx new file mode 100644 index 000000000..ed1a6844d --- /dev/null +++ b/apps/docs/content/sdk-examples/_oidc-libraries-table.mdx @@ -0,0 +1,25 @@ +| Framework | Recommended OIDC Library | Example Documentation Link | +|---|---|---| +| Angular | [@edgeflare/ngx-oidc](https://www.npmjs.com/package/@edgeflare/ngx-oidc) | [Integration Example](/sdk-examples/angular) | +| Astro | [@auth/core](https://www.npmjs.com/package/@auth/core) | [Integration Example](/sdk-examples/astro) | +| Django | [Authlib](https://authlib.org) | [Integration Example](/sdk-examples/django) | +| Express.js | [@auth/express](https://www.npmjs.com/package/@auth/express) | [Integration Example](/sdk-examples/expressjs) | +| FastAPI | [Authlib](https://authlib.org) | [Integration Example](/sdk-examples/fastapi) | +| Fastify | [@auth/core](https://www.npmjs.com/package/@auth/core) | [Integration Example](/sdk-examples/fastify) | +| Flask | [Authlib](https://authlib.org) | [Integration Example](/sdk-examples/flask) | +| Hono | [Auth.js](https://authjs.dev) | [Integration Example](/sdk-examples/hono) | +| Laravel | [Laravel Socialite](https://laravel.com/docs/socialite) | [Integration Example](/sdk-examples/laravel) | +| Nest.js | [@auth/core](https://www.npmjs.com/package/@auth/core) | [Integration Example](/sdk-examples/nestjs) | +| Next.js | [next-auth](https://next-auth.js.org) | [Integration Example](/sdk-examples/nextjs) | +| Nuxt.js | [next-auth](https://next-auth.js.org) | [Integration Example](/sdk-examples/nuxtjs) | +| Qwik | [@auth/core](https://www.npmjs.com/package/@auth/core) | [Integration Example](/sdk-examples/qwik) | +| SolidStart | [@auth/solid-start](https://www.npmjs.com/package/@auth/solid-start) |[Integration Example](/sdk-examples/solidstart) | +| Svelte | [@auth/sveltekit](https://www.npmjs.com/package/@auth/sveltekit) | [Integration Example](/sdk-examples/svelte) | +| Symfony | [Symfony Security](https://symfony.com/doc/current/security.html) | [Integration Example](/sdk-examples/symfony) | + + +You might want to check out the following links to find another good library: + +- [awesome-auth](https://github.com/casbin/awesome-auth) +- [OpenID General References](https://openid.net/developers/libraries/) +- [OpenID certified developer tools](https://openid.net/certified-open-id-developer-tools/) \ No newline at end of file diff --git a/apps/docs/content/sdk-examples/flutter.mdx b/apps/docs/content/sdk-examples/flutter.mdx deleted file mode 100644 index bf0625d7d..000000000 --- a/apps/docs/content/sdk-examples/flutter.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Flutter -description: "Integrate ZITADEL authentication into Flutter applications using the Flutter SDK and OIDC PKCE." -sidebar_label: Flutter ---- - - - - - - -
- flutter logo - - Flutter is a cross-platform mobile app development framework that allows developers to build native iOS and Android apps using a single codebase. - Integrate authentication to your Flutter App easily by using the zitadel-flutter Example. -
- -### Resources -- [Flutter Example Application Repository](https://github.com/zitadel/zitadel_flutter) -- [Step-By-Step Guide](/examples/login/flutter) to create your Flutter App with ZITADEL Login -- [Dart Client Library for ZITADEL](https://github.com/smartive/zitadel-dart) - -### Flutter SDK - -ZITADEL doesn't provide a specific Flutter SDK for authentication in your Web/Mobile App. -You can use any OIDC Library such as [package:oidc](https://pub.dev/packages/oidc). -For Mobile Apps we recommend [Flutter AppAuth](https://pub.dev/packages/flutter_appauth). - -Check out our [Example Application](/sdk-examples/flutter#example-application). - -Additionally, you can use [smartive/zitadel-dart](https://github.com/smartive/zitadel-dart) for user and resource management. -- Manage Resources through ZITADEL APIs - - Authenticate Service Account - - Generated gRPC Clients for integrating ZITADEL API - - User, Organization, Project, etc. Management - - -This library is built by our community. - - -### Example Application - -The [zitadel-flutter](https://github.com/zitadel/zitadel_flutter) repository includes an Example Application ready to start and show how a Flutter application looks like with integrated ZITADEL Login. - -What does the Example include: -- Home Page with Login Button -- Authenticating user with OIDC PKCE Flow -- Private Page: Only accessible after login - -### Step-By-Step Guide - -The [Step-By-Step Guide](/examples/login/flutter) 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 Mobile App with integrated ZITADEL Login -2. Example page accessible by authenticated user -3. Correct setup for your application in ZITADEL - -
- Unauthenticated - Flutter Authenticated -
- -
- Unauthenticated - Flutter Authenticated -
diff --git a/apps/docs/content/sdk-examples/hono.mdx b/apps/docs/content/sdk-examples/hono.mdx index 3ffb15581..ef2fb305c 100644 --- a/apps/docs/content/sdk-examples/hono.mdx +++ b/apps/docs/content/sdk-examples/hono.mdx @@ -3,7 +3,7 @@ title: Hono description: "Implement secure authentication in Hono applications with ZITADEL and Auth.js using the OAuth 2.0 PKCE flow." sidebar_label: Hono framework_url: https://hono.dev -auth_library: "@auth/core" +auth_library: "Auth.js" auth_library_url: https://authjs.dev example_repo: https://github.com/zitadel/example-auth-hono auth_flow: pkce diff --git a/apps/docs/content/sdk-examples/introduction.mdx b/apps/docs/content/sdk-examples/introduction.mdx index f38ac458a..244923d3e 100644 --- a/apps/docs/content/sdk-examples/introduction.mdx +++ b/apps/docs/content/sdk-examples/introduction.mdx @@ -5,6 +5,7 @@ sidebar_label: Introduction --- import { Frameworks } from "@/components/frameworks"; +import OIDCLibrariesTable from './_oidc-libraries-table.mdx' 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. @@ -19,24 +20,19 @@ If you encounter issues with a community-contributed example, please contact the We provide this list for informational purposes and to foster community engagement, but we do not assume responsibility for these external implementations. -## Clients +## Management Clients + +Automate and manage your ZITADEL instance programmatically. These clients are built for Machine-to-Machine (M2M) communication, allowing your backend services to perform administrative tasks without human intervention. framework.client === true } /> -## SDKs +## ZITADEL SDKs + +ZITADEL SDKs are purpose-built to provide a deep, idiomatic integration into your specific framework. +While standard OIDC libraries handle basic authentication, Zitadel SDKs act as a powerful abstraction layer, streamlining complex identity tasks and providing direct access to the ZITADEL core platform. framework.sdk === true } /> -## Resources - - framework.client === false || framework.client == null} /> - -To further streamline your setup, simply visit the management console in Zitadel where you can select one of the languages or frameworks. This will allow you to instantly set up the settings for that specific sample in Zitadel, ensuring you have everything you need to get started right away. - -![](../../public/img/sdk-examples/console.png) - -To begin configuring login for any of these samples, start [here](/guides/manage/console/console-overview). - ## OIDC Libraries OIDC is a standard for authentication and most languages and frameworks do provide a OIDC library which can be easily integrated to your application. @@ -45,22 +41,18 @@ language or framework instead of building your own. Certified libraries have undergone rigorous testing and validation to ensure high security and reliability. There are many recommended libraries available, this saves time and ensures that users' data is well-protected. -You might want to check out the following links to find a good library: -- [awesome-auth](https://github.com/casbin/awesome-auth) -- [OpenID General References](https://openid.net/developers/libraries/) -- [OpenID certified developer tools](https://openid.net/certified-open-id-developer-tools/) + -## Other example applications +## Example Applications - [B2B customer portal](https://github.com/zitadel/zitadel-nextjs-b2b): Showcase the use of personal access tokens in a B2B environment. Uses Next.js 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 - [Introspection](https://github.com/zitadel/examples-api-access-and-token-introspection): Python examples for securing an API and invoking it as a service account - [Fine-grained authorization](https://github.com/zitadel/example-fine-grained-authorization): Leverage actions, custom metadata, and claims for attribute-based access control Search for the "example" tag in our repository to [explore all examples](https://github.com/search?q=topic%3Aexamples+org%3Azitadel&type=repositories). -## Missing SDK +## Missing Management Client Is your language/framework missing? Fear not, you can generate your gRPC API Client with ease. diff --git a/apps/docs/content/sdk-examples/oidc-libraries.mdx b/apps/docs/content/sdk-examples/oidc-libraries.mdx new file mode 100644 index 000000000..f0359c9f7 --- /dev/null +++ b/apps/docs/content/sdk-examples/oidc-libraries.mdx @@ -0,0 +1,10 @@ +--- +title: Integrating ZITADEL with Standard OIDC & OAuth2 Libraries +description: Integrate ZITADEL with any standards-compliant OpenID Connect (OIDC) or OAuth2 library. +--- + +import OIDCLibrariesTable from './_oidc-libraries-table.mdx' + +Since ZITADEL is a certified provider, you can use industry-standard tools to handle authentication and API protection in any language or framework without vendor lock-in. + + \ No newline at end of file diff --git a/apps/docs/content/sdk-examples/solidstart.mdx b/apps/docs/content/sdk-examples/solidstart.mdx index 2be2597a7..6bb083e14 100644 --- a/apps/docs/content/sdk-examples/solidstart.mdx +++ b/apps/docs/content/sdk-examples/solidstart.mdx @@ -3,7 +3,7 @@ title: SolidStart description: "Integrate ZITADEL authentication into SolidStart applications using the OAuth 2.0 PKCE flow." sidebar_label: SolidStart framework_url: https://start.solidjs.com -auth_library: "@auth/core" +auth_library: "@auth/solid-start" auth_library_url: https://www.npmjs.com/package/@auth/core example_repo: https://github.com/zitadel/example-auth-solidstart auth_flow: pkce diff --git a/apps/docs/content/sdk-examples/sveltekit.mdx b/apps/docs/content/sdk-examples/sveltekit.mdx index fa3b4f982..a7c8cee11 100644 --- a/apps/docs/content/sdk-examples/sveltekit.mdx +++ b/apps/docs/content/sdk-examples/sveltekit.mdx @@ -3,8 +3,8 @@ title: SvelteKit description: "Integrate ZITADEL authentication into SvelteKit applications using the OAuth 2.0 PKCE flow." sidebar_label: SvelteKit framework_url: https://kit.svelte.dev -auth_library: "@auth/core" -auth_library_url: https://www.npmjs.com/package/@auth/core +auth_library: "@auth/sveltekit" +auth_library_url: https://www.npmjs.com/package/@auth/sveltekit example_repo: https://github.com/zitadel/example-auth-sveltekit auth_flow: pkce status: stable diff --git a/apps/docs/css/custom.css b/apps/docs/css/custom.css index fc98d661a..f9f1c1638 100644 --- a/apps/docs/css/custom.css +++ b/apps/docs/css/custom.css @@ -284,4 +284,8 @@ p strong { table#zitadel-versions td { vertical-align: top; +} + +h3 { + font-size: 1.5rem; } \ No newline at end of file diff --git a/apps/docs/frameworks.json b/apps/docs/frameworks.json index 60699b2f5..46738effb 100644 --- a/apps/docs/frameworks.json +++ b/apps/docs/frameworks.json @@ -60,8 +60,7 @@ "id": "go", "title": "Go", "imgSrcDark": "/docs/img/tech/golang.svg", - "docsLink": "/docs/guides/start/quickstart?framework=go", - "sdk": true + "docsLink": "/docs/guides/start/quickstart?framework=go" }, { "id": "hono", @@ -137,5 +136,95 @@ "description": "This preset sets up an OIDC configuration with Authentication Code Flow, secured by PKCE", "imgSrcDark": "/docs/img/tech/vue.svg", "docsLink": "/docs/guides/start/quickstart?framework=vue" + }, + { + "id": "java", + "title": "Java", + "description": "This preset sets up an OIDC configuration with Authentication Code Flow, secured by PKCE", + "imgSrcDark": "/docs/img/tech/java.svg", + "docsLink": "/docs/guides/start/quickstart?framework=vue" + }, + { + "id": "client-dart", + "title": "Dart / Flutter", + "imgSrcDark": "/docs/img/tech/dart.svg", + "docsLink": "https://github.com/smartive/zitadel-dart", + "client": true, + "external": true + }, + { + "title": "Elixir", + "imgSrcDark": "/docs/img/tech/elixir.svg", + "docsLink": "https://github.com/maennchen/zitadel_api", + "client": true, + "external": true + }, + { + "title": "Go", + "imgSrcDark": "/docs/img/tech/golang.svg", + "docsLink": "/docs/sdk-examples/go", + "client": true, + "sdk": true + }, + { + "title": "Java", + "imgSrcDark": "/docs/img/tech/java.svg", + "docsLink": "/docs/sdk-examples/client-libraries/java", + "client": true + }, + { + "title": ".Net", + "imgSrcDark": "/docs/img/tech/dotnet.svg", + "docsLink": "https://github.com/smartive/zitadel-net", + "external": true, + "client": true, + "sdk": true + }, + { + "title": "Node.js", + "imgSrcDark": "/docs/img/tech/nodejs.svg", + "docsLink": "/docs/sdk-examples/client-libraries/node", + "client": true + }, + { + "title": "PHP", + "imgSrcDark": "/docs/img/tech/php.svg", + "docsLink": "/docs/sdk-examples/client-libraries/php", + "client": true + }, + { + "title": "Python", + "imgSrcDark": "/docs/img/tech/python.svg", + "docsLink": "/docs/sdk-examples/client-libraries/python", + "client": true + }, + { + "title": "React", + "imgSrcDark": "/docs/img/tech/react.svg", + "docsLink": "https://github.com/zitadel/zitadel-react", + "sdk": true, + "external": true + }, + { + "title": "Ruby", + "imgSrcDark": "/docs/img/tech/ruby.svg", + "docsLink": "/docs/sdk-examples/client-libraries/ruby", + "client": true + }, + { + "title": "Rust", + "imgSrcLight": "/docs/img/tech/rust.svg", + "imgSrcDark": "/docs/img/tech/rustlight.svg", + "docsLink": "https://github.com/smartive/zitadel-rust", + "client": true, + "sdk": true, + "external": true + }, + { + "title": "Vue", + "imgSrcDark": "/docs/img/tech/vue.svg", + "docsLink": "https://github.com/zitadel/zitadel-vue", + "sdk": true, + "external": true } ] diff --git a/apps/docs/lib/sidebar-data.ts b/apps/docs/lib/sidebar-data.ts index 73835a15b..66afae6d1 100644 --- a/apps/docs/lib/sidebar-data.ts +++ b/apps/docs/lib/sidebar-data.ts @@ -88,14 +88,14 @@ export const guidesSidebar: readonly SidebarItem[] = [ "Step-by-step instructions for integrating ZITADEL authentication into your frontend single-page applications. Includes guides for React, Angular, Vue, and vanilla JS.", }, items: [ + "sdk-examples/angular", + "sdk-examples/react", { type: "link", label: "Vanilla-JS", href: "https://github.com/zitadel/zitadel-vanilla-js", }, - "examples/login/react", - "examples/login/angular", - "examples/login/vue", + "sdk-examples/vue", ], }, { @@ -123,8 +123,20 @@ export const guidesSidebar: readonly SidebarItem[] = [ "Integrate ZITADEL with your full-stack and server-side rendered (SSR) applications. Follow our guides for Next.js, B2B scenarios, and other modern web frameworks.", }, items: [ - "examples/login/nextjs", + "sdk-examples/astro", + "sdk-examples/dotnet", + "sdk-examples/expressjs", + "sdk-examples/flask", + "sdk-examples/fastapi", + "sdk-examples/fastify", + "sdk-examples/laravel", + "sdk-examples/nestjs", + "sdk-examples/nextjs", "examples/login/nextjs-b2b", + "sdk-examples/nuxtjs", + "sdk-examples/qwik", + "sdk-examples/solidstart", + "sdk-examples/sveltekit", ], }, { @@ -138,10 +150,10 @@ export const guidesSidebar: readonly SidebarItem[] = [ "Step-by-step guides for integrating ZITADEL into traditional server-side web applications. Learn how to secure Java Spring, PHP Symfony, Django, and Go apps.", }, items: [ - "examples/login/symfony", - "examples/login/java-spring", - "examples/login/python-django", - "examples/login/go" + "sdk-examples/django", + "examples/login/go", + "sdk-examples/symfony", + "sdk-examples/spring", ], }, { @@ -157,10 +169,9 @@ export const guidesSidebar: readonly SidebarItem[] = [ items: [ "examples/secure-api/go", "examples/secure-api/java-spring", - "examples/secure-api/python-django", - "examples/secure-api/python-flask", "examples/secure-api/nodejs-nestjs", "examples/secure-api/pylon", + "examples/secure-api/python-django", ], }, ], @@ -282,49 +293,44 @@ export const guidesSidebar: readonly SidebarItem[] = [ }, { type: "category", - label: "SDKs", + label: "SDKs & Integrations", items: [ "sdk-examples/introduction", { type: "category", - label: "Frontend (SPA)", - items: [ - "sdk-examples/react", - "sdk-examples/angular", - "sdk-examples/vue", - ], - }, - { - type: "category", - label: "Mobile & Native", + label: "Frontend & Mobile (OIDC/PKCE)", items: [ { type: "link", - label: "Dart / Flutter", - href: "https://github.com/smartive/zitadel-dart", + label: "Angular", + href: "/docs/sdk-examples/oidc-libraries" }, + "sdk-examples/go", { type: "link", label: ".NET (MAUI/Xamarin)", href: "https://github.com/smartive/zitadel-net", }, - ], - }, - { - type: "category", - label: "Full-Stack / SSR", - items: [ - "sdk-examples/nextjs", - "sdk-examples/nuxtjs", - "sdk-examples/sveltekit", - "sdk-examples/qwik", - "sdk-examples/solidstart", - "sdk-examples/astro", { type: "link", label: "NextAuth", href: "https://next-auth.js.org/providers/zitadel", }, + { + type: "link", + label: "React", + href: "https://github.com/zitadel/zitadel-react", + }, + { + type: "link", + label: "Vue", + href: "https://github.com/zitadel/zitadel-vue", + }, + { + type: "link", + label: "Other", + href: "/docs/sdk-examples/oidc-libraries" + }, ], }, { @@ -332,85 +338,52 @@ export const guidesSidebar: readonly SidebarItem[] = [ label: "Backend & API", items: [ { - type: "category", - label: "Node.js", - items: [ - "sdk-examples/client-libraries/node", - "sdk-examples/expressjs", - "sdk-examples/fastify", - "sdk-examples/hono", - "sdk-examples/nestjs", - { - type: "link", - label: "Passport.js", - href: "https://github.com/buehler/node-passport-zitadel", - }, - { - type: "link", - label: "Node.js (Community)", - href: "https://www.npmjs.com/package/@zitadel/node", - }, - ], + type: "link", + label: ".NET (MAUI/Xamarin)", + href: "https://github.com/smartive/zitadel-net", + }, + "sdk-examples/go", + { + type: "link", + label: "Passport.js", + href: "https://github.com/buehler/node-passport-zitadel", + }, + ], + }, + { + type: "category", + label: "Management API Clients", + items: [ + { + type: "link", + label: "Dart / Flutter", + href: "https://github.com/smartive/zitadel-dart", }, { - type: "category", - label: "Python", - items: [ - "sdk-examples/client-libraries/python", - "sdk-examples/flask", - "sdk-examples/django", - "sdk-examples/fastapi", - ], + type: "link", + label: "Elixir", + href: "https://github.com/maennchen/zitadel_api", }, + "sdk-examples/go", + "sdk-examples/client-libraries/java", { - type: "category", - label: "Go", - items: ["sdk-examples/go"], + type: "link", + label: ".NET (MAUI/Xamarin)", + href: "https://github.com/smartive/zitadel-net", }, + "sdk-examples/client-libraries/node", { - type: "category", - label: "Java", - items: [ - "sdk-examples/java", - "sdk-examples/spring", - "sdk-examples/client-libraries/java", - ], + type: "link", + label: "Node.js (Community)", + href: "https://github.com/smartive/zitadel-node", }, + "sdk-examples/client-libraries/php", + "sdk-examples/client-libraries/python", + "sdk-examples/client-libraries/ruby", { - type: "category", - label: "PHP", - items: [ - "sdk-examples/symfony", - "sdk-examples/laravel", - "sdk-examples/client-libraries/php", - ], - }, - { - type: "category", - label: ".NET", - items: ["sdk-examples/dotnet"], - }, - { - type: "category", - label: "Other Languages", - items: [ - "sdk-examples/client-libraries/ruby", - { - type: "link", - label: "Elixir", - href: "https://github.com/maennchen/zitadel_api", - }, - { - type: "link", - label: "Rust", - href: "https://github.com/smartive/zitadel-rust", - }, - { - type: "link", - label: "Pylon", - href: "https://github.com/getcronit/pylon", - }, - ], + type: "link", + label: "Rust", + href: "https://github.com/smartive/zitadel-rust", }, ], }, diff --git a/apps/docs/redirects.json b/apps/docs/redirects.json index 59482ed1f..f00290125 100644 --- a/apps/docs/redirects.json +++ b/apps/docs/redirects.json @@ -1,4 +1,49 @@ [ + { + "source": "/examples/login/react", + "destination": "/sdk-examples/react", + "permanent": true + }, + { + "source": "/examples/login/angular", + "destination": "/sdk-examples/angular", + "permanent": true + }, + { + "source": "/examples/login/vue", + "destination": "/sdk-examples/vue", + "permanent": true + }, + { + "source": "/examples/login/nextjs", + "destination": "/sdk-examples/nextjs", + "permanent": true + }, + { + "source": "/examples/login/symfony", + "destination": "/sdk-examples/symfony", + "permanent": true + }, + { + "source": "/examples/login/java-spring", + "destination": "/sdk-examples/spring", + "permanent": true + }, + { + "source": "/examples/login/python-django", + "destination": "/sdk-examples/django", + "permanent": true + }, + { + "source": "/examples/secure-api/python-flask", + "destination": "/sdk-examples/flask", + "permanent": true + }, + { + "source": "/examples/secure-api/python-flask", + "destination": "/sdk-examples/flask", + "permanent": true + }, { "source": "/apis/resources/action_service_v2", "destination": "/reference/api/action",