andwati/zitadel
1
0
Fork 0
mirror of https://github.com/andwati/zitadel.git synced 2026-10-22 15:32:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Quickstart add frameworks (#11485)

Browse Source 
# Which Problems Are Solved

The quickstart only shows the steps to take to get a working zitadel
login into your app with react.
For users with another framework or languages we didn't show how to get
to success fast.

# How the Problems Are Solved

- Adding different frameworks to the qucisktart example
- Make sure the app configurations in the onboarding flow from the
console match the configurations from the examples
- Docs link in console onboarding flow point towards quickstart
- Quickstart accepts framework selector, to pre select a framework from
another page

---------

Co-authored-by: Federico Coppede <[email protected]>
Co-authored-by: Copilot <[email protected]>
This commit is contained in:
Fabienne Bühler
2026-02-04 13:09:25 +01:00
committed by GitHub
co-authored by Federico Coppede Copilot
parent be6590c33c
commit 6f07b8deee
50 changed files with 447 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/content/examples/login/go.mdx
+1 -1
View File
@@ -129,7 +129,7 @@ You will need to provide some values for the program to run:
- `port`: The port on which the API will be accessible, default it 8089
```bash
go run main.go --domain <custom domain> --key <key> -- clientID <clientID> --redirectURI <redirectURI>
go run main.go --domain <custom domain> --key <key> --clientID <clientID> --redirectURI <redirectURI>
```
This could look like:
apps/docs/content/guides/start/_app_config.mdx
+18
View File
@@ -0,0 +1,18 @@
export default function AppConfig({ redirectUrl, postLogoutRedirectUrl }) {
return (
<div>
<ul>
<li>
<b>Auth Strategy</b>: <a href="/docs/apis/openidoauth/grant-types#authorization-code">Authorization Code Flow (PKCE)</a>. This modern standard ensures tokens are exchanged securely without needing a client secret in your frontend.
</li>
<li><b>Redirect URIs</b>: These define where users return after authentication:
<ul>
<li>Redirect URI: {redirectUrl} (Landing page after login)</li>
<li>Post Logout URI: {postLogoutRedirectUrl} (Landing page after logout)</li>
</ul>
</li>
</ul>
</div>
);
}
apps/docs/content/guides/start/_app_values.mdx
+41
View File
@@ -0,0 +1,41 @@
import ProjectClientIdImg from '@pub/img/guides/quickstart/project_client_id.png'
import ProjectClientIdSecretImg from '@pub/img/guides/quickstart/project_client_id_secret.png'
import ProjectUrlsImg from '@pub/img/guides/quickstart/project_urls.png'
import ProjectProjectIdImg from '@pub/img/guides/quickstart/project_project_id.png'
export default function AppValue({ valueCount, clientSecret, projectID }) {
return (
<div>
<p>
To connect your application to ZITADEL, you need {valueCount} primary configuration values.
These are typically stored as environment variables in your project.
</p>
<ol>
{!!clientSecret == false && (<li>
<b>Client ID</b> Navigate to Configurations in the left sidebar. This is the unique public identifier for your React application.
<img
src={ProjectClientIdImg.src} alt="Get Client ID"/>
</li>)}
{!!clientSecret && (<li>
<b>Client ID & Client Secret</b> Copy the client id and secret from the modal. The client id is the unique public identifier for your application.
Note: If you missed copy the secret, you can generate a new one in the Actions dropdown.
<img
src={ProjectClientIdSecretImg.src} alt="Get Client ID and Secret"/>
</li>)}
<li>
<b>Issuer URL</b> Click on URLs in the left sidebar to find your <b>Discovery Endpoint</b>.
- The Value: Copy the issuer URL (e.g., https://your-instance.zitadel.cloud).
- Why it matters: ZITADEL supports OIDC Discovery. By providing just the Issuer URL to your SDK, the library automatically finds the login, logout, and token endpoints for you.
<img src={ProjectUrlsImg.src} alt="Get URLs"/>
</li>
{!!projectID && (<li >
<b>Project ID</b> Your currently in the application configuration which is a sub resource of the Project. Navigate to the Project with the back arrow and copy the Project ID.
<img src={ProjectProjectIdImg.src} alt="Get Project ID"/>
</li>)}
</ol>
</div>
);
}
apps/docs/content/guides/start/quickstart.mdx
+322 -65
View File
@@ -1,18 +1,16 @@
---
title: The ZITADEL Quick Start Guide
description: Learn how to integrate OIDC PKCE authentication in React using ZITADEL in under 5 minutes.
description: Learn how to integrate OIDC PKCE authentication in your application using ZITADEL in under 5 minutes.
sidebar_label: Quick Start Guide
keywords: [ZITADEL, React, OIDC, PKCE, Authentication, Identity Management]
framework: React
stack: Node.js
keywords: [ZITADEL, OIDC, PKCE, Authentication, Identity Management]
---
import { ResponsivePlayer } from "@/components/player";
import { Tab } from 'fumadocs-ui/components/tabs';
import { FrameworkSelector } from '@/components/framework_selector';
import AppConfig from './_app_config.mdx';
import AppValues from './_app_values.mdx';
This sample app implements the [OIDC PKCE](/guides/integrate/login/oidc/login-users) flow for secure authentication.
- Login: Exchanges a code challenge for an access token via ZITADEL.
- Authorize: Uses the token to retrieve profile data from the userinfo endpoint.
- Logout: Clears the local session and revokes the token.
In this guide, you’ll set up a Zitadel account and authenticate your first example application.
## Get Started with ZITADEL Cloud
@@ -34,8 +32,7 @@ This is the administrative hub for managing your billing, teams, and instances.
Complete the brief onboarding questions.
This data helps us prioritize the development of new features, SDKs, and integrations that matter most to our community.
![](../../../public/img/guides/quickstart/onboarding_questions.png)
![Onboarding Questions](../../../public/img/guides/quickstart/onboarding_questions.png)
### 3. Create your ZITADEL instance
@@ -65,33 +62,88 @@ Log in using the Admin credentials you just created.
#### Step 1: Define your Project
- **Name**: Enter a name (e.g., Project1).
- **Framework**: Select React (or choose Other if your stack isn't listed).
- **Framework**: Select your preferred framework
- **Continue**: Click the Continue button.
![](../../../public/img/guides/quickstart/create_project_react.png)
![Project Name and Framework/Language](../../../public/img/guides/quickstart/create_project_react.png)
#### Step 2: Review Default Configuration
ZITADEL automatically configures the best security settings for your selected framework.
- **Auth Strategy**: [Authorization Code Flow](/apis/openidoauth/grant-types#authorization-code) with [PKCE](/apis/openidoauth/grant-types#authorization-code). This modern standard ensures tokens are exchanged securely without needing a client secret in your frontend.
- **Redirect URIs**: These define where users return after authentication:
- Redirect URI: http://localhost:3000/callback (Landing page after login)
- Post Logout URI: http://localhost:3000/ (Landing page after logout)
![](../../../public/img/guides/quickstart/project_config_overview_react.png)
<FrameworkSelector>
<Tab value="Angular">
<AppConfig
redirectUrl="http://localhost:3000/auth/callback"
postLogoutRedirectUrl="http://localhost:3000/signedout">
</AppConfig>
</Tab>
<Tab value="Flutter">
<AppConfig
redirectUrl="http://localhost:4444/auth.html, com.example.zitadelflutter"
postLogoutRedirectUrl="http://localhost:4444, com.example.zitadelflutter">
</AppConfig>
</Tab>
<Tab value="Go">
<AppConfig
redirectUrl="http://localhost:8089/auth/callback"
postLogoutRedirectUrl="http://localhost:8089">
</AppConfig>
</Tab>
<Tab value="Next.js">
<AppConfig
redirectUrl="http://localhost:3000/api/auth/callback/zitadel"
postLogoutRedirectUrl="http://localhost:3000/api/auth/logout/callback">
</AppConfig>
</Tab>
<Tab value="React">
<AppConfig
redirectUrl="http://localhost:3000/callback"
postLogoutRedirectUrl="http://localhost:3000/">
</AppConfig>
</Tab>
<Tab value="Symfony">
<AppConfig
redirectUrl="http://localhost:8000/login_check"
postLogoutRedirectUrl="http://localhost:8000/logout">
</AppConfig>
</Tab>
<Tab value="Vue.js">
<AppConfig
redirectUrl="http://localhost:3000/auth/callback"
postLogoutRedirectUrl="http://localhost:3000/">
</AppConfig>
</Tab>
</FrameworkSelector>
![Project Configuration Overview](../../../public/img/guides/quickstart/project_config_overview_react.png)
### 5. Collect your Integration Keys
To connect your React application to ZITADEL, you need two primary configuration values.
These are typically stored as environment variables in your project.
<FrameworkSelector>
<Tab value="Angular">
<AppValues valueCount="two" clientSecret={false} projectID={false}></AppValues>
</Tab>
<Tab value="Flutter">
<AppValues valueCount="two" clientSecret={false} projectID={false}></AppValues>
</Tab>
<Tab value="Go">
<AppValues valueCount="two" clientSecret={false} projectID={false}></AppValues>
</Tab>
<Tab value="Next.js">
<AppValues valueCount="three" clientSecret={true} projectID={false}></AppValues>
</Tab>
<Tab value="React">
<AppValues valueCount="two" clientSecret={false} projectID={false}></AppValues>
</Tab>
<Tab value="Symfony">
<AppValues valueCount="three" clientSecret={true} projectID={false}></AppValues>
</Tab>
<Tab value="Vue.js">
<AppValues valueCount="two" clientSecret={false} projectID={false}></AppValues>
</Tab>
</FrameworkSelector>
1. **Client ID** Navigate to Configurations in the left sidebar. This is the unique public identifier for your React application.
![Get Client ID](../../../public/img/guides/quickstart/project_client_id.png)
2. **Issuer URL** Click on URLs in the left sidebar to find your **Discovery Endpoint**.
- The Value: Copy the issuer URL (e.g., https://your-instance.zitadel.cloud).
- Why it matters: ZITADEL supports OIDC Discovery. By providing just the Issuer URL to your SDK, the library automatically finds the login, logout, and token endpoints for you.
![Get URLs](../../../public/img/guides/quickstart/project_urls.png)
## Integrate ZITADEL into your React App
## Integrate ZITADEL into your App
### How the Authentication Flow Works
@@ -104,61 +156,266 @@ ZITADEL handles the complexity of the OIDC handshake so your app stays secure wi
### 1. Prerequisites
- [Node.js](https://nodejs.org/): v16 or later.
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
- [Yarn](https://yarnpkg.com/): This project uses Yarn for dependency management.
<FrameworkSelector>
<Tab value="Angular">
- [Node.js](https://nodejs.org/)
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
</Tab>
<Tab value="Flutter">
- [Flutter](https://docs.flutter.dev/install)
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
</Tab>
<Tab value="Go">
- [Go](https://go.dev/)
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
</Tab>
<Tab value="Next.js">
- [Node.js](https://nodejs.org/)
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
</Tab>
<Tab value="React">
- [Node.js](https://nodejs.org/)
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
</Tab>
<Tab value="Symfony">
- [PHP](https://www.php.net/)
- [Composer](https://getcomposer.org/)
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
</Tab>
<Tab value="Vue.js">
- [Node.js](https://nodejs.org/)
- Code Editor: [VS Code](https://code.visualstudio.com/) or similar
</Tab>
</FrameworkSelector>
### 2. Get the Example Project
Clone the repository and move into the project directory:
```bash
git clone https://github.com/zitadel/zitadel-react.git
cd zitadel-react
```
<FrameworkSelector>
<Tab value="Angular">
```bash
git clone https://github.com/zitadel/example-auth-angular.git
cd example-auth-angular
```
</Tab>
<Tab value="Flutter">
```bash
git clone https://github.com/zitadel/zitadel_flutter.git
cd zitadel_flutter
```
</Tab>
<Tab value="Go">
```bash
git clone https://github.com/zitadel/zitadel-go.git
cd zitadel_go
```
</Tab>
<Tab value="Next.js">
```bash
git clone [email protected]:zitadel/example-auth-nextjs.git
cd example-auth-nextjs
```
</Tab>
<Tab value="React">
```bash
git clone https://github.com/zitadel/example-auth-react.git
cd example-auth-react
```
</Tab>
<Tab value="Symfony">
```bash
git clone https://github.com/zitadel/example-auth-symfony.git
cd example-auth-symfony
```
</Tab>
<Tab value="Vue.js">
```bash
git clone [email protected]:zitadel/example-auth-vuejs.git
cd example-auth-vuejs
```
</Tab>
</FrameworkSelector>
### 3. Build and Install
### 3. Configure your Credentials
Since this repo contains the SDK source, you need to build the library before running the example:
```bash
# Build the SDK library
cd lib && yarn install && yarn build
<FrameworkSelector>
<Tab value="Angular">
# Install example app dependencies
cd .. && yarn install
```
1. Copy+paste the .env.example to .env.local
2. Update the ZITADEL_CLIENT_ID and ZITADEL_DOMAIN with the client id and issuer you collected in Step 5.
### 4. Configure your Credentials
```bash
PORT=3000
NG_APP_ZITADEL_DOMAIN="https://your-zitadel-domain"
NG_APP_ZITADEL_CLIENT_ID="your-client-id"
NG_APP_ZITADEL_CALLBACK_URL="http://localhost:3000/auth/callback"
NG_APP_ZITADEL_POST_LOGOUT_URL="http://localhost:3000/auth/logout/callback"
NG_APP_ZITADEL_POST_LOGIN_URL="/profile"
```
</Tab>
<Tab value="Flutter">
No action required for this step.
The issuer and client Id will be passed directly when running the app (next step)
</Tab>
<Tab value="Go">
No action required for this step.
The issuer and client Id will be passed directly when running the app (next step)
</Tab>
<Tab value="Next.js">
1. Copy+past the .env.example to .env.local
2. Update the ZITADEL_CLIENT_ID, ZITADEL_CLIENT_SECRET and ZITADEL_DOMAIN with the client id and issuer you collected in Step 5.
Open src/App.tsx and update the config object with the **Issuer** and **Client ID** you collected in Step 5.
```bash
NODE_ENV=development
PORT=3000
SESSION_SECRET="your-very-secret-and-strong-session-key"
SESSION_DURATION=3600
ZITADEL_DOMAIN="[https://your-instance.zitadel.cloud/](https://your-instance.zitadel.cloud/)"
ZITADEL_CLIENT_ID="zitadel-client-id"
ZITADEL_CLIENT_SECRET="zitadel-client-secret"
ZITADEL_CALLBACK_URL="http://localhost:3000/api/auth/callback/zitadel"
ZITADEL_POST_LOGIN_URL="/profile"
ZITADEL_POST_LOGOUT_URL="http://localhost:3000/api/auth/logout/callback"
NEXTAUTH_URL="http://localhost:3000"
```typescript
const config: ZitadelConfig = {
authority: "https://your-instance.zitadel.cloud", // Your Issuer URL
client_id: "YOUR_CLIENT_ID", // Your Client ID
redirect_uri: "http://localhost:3000/callback",
post_logout_redirect_uri: "http://localhost:3000",
response_type: 'code',
scope: 'openid profile email'
};
```
```
</Tab>
<Tab value="React">
1. Copy+paste the .env.example to .env
2. Update the ZITADEL_CLIENT_ID and ZITADEL_DOMAIN with the client id and issuer you collected in Step 5.
### 5. Run the Application
```bash
NODE_ENV=development
PORT=3000
VITE_ZITADEL_DOMAIN="https://your-zitadel-domain"
VITE_ZITADEL_CLIENT_ID="your-client-id"
VITE_ZITADEL_CALLBACK_URL="http://localhost:3000/auth/callback"
VITE_ZITADEL_POST_LOGIN_URL="/profile"
VITE_ZITADEL_POST_LOGOUT_URL="http://localhost:3000"
```
</Tab>
<Tab value="Symfony">
Start your development server:
```bash
yarn start
```
1. Copy+paste the .env.example to .env
2. Update the ZITADEL_CLIENT_ID and ZITADEL_DOMAIN with the client id and issuer you collected in Step 5.
Your app will be live at `http://localhost:3000`. Click Login to test the full PKCE flow!
```bash
PORT=3000
NG_APP_ZITADEL_DOMAIN="https://your-zitadel-domain"
NG_APP_ZITADEL_CLIENT_ID="your-client-id"
NG_APP_ZITADEL_CALLBACK_URL="http://localhost:3000/auth/callback"
NG_APP_ZITADEL_POST_LOGOUT_URL="http://localhost:3000/auth/logout/callback"
NG_APP_ZITADEL_POST_LOGIN_URL="/profile"
```
</Tab>
<Tab value="Vue.js">
1. Copy+paste the .env.example to .env
2. Update the ZITADEL_CLIENT_ID and ZITADEL_DOMAIN with the client id and issuer you collected in Step 5.
![React Example App](../../../public/img/guides/quickstart/react_example_app.png)
```bash
NODE_ENV=development
PORT=3000
VITE_ZITADEL_DOMAIN="https://your-zitadel-domain"
VITE_ZITADEL_CLIENT_ID="your-client-id"
VITE_ZITADEL_CALLBACK_URL="http://localhost:3000/auth/callback"
VITE_ZITADEL_POST_LOGIN_URL="/profile"
VITE_ZITADEL_POST_LOGOUT_URL="http://localhost:3000"
```
</Tab>
</FrameworkSelector>
### 4. Build and Run
<FrameworkSelector>
<Tab value="Angular">
```bash
npm install
npm run dev
```
Your app will be live at `http://localhost:4200`.
![Angular Example App](../../../public/img/guides/quickstart/angular_example_app.png)
</Tab>
<Tab value="Flutter">
Make sure to replace the [zitadel_issuer] and [zitadel_client_id] with your own value before running the command
```bash
flutter run -d chrome --web-port=4444 --dart-define zitadel_url=[zitadel_issuer] --dart-define zitadel_client_id=[zitadel_client_id]
```
Your app will be live at `http://localhost:4444`.
![Flutter Example App](../../../public/img/guides/quickstart/flutter_example_app.png)
</Tab>
<Tab value="Go">
Make sure to replace the [zitadel_domain] (use the domain from the issuer without the https://) and [zitadel_client_id] with your own value before running the command
```bash
go run example/app/app.go --domain [zitadel_domain] --key XKv2Lqd7YAq13NUZVUWZEWZeruqyzViM --clientID [zitadel_client_id] --redirectURI http://localhost:8089/auth/callback
```
Your app will be live at `http://localhost:8089`.
![Go Example App](../../../public/img/guides/quickstart/go_example_app.png)
</Tab>
<Tab value="Next.js">
```bash
npm install
npm run dev
```
Your app will be live at `http://localhost:3000`.
![Next.js Example App](../../../public/img/guides/quickstart/next_example_app.png)
</Tab>
<Tab value="React">
```bash
npm install
npm run dev
```
Your app will be live at `http://localhost:3000`.
![React Example App](../../../public/img/guides/quickstart/react_example_app.png)
</Tab>
<Tab value="Symfony">
```bash
composer install
composer run dev
```
Your app will be live at `http://localhost:3000`.
![Angular Example App](../../../public/img/guides/quickstart/symfony_example_app.png)
</Tab>
<Tab value="Vue.js">
```bash
npm install
npm run dev
```
Your app will be live at `http://localhost:3000`.
![Vue Example App](../../../public/img/guides/quickstart/vue_example_app.png)
</Tab>
</FrameworkSelector>
## Success! 🚀
You’ve successfully integrated ZITADEL into a React application.
You’ve successfully integrated ZITADEL into an application.
<Callout type="warn" title="Prevent Misconfiguration Lockouts">
Login policy misconfigurations that occur during the testing phase can easily lead to a [lockout](/legal/policies/account-lockout-policy). To ensure you don't lose access to your instance:
1. **Generate a backup PAT:** Create a [Service User Personal Access Token](/guides/integrate/service-users/personal-access-token) with the [`IAM_OWNER`](/guides/manage/console/managers) role to revert any login UI misconfigurations using the API.
2. **Add a second Instance Manager:** Always designate at least one [**second instance manager**](/guides/manage/console/managers).
</Callout>
### What’s next?
- [**Example Applications**](/examples/introduction): Find more comprehensive guides and examples for the different frameworks
- [**SSO**](/guides/integrate/services): Learn how to add SSO to your services
- [**Customize the UI**](/guides/manage/customize/branding): Make the login page your own with Branding.
- [**Explore the API**](/apis/introduction): Check out the ZITADEL API Reference for advanced integrations.
Need help? Join our [Discord community](https://zitadel.com/chat) or explore the full Documentation. Happy coding!
Need help? Join our [Discord community](https://zitadel.com/chat) or explore the full Documentation. Happy coding!