andwati/zitadel
1
0
Fork 0
mirror of https://github.com/andwati/zitadel.git synced 2026-10-28 18:12:16 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: introduce versioned docs and migrate to fuma (#11166)

Browse Source 
## Todos for release

- [x] Configure Env in docs project on vercel
- [x] Configure Root Path in the docs project on vercel
- [ ] Remove old CSP https://github.com/zitadel/website/pull/1592

## What we did

This pull request migrates the project documentation from the old
`docs/` directory to the new `apps/docs/` directory, introduces a new
documentation system built with Next.js and Fumadocs, and updates all
relevant references, configuration files, and documentation to reflect
this change. It also adds new configuration and ignore files for the new
documentation app, updates CI and linting to exclude the new docs from
certain checks, and revises the contributing guidelines accordingly.

**Documentation System Migration and New Docs App**

* Migrated all documentation from `docs/` to `apps/docs/`, and updated
all references in `README.md`, `CONTRIBUTING.md`, and other files to
point to the new location.
[[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640)
[[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607)
[[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687)
[[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3)
[[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30)
* Added a new Next.js/Fumadocs-based documentation app under
`apps/docs/`, including core app files, layouts, routing, search API,
and a comprehensive `README.md` with development and contribution
instructions.
[[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74)
[[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39)
[[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7)
[apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81),
[apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79),
[[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7)
[[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29)
[[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25)

**Configuration and Tooling Updates**

* Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and
`.github/dependabot.yml` to properly handle the new docs app: excluded
`apps/docs` from certain checks, added npm dependency updates for the
docs app, and excluded generated content.
[[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14)
[[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6)
[[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129)
[[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106)
* Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3
version for consistency.

**Licensing and Miscellaneous**

* Added `apps/docs/` to the list of licensed directories in
`LICENSING.md`.

These changes ensure the documentation is now maintained in a modern,
scalable system and all project tooling is updated to support the new
structure.

---------

Co-authored-by: Federico Coppede <[email protected]>
This commit is contained in:
Florian Forster
2026-01-29 08:38:36 -08:00
committed by GitHub
co-authored by Federico Coppede
parent 7b6395c348
commit d8ea041c56
2826 changed files with 78739 additions and 23571 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/content/sdk-examples/angular.mdx
+80
View File
@@ -0,0 +1,80 @@
---
title: Angular
sidebar_label: Angular
framework_url: https://angular.dev
auth_library: "@edgeflare/ngx-oidc"
auth_library_url: https://www.npmjs.com/package/@edgeflare/ngx-oidc
example_repo: https://github.com/zitadel/example-auth-angular
auth_flow: pkce
status: stable
---
## Overview
[Angular](https://angular.dev) is a TypeScript-based framework for building web applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your Angular application.
#### Auth library
This example uses **[@edgeflare/ngx-oidc](https://www.npmjs.com/package/@edgeflare/ngx-oidc)** (built on **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**) to implement the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manage [PKCE](https://oauth.net/2/pkce/) code challenge generation, perform secure token exchange, and provide session management helpers.
---
## What this example demonstrates
This Angular application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with [PKCE](https://oauth.net/2/pkce/). Users begin on a public landing page where they can initiate sign-in with Zitadel's authorization server. After successful authentication, the app handles the OAuth callback and redirects users to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).
The application integrates authentication logic into Angular routing: protected routes use router guards to automatically redirect unauthenticated users to the sign-in flow, and callback routes complete the PKCE exchange and restore session state. The example requests standard OIDC scopes (`openid`, `profile`, `email`), `offline_access` for refresh tokens, and Zitadel-specific scopes for metadata and role information.
The example includes secure sign-out functionality implementing **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's end-session endpoint, which terminates both the local application session and the Zitadel session, then redirects the user back to the application.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production deployments, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/login-users):
1. Clone the [repository](https://github.com/zitadel/example-auth-angular).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). Use these environment variable names exactly as shown:
```
NODE_ENV=development
PORT=3000
NG_APP_ZITADEL_DOMAIN=https://your-zitadel-domain
NG_APP_ZITADEL_CLIENT_ID=your-zitadel-application-client-id
NG_APP_ZITADEL_CLIENT_SECRET=
NG_APP_ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
NG_APP_ZITADEL_POST_LOGIN_URL=/profile
NG_APP_ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **NG_APP_ZITADEL_DOMAIN**)
- The **Client ID** you copied when creating the application
- The **redirect URIs** you configured in the PKCE setup (must match exactly)
- The **post-logout redirect URIs** you configured (must match exactly)
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Angular documentation](https://angular.dev)
* [@edgeflare/ngx-oidc package](https://www.npmjs.com/package/@edgeflare/ngx-oidc)
* [oidc-client-ts package](https://www.npmjs.com/package/oidc-client-ts)
* [Example repository](https://github.com/zitadel/example-auth-angular)
apps/docs/content/sdk-examples/astro.mdx
+83
View File
File diff suppressed because one or more lines are too long
apps/docs/content/sdk-examples/client-libraries/_category_.json
+4
View File
@@ -0,0 +1,4 @@
{
"label": "Client Libraries",
"position": 2
}
apps/docs/content/sdk-examples/client-libraries/java.mdx
+176
View File
@@ -0,0 +1,176 @@
---
title: Java Client
sidebar_label: 'Java Client'
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/java.svg" alt="java logo"/>
</td>
<td>
This guide covers the official Zitadel Management API Client for the JVM (Java 11+), which allows you to programmatically manage resources in your Zitadel instance.
</td>
</tr>
</table>
<Callout>
**This is a Management API Client, not an Authentication SDK.**
This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library like Spring Security.
</Callout>
The Zitadel Java Client provides an idiomatic way to access the full gamut of Zitadel's v2 Management APIs from your JVM-based backend applications.
> Please be aware that this client library is currently in an **incubating stage**.
While it is available for use, the API and its functionality may evolve, potentially introducing
breaking changes in future updates. We advise caution when considering it for production environments.
### Installation
You can add the client library to your project using Maven by adding the following dependency to your `pom.xml` :
```xml
<dependency>
<groupId>io.github.zitadel</groupId>
<artifactId>client</artifactId>
<version>4.0.0-beta-1</version>
</dependency>
```
### Using the SDK
Your SDK offers three ways to authenticate with Zitadel. Each method has its
own benefits—choose the one that fits your situation best.
#### 1. Private Key JWT Authentication
**What is it?**
You use a JSON Web Token (JWT) that you sign with a private key stored in a
JSON file. This process creates a secure token.
**When should you use it?**
- **Best for production:** It offers strong security.
- **Advanced control:** You can adjust token settings like expiration.
**How do you use it?**
1. Save your private key in a JSON file.
2. Build the authenticator using the helper method.
**Example:**
```java
class Demo {
public static void main(String[] args) throws ApiException {
Zitadel zitadel = Zitadel.withPrivateKey("https://example.us1.zitadel.cloud", "path/to/jwt-key.json");
UserServiceAddHumanUserResponse response = zitadel.users.userServiceAddHumanUser(
new UserServiceAddHumanUserRequest()
.username("john.doe")
.profile(new UserServiceSetHumanProfile()
.givenName("John")
.familyName("Doe"))
.email(new UserServiceSetHumanEmail()
.email("[email protected]"))
);
System.out.println("User created: " + response);
}
}
```
#### 2. Client Credentials Grant
**What is it?**
This method uses a client ID and client secret to get a secure access token,
which is then used to authenticate.
**When should you use it?**
- **Simple and straightforward:** Good for server-to-server communication.
- **Trusted environments:** Use it when both servers are owned or trusted.
**How do you use it?**
1. Provide your client ID and client secret.
2. Build the authenticator using the helper method.
**Example:**
```java
class Demo {
public static void main(String[] args) throws ApiException {
Zitadel zitadel = Zitadel.withClientCredentials("https://example.us1.zitadel.cloud", "id", "secret");
UserServiceAddHumanUserResponse response = zitadel.users.addHumanUser(
new UserServiceAddHumanUserRequest()
.username("john.doe")
.profile(new UserServiceSetHumanProfile()
.givenName("John")
.familyName("Doe"))
.email(new UserServiceSetHumanEmail()
.email("[email protected]"))
);
System.out.println("User created: " + response);
}
}
```
#### 3. Personal Access Tokens (PATs)
**What is it?**
A Personal Access Token (PAT) is a pre-generated token that you can use to
authenticate without exchanging credentials every time.
**When should you use it?**
- **Easy to use:** Great for development or testing scenarios.
- **Quick setup:** No need for dynamic token generation.
**How do you use it?**
1. Obtain a valid personal access token from your account.
2. Build the authenticator using the helper method.
**Example:**
```java
class Demo {
public static void main(String[] args) throws ApiException {
Zitadel zitadel = Zitadel.withAccessToken("https://example.us1.zitadel.cloud", "token");
UserServiceAddHumanUserResponse response = zitadel.users.addHumanUser(
new UserServiceAddHumanUserRequest()
.username("john.doe")
.profile(new UserServiceSetHumanProfile()
.givenName("John")
.familyName("Doe"))
.email(new UserServiceSetHumanEmail()
.email("[email protected]"))
);
System.out.println("User created: " + response);
}
}
```
---
Choose the authentication method that best suits your needs based on your
environment and security requirements. For more details, please refer to the
[Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).
### Versioning
The client library's versioning is aligned with the Zitadel core project. The major version of the
client corresponds to the major version of Zitadel it is designed to work with. For example,
v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration.
### Resources
- [GitHub Repository](https://github.com/zitadel/client-java): For source code, examples, and to report issues.
- [Maven Package](https://central.sonatype.com/artifact/io.github.zitadel/client): The official package artifact for Maven.
apps/docs/content/sdk-examples/client-libraries/node.mdx
+207
View File
@@ -0,0 +1,207 @@
---
title: Node.js Client
sidebar_label: 'Node.js Client'
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/nodejs.svg" alt="node.js logo"/>
</td>
<td>
This guide covers the official Zitadel Management API Client for Node.js (20+), which allows you to programmatically manage resources in your Zitadel instance.
</td>
</tr>
</table>
<Callout>
**This is a Management API Client, not an Authentication SDK.**
This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library with your Node.js framework of choice.
</Callout>
The Zitadel Node.js Client provides an idiomatic way to access the full gamut of Zitadel's v2 Management APIs from your Node.js backend.
> Please be aware that this client library is currently in an **incubating stage**.
While it is available for use, the API and its functionality may evolve, potentially introducing
breaking changes in future updates. We advise caution when considering it for production environments.
### Installation
This package is **published on GitHub Packages**, not on the public npm registry. Create or update a `.npmrc`
file in your project root with:
```ini
@zitadel:registry=https://npm.pkg.github.com
```
You can add the client library to your project using npm, pnpm, or yarn:
```bash
npm install @zitadel/zitadel-node
# or
pnpm add @zitadel/zitadel-node
# or
yarn add @zitadel/zitadel-node
```
### Using the SDK
Your SDK offers three ways to authenticate with Zitadel. Each method has its
own benefits—choose the one that fits your situation best.
#### 1. Private Key JWT Authentication
**What is it?**
You use a JSON Web Token (JWT) that you sign with a private key stored in a
JSON file. This process creates a secure token.
**When should you use it?**
- **Best for production:** It offers strong security.
- **Advanced control:** You can adjust token settings like expiration.
**How do you use it?**
1. Save your private key in a JSON file.
2. Use the provided method to create an authenticator.
**Example:**
```ts
const client = await Zitadel.withPrivateKey(
"https://example.us1.zitadel.cloud",
"path/to/jwt-key.json",
);
try {
const response = await client.users.addHumanUser({
userServiceAddHumanUserRequest: {
username: "john.doe",
profile: {
givenName: "John",
familyName: "Doe"
},
email: {
email: "[email protected]"
},
},
});
console.log("User created:", response);
} catch (e) {
if (e instanceof ApiException) {
console.error("Error:", e.message);
}
}
```
#### 2. Client Credentials Grant
**What is it?**
This method uses a client ID and client secret to get a secure access token,
which is then used to authenticate.
**When should you use it?**
- **Simple and straightforward:** Good for server-to-server communication.
- **Trusted environments:** Use it when both servers are owned or trusted.
**How do you use it?**
1. Provide your client ID and client secret.
2. Use the provided method to create an authenticator.
**Example:**
```ts
const client = await Zitadel.withClientCredentials(
"https://example.us1.zitadel.cloud",
"id",
"secret",
);
try {
const response = await client.users.addHumanUser({
userServiceAddHumanUserRequest: {
username: "john.doe",
profile: {
givenName: "John",
familyName: "Doe"
},
email: {
email: "[email protected]"
},
},
});
console.log("User created:", response);
} catch (e) {
if (e instanceof ApiException) {
console.error("Error:", e.message);
}
}
```
#### 3. Personal Access Tokens (PATs)
**What is it?**
A Personal Access Token (PAT) is a pre-generated token that you can use to
authenticate without exchanging credentials every time.
**When should you use it?**
- **Easy to use:** Great for development or testing scenarios.
- **Quick setup:** No need for dynamic token generation.
**How do you use it?**
1. Obtain a valid personal access token from your account.
2. Use the provided method to create an authenticator.
**Example:**
```ts
const client = await Zitadel.withAccessToken(
"https://example.us1.zitadel.cloud",
"token",
);
try {
const response = await client.users.addHumanUser({
userServiceAddHumanUserRequest: {
username: "john.doe",
profile: {
givenName: "John",
familyName: "Doe"
},
email: {
email: "[email protected]"
},
},
});
console.log("User created:", response);
} catch (e) {
if (e instanceof ApiException) {
console.error("Error:", e.message);
}
}
```
---
Choose the authentication method that best suits your needs based on your
environment and security requirements. For more details, please refer to the
[Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).
### Versioning
The client library's versioning is aligned with the Zitadel core project. The major version of the
client corresponds to the major version of Zitadel it is designed to work with. For example,
v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration.
### Resources
- [GitHub Repository](https://github.com/zitadel/client-nodejs): For source code, examples, and to report issues.
- [npm Package](https://github.com/zitadel/zitadel-node/pkgs/npm/zitadel-node): The official package artifact for npm.
apps/docs/content/sdk-examples/client-libraries/php.mdx
+192
View File
@@ -0,0 +1,192 @@
---
title: PHP Client
sidebar_label: 'PHP Client'
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/php.svg" alt="php logo"/>
</td>
<td>
This guide covers the official Zitadel Management API Client for PHP, which allows you to programmatically manage resources in your Zitadel instance.
</td>
</tr>
</table>
<Callout>
**This is a Management API Client, not an Authentication SDK.**
This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library with your PHP framework of choice.
</Callout>
The Zitadel PHP Client provides an idiomatic way to access the full gamut of
Zitadel's v2 Management APIs from your PHP backend.
> Please be aware that this client library is currently in an **incubating stage**.
While it is available for use, the API and its functionality may evolve, potentially introducing
breaking changes in future updates. We advise caution when considering it for production environments.
### Installation
You can add the client library to your project using Composer:
```bash
composer require zitadel/client:"^4.0.0-beta1"
```
### Using the SDK
Your SDK offers three ways to authenticate with Zitadel. Each method has its
own benefits—choose the one that fits your situation best.
#### 1. Private Key JWT Authentication
**What is it?**
You use a JSON Web Token (JWT) that you sign with a private key stored in a
JSON file. This process creates a secure token.
**When should you use it?**
- **Best for production:** It offers strong security.
- **Advanced control:** You can adjust token settings like expiration.
**How do you use it?**
1. Save your private key in a JSON file.
2. Use the provided method to load this key and create a JWT-based
authenticator.
**Example:**
```php
use \Zitadel\Client\Zitadel;
$zitadel = Zitadel::withPrivateKey("https://example.us1.zitadel.cloud", "path/to/jwt-key.json");
try {
$response = $zitadel->users->userServiceAddHumanUser([
'username' => 'john.doe',
'profile' => [
'givenName' => 'John',
'familyName' => 'Doe'
],
'email' => [
'email' => '[email protected]'
]
]);
echo "User created: " . print_r($response, true);
} catch (ApiException $e) {
echo "Error: " . $e->getMessage();
}
```
#### 2. Client Credentials Grant
**What is it?**
This method uses a client ID and client secret to get a secure access token,
which is then used to authenticate.
**When should you use it?**
- **Simple and straightforward:** Good for server-to-server communication.
- **Trusted environments:** Use it when both servers are owned or trusted.
**How do you use it?**
1. Provide your client ID and client secret.
2. Build the authenticator
**Example:**
```php
use Zitadel\Client\Zitadel;
use Zitadel\Client\Model\UserServiceAddHumanUserRequest;
use \Zitadel\Client\Model\UserServiceAddHumanUserRequest;
use \Zitadel\Client\Model\UserServiceSetHumanProfile;
use \Zitadel\Client\Model\UserServiceSetHumanEmail;
$zitadel = Zitadel::withClientCredentials("https://example.us1.zitadel.cloud", "id", "secret");
try {
$response = $zitadel->users->addHumanUser((new UserServiceAddHumanUserRequest())
->setUsername('john.doe')
->setProfile(
(new UserServiceSetHumanProfile())
->setGivenName('John')
->setFamilyName('Doe')
)
->setEmail(
(new UserServiceSetHumanEmail())
->setEmail('[email protected]')
));
echo "User created: " . print_r($response, true);
} catch (ApiException $e) {
echo "Error: " . $e->getMessage();
}
```
#### 3. Personal Access Tokens (PATs)
**What is it?**
A Personal Access Token (PAT) is a pre-generated token that you can use to
authenticate without exchanging credentials every time.
**When should you use it?**
- **Easy to use:** Great for development or testing scenarios.
- **Quick setup:** No need for dynamic token generation.
**How do you use it?**
1. Obtain a valid personal access token from your account.
2. Create the authenticator with: `PersonalAccessTokenAuthenticator`
**Example:**
```php
use \Zitadel\Client\Zitadel;
use Zitadel\Client\Zitadel;
use Zitadel\Client\Model\UserServiceAddHumanUserRequest;
use \Zitadel\Client\Model\UserServiceAddHumanUserRequest;
use \Zitadel\Client\Model\UserServiceSetHumanProfile;
use \Zitadel\Client\Model\UserServiceSetHumanEmail;
$zitadel = Zitadel::withAccessToken("https://example.us1.zitadel.cloud", "token");
try {
$response = $zitadel->users->addHumanUser(
(new UserServiceAddHumanUserRequest())
->setUsername('john.doe')
->setProfile(
(new UserServiceSetHumanProfile())
->setGivenName('John')
->setFamilyName('Doe')
)
->setEmail(
(new UserServiceSetHumanEmail())
->setEmail('[email protected]')
)
);
echo "User created: " . print_r($response, true);
} catch (ApiException $e) {
echo "Error: " . $e->getMessage();
}
```
---
Choose the authentication method that best suits your needs based on your
environment and security requirements. For more details, please refer to the
[Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).
### Versioning
The client library's versioning is aligned with the Zitadel core project. The major version of the
client corresponds to the major version of Zitadel it is designed to work with. For example,
v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration.
### Resources
- [GitHub Repository](https://github.com/zitadel/client-php): For source code, examples, and to report issues.
- [Packagist Package](https://packagist.org/packages/zitadel/client): The official package artifact for Composer.
apps/docs/content/sdk-examples/client-libraries/python.mdx
+196
View File
@@ -0,0 +1,196 @@
---
title: Python Client
sidebar_label: 'Python Client'
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/python.svg" alt="python logo"/>
</td>
<td>
This guide covers the official Zitadel Management API Client for Python (3.9+), which allows you to programmatically manage resources in your Zitadel instance.
</td>
</tr>
</table>
<Callout>
**This is a Management API Client, not an Authentication SDK.**
This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library with your Python framework of choice, such as `mozilla-django-oidc` for Django or `Authlib` for Flask.
</Callout>
The Zitadel Python Client provides an idiomatic way to access the full gamut of Zitadel's v2 Management APIs from your Python backend.
> Please be aware that this client library is currently in an **incubating stage**.
While it is available for use, the API and its functionality may evolve, potentially introducing
breaking changes in future updates. We advise caution when considering it for production environments.
### Installation
You can add the client library to your project using pip:
```bash
pip install --pre zitadel-client
```
### Using the SDK
Your SDK offers three ways to authenticate with Zitadel. Each method has its
own benefits—choose the one that fits your situation best.
#### 1. Private Key JWT Authentication
**What is it?**
You use a JSON Web Token (JWT) that you sign with a private key stored in a
JSON file. This process creates a secure token.
**When should you use it?**
- **Best for production:** It offers strong security.
- **Advanced control:** You can adjust token settings like expiration.
**How do you use it?**
1. Save your private key in a JSON file.
2. Use the provided method to load this key and create a JWT-based
authenticator.
**Example:**
```python
import zitadel_client as zitadel
from zitadel_client.exceptions import ApiError
from zitadel_client.models import (
UserServiceAddHumanUserRequest,
UserServiceSetHumanEmail,
UserServiceSetHumanProfile,
)
zitadel = zitadel.Zitadel.with_private_key("https://example.us1.zitadel.cloud", "path/to/jwt-key.json")
try:
request = UserServiceAddHumanUserRequest(
username="john.doe",
profile=UserServiceSetHumanProfile(
givenName="John",
familyName="Doe"
),
email=UserServiceSetHumanEmail(
email="[email protected]"
),
)
response = zitadel.users.add_human_user(request)
print("User created:", response)
except ApiError as e:
print("Error:", e)
```
#### 2. Client Credentials Grant
**What is it?**
This method uses a client ID and client secret to get a secure access token,
which is then used to authenticate.
**When should you use it?**
- **Simple and straightforward:** Good for server-to-server communication.
- **Trusted environments:** Use it when both servers are owned or trusted.
**How do you use it?**
1. Provide your client ID and client secret.
2. Build the authenticator
**Example:**
```python
import zitadel_client as zitadel
from zitadel_client.exceptions import ApiError
from zitadel_client.models import (
UserServiceAddHumanUserRequest,
UserServiceSetHumanEmail,
UserServiceSetHumanProfile,
)
zitadel = zitadel.Zitadel.with_client_credentials("https://example.us1.zitadel.cloud", "id", "secret")
try:
request = UserServiceAddHumanUserRequest(
username="john.doe",
profile=UserServiceSetHumanProfile(
givenName="John",
familyName="Doe"
),
email=UserServiceSetHumanEmail(
email="[email protected]"
),
)
response = zitadel.users.add_human_user(request)
print("User created:", response)
except ApiError as e:
print("Error:", e)
```
#### 3. Personal Access Tokens (PATs)
**What is it?**
A Personal Access Token (PAT) is a pre-generated token that you can use to
authenticate without exchanging credentials every time.
**When should you use it?**
- **Easy to use:** Great for development or testing scenarios.
- **Quick setup:** No need for dynamic token generation.
**How do you use it?**
1. Obtain a valid personal access token from your account.
2. Create the authenticator with: `PersonalAccessTokenAuthenticator`
**Example:**
```python
import zitadel_client as zitadel
from zitadel_client.exceptions import ApiError
from zitadel_client.models import (
UserServiceAddHumanUserRequest,
UserServiceSetHumanEmail,
UserServiceSetHumanProfile,
)
zitadel = zitadel.Zitadel.with_access_token("https://example.us1.zitadel.cloud", "token")
try:
request = UserServiceAddHumanUserRequest(
username="john.doe",
profile=UserServiceSetHumanProfile(
givenName="John",
familyName="Doe"
),
email=UserServiceSetHumanEmail(
email="[email protected]"
),
)
response = zitadel.users.add_human_user(request)
print("User created:", response)
except ApiError as e:
print("Error:", e)
```
---
Choose the authentication method that best suits your needs based on your
environment and security requirements. For more details, please refer to the
[Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).
### Versioning
The client library's versioning is aligned with the Zitadel core project. The major version of the
client corresponds to the major version of Zitadel it is designed to work with. For example,
v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration.
### Resources
- [GitHub Repository](https://github.com/zitadel/client-python): For source code, examples, and to report issues.
- [PyPI Package](https://pypi.org/project/zitadel-client): The official package artifact for pip.
apps/docs/content/sdk-examples/client-libraries/ruby.mdx
+200
View File
@@ -0,0 +1,200 @@
---
title: Ruby Client
sidebar_label: 'Ruby Client'
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/ruby.svg" alt="ruby logo"/>
</td>
<td>
This guide covers the official Zitadel Management API Client for Ruby (3.1+), which allows you to programmatically manage resources in your Zitadel instance.
</td>
</tr>
</table>
<Callout>
**This is a Management API Client, not an Authentication SDK.**
This library is designed for server-to-server communication to manage your Zitadel instance (e.g., creating users, managing projects, and updating settings). It is **not** intended for handling end-user login flows in your web application. For user authentication, you should use a standard OIDC library with your Ruby framework of choice.
</Callout>
The Zitadel Ruby Client provides an idiomatic way to access the full gamut of Zitadel's v2 Management APIs from your Ruby backend.
> Please be aware that this client library is currently in an **incubating stage**.
While it is available for use, the API and its functionality may evolve, potentially introducing
breaking changes in future updates. We advise caution when considering it for production environments.
### Installation
You can add the client library to your project using RubyGems. Add this line to your application's Gemfile:
```ruby
gem install zitadel-client --pre
```
### Using the SDK
Your SDK offers three ways to authenticate with Zitadel. Each method has its
own benefits—choose the one that fits your situation best.
#### 1. Private Key JWT Authentication
**What is it?**
You use a JSON Web Token (JWT) that you sign with a private key stored in a
JSON file. This process creates a secure token.
**When should you use it?**
- **Best for production:** It offers strong security.
- **Advanced control:** You can adjust token settings like expiration.
**How do you use it?**
1. Save your private key in a JSON file.
2. Use the provided method to create an authenticator.
**Example:**
```ruby
require 'zitadel-client'
require 'securerandom'
client = Zitadel::Client::Zitadel.with_private_key("https://example.us1.zitadel.cloud", "path/to/jwt-key.json")
begin
response = client.users.add_human_user(
Zitadel::Client::UserServiceAddHumanUserRequest.new(
username: SecureRandom.hex,
profile: Zitadel::Client::UserServiceSetHumanProfile.new(
given_name: 'John',
family_name: 'Doe'
),
email: Zitadel::Client::UserServiceSetHumanEmail.new(
email: "[email protected]"
)
)
)
puts "User created: #{response}"
rescue StandardError => e
puts "Error: #{e.message}"
end
```
#### 2. Client Credentials Grant
**What is it?**
This method uses a client ID and client secret to get a secure access token,
which is then used to authenticate.
**When should you use it?**
- **Simple and straightforward:** Good for server-to-server communication.
- **Trusted environments:** Use it when both servers are owned or trusted.
**How do you use it?**
1. Provide your client ID and client secret.
2. Use the provided method to create an authenticator.
**Example:**
```ruby
require 'zitadel-client'
require 'securerandom'
client = Zitadel::Client::Zitadel.with_client_credentials("https://example.us1.zitadel.cloud", "id", "secret")
begin
response = client.users.add_human_user(
Zitadel::Client::UserServiceAddHumanUserRequest.new(
username: SecureRandom.hex,
profile: Zitadel::Client::UserServiceSetHumanProfile.new(
given_name: 'John',
family_name: 'Doe'
),
email: Zitadel::Client::UserServiceSetHumanEmail.new(
email: "[email protected]"
)
)
)
puts "User created: #{response}"
rescue StandardError => e
puts "Error: #{e.message}"
end
```
#### 3. Personal Access Tokens (PATs)
**What is it?**
A Personal Access Token (PAT) is a pre-generated token that you can use to
authenticate without exchanging credentials every time.
**When should you use it?**
- **Easy to use:** Great for development or testing scenarios.
- **Quick setup:** No need for dynamic token generation.
**How do you use it?**
1. Obtain a valid personal access token from your account.
2. Use the provided method to create an authenticator.
**Example:**
```ruby
require 'zitadel-client'
require 'securerandom'
client = Zitadel::Client::Zitadel.with_access_token("https://example.us1.zitadel.cloud", "token")
begin
response = client.users.add_human_user(
Zitadel::Client::UserServiceAddHumanUserRequest.new(
username: SecureRandom.hex,
profile: Zitadel::Client::UserServiceSetHumanProfile.new(
given_name: 'John',
family_name: 'Doe'
),
email: Zitadel::Client::UserServiceSetHumanEmail.new(
email: "[email protected]"
)
)
)
puts "User created: #{response}"
rescue StandardError => e
puts "Error: #{e.message}"
end
```
---
Choose the authentication method that best suits your needs based on your
environment and security requirements. For more details, please refer to the
[Zitadel documentation on authenticating service users](https://zitadel.com/docs/guides/integrate/service-users/authenticate-service-users).
### Debugging
The SDK supports debug logging, which can be enabled for troubleshooting
and debugging purposes. You can enable debug logging by setting the `debug`
flag to `true` when initializing the `Zitadel` client, like this:
```ruby
zitadel = zitadel.Zitadel("your-zitadel-base-url", 'your-valid-token', lambda config: config.debug = True)
```
When enabled, the SDK will log additional information, such as HTTP request
and response details, which can be useful for identifying issues in the
integration or troubleshooting unexpected behavior.
### Versioning
The client library's versioning is aligned with the Zitadel core project. The major version of the
client corresponds to the major version of Zitadel it is designed to work with. For example,
v2.x.x of the client is built for and tested against Zitadel v2, ensuring a predictable and stable integration.
### Resources
- [GitHub Repository](https://github.com/zitadel/client-ruby): For source code, examples, and to report issues.
- [RubyGems Package](https://rubygems.org/gems/zitadel-client): The official package artifact for RubyGems.
apps/docs/content/sdk-examples/django.mdx
+81
View File
@@ -0,0 +1,81 @@
---
title: Django
sidebar_label: Django
framework_url: https://www.djangoproject.com
auth_library: "Authlib"
auth_library_url: https://authlib.org
example_repo: https://github.com/zitadel/example-auth-django
auth_flow: pkce
status: stable
---
## Overview
[Django](https://www.djangoproject.com) is a high-level Python web framework that encourages rapid development and clean, pragmatic design. It provides a robust set of features for web applications, making it one of the most popular choices for building server-side applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
#### Auth library
This example uses **[Authlib](https://authlib.org)**, the standard authentication library for Python web frameworks. Authlib implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management helpers. The integration uses Authlib's Django client which seamlessly handles OAuth 2.0 flows within Django applications.
---
## What this example demonstrates
This example shows a complete authentication implementation using [Django](https://www.djangoproject.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/pkce/), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) after successful authentication.
The application implements server-side session management with Django's built-in session framework, storing authentication state securely in signed cookies. Protected routes use the `@require_auth` decorator to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint).
The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles).
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-django).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-zitadel-application-client-id
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer)
- The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID`
- The **redirect URI** you configured in the PKCE setup for `ZITADEL_CALLBACK_URL` (must match exactly)
- The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL`
- A strong random string for `SESSION_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`)
- A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`)
3. Install dependencies using [Poetry](https://python-poetry.org) with `poetry install` and start the development server with `poetry run python manage.py runserver localhost:3000` to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Django documentation](https://www.djangoproject.com)
* [Authlib documentation](https://authlib.org)
* [Example repository](https://github.com/zitadel/example-auth-django)
apps/docs/content/sdk-examples/expressjs.mdx
+88
View File
@@ -0,0 +1,88 @@
---
title: Express.js
sidebar_label: Express.js
framework_url: https://expressjs.com
auth_library: "@auth/express"
auth_library_url: https://www.npmjs.com/package/@auth/express
example_repo: https://github.com/zitadel/example-auth-expressjs
auth_flow: pkce
status: stable
---
## Overview
[Express.js](https://expressjs.com) is a fast, unopinionated, minimalist web framework for [Node.js](https://nodejs.org) that provides a robust set of features for building web and mobile applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your Express application.
#### Auth library
This example uses **[@auth/express](https://www.npmjs.com/package/@auth/express)** ([GitHub](https://github.com/nextauthjs/next-auth)), the Express.js adapter for [Auth.js](https://authjs.dev). This library implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol with [PKCE](https://oauth.net/2/pkce/) support, manages [token exchange](https://zitadel.com/docs/apis/openidoauth/grant-types), performs automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token), and provides session management with secure cookie-based storage.
---
## What this example demonstrates
This Express.js example provides a complete authentication implementation using [Zitadel](https://zitadel.com/docs) as the identity provider. The application starts with a public landing page featuring a login button that initiates the [PKCE authentication flow](https://oauth.net/2/pkce/). When users click login, [@auth/express](https://www.npmjs.com/package/@auth/express) generates a cryptographic code verifier and challenge, then redirects to Zitadel's authorization endpoint. After successful authentication at Zitadel, users return to the application's [callback URL](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) where the authorization code is exchanged for [access tokens](https://zitadel.com/docs/apis/openidoauth/endpoints) and an [ID token](https://zitadel.com/docs/apis/openidoauth/claims).
The example includes protected routes using [Express middleware](https://expressjs.com/en/guide/using-middleware.html) that automatically verify session state and redirect unauthenticated users to the sign-in page. Authenticated users can access their profile page displaying user information including email, name, and custom [metadata claims](https://expressjs.com/en/guide/using-middleware.html) that automatically verify session state and redirect unauthenticated users to the sign-in page. Authenticated users can access their profile page displaying user information including email, name, and custom [metadata claims](https://zitadel.com/docs/apis/openidoauth/claims) from Zitadel. The application maintains long-lived sessions through automatic [token refresh](https://expressjs.com/en/guide/using-middleware.html) that automatically verify session state and redirect unauthenticated users to the sign-in page. Authenticated users can access their profile page displaying user information including email, name, and custom [metadata claims](https://zitadel.com/docs/apis/openidoauth/claims) from Zitadel. The application maintains long-lived sessions through automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint), ensuring users remain authenticated without repeated logins.
Sign-out functionality implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by redirecting to Zitadel's end-session endpoint with the ID token hint, terminating both the local session and the Zitadel session. The logout flow includes [CSRF protection](https://authjs.dev/guides/basics/securing-pages-and-api-routes) through state parameter validation, and users are redirected to a success page after logout completion. All authentication flows use secure HTTP-only cookies for [session storage](https://authjs.dev/concepts/session-strategies) and implement proper security headers.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/login-users):
1. Clone the [repository](https://github.com/zitadel/example-auth-expressjs).
2. Create a `.env.local` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). Use the exact environment variable names from the repository:
```
NODE_ENV=development
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
SESSION_DURATION=3600
ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id_from_console
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000
```
Replace these values with:
- Your actual Zitadel instance URL (the **Issuer** from the PKCE setup guide)
- The **Client ID** you copied when creating the application
- A randomly generated client secret (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
- The **redirect URI** you configured in the PKCE setup (must match exactly)
- A strong session secret (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
The application will be running at `http://localhost:3000`.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Framework docs](https://expressjs.com)
* [Auth library](https://www.npmjs.com/package/@auth/express)
* [Auth.js documentation](https://authjs.dev)
* [Example repository](https://github.com/zitadel/example-auth-expressjs)
apps/docs/content/sdk-examples/fastapi.mdx
+82
View File
@@ -0,0 +1,82 @@
---
title: FastAPI
sidebar_label: FastAPI
framework_url: https://fastapi.tiangolo.com
auth_library: "Authlib"
auth_library_url: https://authlib.org
example_repo: https://github.com/zitadel/example-auth-fastapi
auth_flow: pkce
status: stable
---
## Overview
[FastAPI](https://fastapi.tiangolo.com) is a modern, fast (high-performance) web framework for building APIs with Python based on standard Python type hints. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
#### Auth library
This example uses **[Authlib](https://authlib.org)**, the standard authentication library for Python web frameworks. Authlib implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management helpers. The integration uses Authlib's Starlette client which seamlessly handles OAuth 2.0 flows within FastAPI applications built on [Starlette](https://www.starlette.io).
---
## What this example demonstrates
This example shows a complete authentication implementation using [FastAPI](https://fastapi.tiangolo.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/pkce/), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) after successful authentication.
The application implements server-side session management with Starlette's session middleware, storing authentication state securely in encrypted cookies. Protected routes use the `require_auth` dependency to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint).
The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles).
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-fastapi).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
PY_ENV=development
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-zitadel-application-client-id
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer)
- The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID`
- The **redirect URI** you configured in the PKCE setup for `ZITADEL_CALLBACK_URL` (must match exactly)
- The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL`
- A strong random string for `SESSION_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`)
- A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`)
3. Install dependencies using [Poetry](https://python-poetry.org) with `poetry install` and start the development server with `poetry run python run.py` to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [FastAPI documentation](https://fastapi.tiangolo.com)
* [Authlib documentation](https://authlib.org)
* [Example repository](https://github.com/zitadel/example-auth-fastapi)
apps/docs/content/sdk-examples/fastify.mdx
+83
View File
@@ -0,0 +1,83 @@
---
title: Fastify
sidebar_label: Fastify
framework_url: https://fastify.dev
auth_library: "@auth/core"
auth_library_url: https://www.npmjs.com/package/@auth/core
example_repo: https://github.com/zitadel/example-auth-fastify
auth_flow: pkce
status: stable
---
## Overview
[Fastify](https://fastify.dev) is a fast and low overhead web framework for Node.js, designed for building efficient server-side applications. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
#### Auth library
This example uses **[@mridang/fastify-auth](https://www.npmjs.com/package/@mridang/fastify-auth)**, a [Fastify](https://fastify.dev) plugin that wraps **[@auth/core](https://www.npmjs.com/package/@auth/core)** (formerly Auth.js). The underlying [@auth/core](https://authjs.dev) library implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management helpers. This integration leverages the **[@auth/core/providers/zitadel](https://authjs.dev/reference/core/providers/zitadel)** provider specifically designed for Zitadel authentication.
---
## What this example demonstrates
This example shows a complete authentication implementation using [Fastify](https://fastify.dev) with [server-side rendering](https://fastify.dev) via [@fastify/view](https://www.npmjs.com/package/@fastify/view) and [Handlebars](https://handlebarsjs.com) templates. The application implements secure user authentication through [Zitadel](https://zitadel.com/docs) using the industry-standard [PKCE flow](https://oauth.net/2/pkce/), which prevents authorization code interception attacks without requiring client secrets.
The example includes a custom sign-in page that initiates the [OAuth 2.0](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) authentication flow, automatic [callback handling](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) authentication flow, automatic [callback handling](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) with secure token exchange, and [JWT-based session management](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) with [@fastify/cookie](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) authentication flow, automatic [callback handling](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) with secure token exchange, and [JWT-based session management](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with [@fastify/cookie](https://www.npmjs.com/package/@fastify/cookie). Protected routes use the `requireAuth` middleware to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) authentication flow, automatic [callback handling](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) with secure token exchange, and [JWT-based session management](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with [@fastify/cookie](https://www.npmjs.com/package/@fastify/cookie). Protected routes use the `requireAuth` middleware to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint).
The application also demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles).
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-fastify).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
NODE_ENV=development
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
SESSION_DURATION=3600
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-zitadel-application-client-id
ZITADEL_CLIENT_SECRET=
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer)
- The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID`
- The **redirect URI** you configured in the PKCE setup for `ZITADEL_CALLBACK_URL` (must match exactly)
- The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL`
- A strong random string for `SESSION_SECRET` (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
3. Install dependencies using [npm](https://www.npmjs.com) with `npm install` and start the development server with `npm run dev` to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Fastify documentation](https://fastify.dev)
* [Auth.js (Auth/Core)](https://www.npmjs.com/package/@auth/core)
* [Fastify Auth plugin](https://www.npmjs.com/package/@mridang/fastify-auth)
* [Example repository](https://github.com/zitadel/example-auth-fastify)
apps/docs/content/sdk-examples/flask.mdx
+82
View File
@@ -0,0 +1,82 @@
---
title: Flask
sidebar_label: Flask
framework_url: https://flask.palletsprojects.com
auth_library: "Authlib"
auth_library_url: https://authlib.org
example_repo: https://github.com/zitadel/example-auth-flask
auth_flow: pkce
status: stable
---
## Overview
[Flask](https://flask.palletsprojects.com) is a lightweight WSGI web application framework for Python. It's designed to make getting started quick and easy, with the ability to scale up to complex applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
#### Auth library
This example uses **[Authlib](https://authlib.org)**, the standard authentication library for Python web frameworks. Authlib implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management helpers. The integration uses Authlib's Flask client which seamlessly handles OAuth 2.0 flows within Flask applications.
---
## What this example demonstrates
This example shows a complete authentication implementation using [Flask](https://flask.palletsprojects.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/pkce/), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) after successful authentication.
The application implements server-side session management with Flask's built-in session handling, storing authentication state securely in encrypted cookies. Protected routes use the `@require_auth` decorator to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint).
The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles).
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-flask).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
PY_ENV=development
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-zitadel-application-client-id
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer)
- The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID`
- The **redirect URI** you configured in the PKCE setup for `ZITADEL_CALLBACK_URL` (must match exactly)
- The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL`
- A strong random string for `SESSION_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`)
- A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `python -c "import secrets; print(secrets.token_hex(32))"`)
3. Install dependencies using [Poetry](https://python-poetry.org) with `poetry install` and start the development server with `poetry run python run.py` to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Flask documentation](https://flask.palletsprojects.com)
* [Authlib documentation](https://authlib.org)
* [Example repository](https://github.com/zitadel/example-auth-flask)
apps/docs/content/sdk-examples/flutter.mdx
+67
View File
@@ -0,0 +1,67 @@
---
title: Flutter
sidebar_label: Flutter
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/flutter.svg" alt="flutter logo"/>
</td>
<td>
<a href="https://flutter.dev/" target="_blank">Flutter</a> 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 <a href="https://github.com/zitadel/zitadel_flutter" target="_blank">zitadel-flutter</a> Example.
</td>
</tr>
</table>
### 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 User
- Generated gRPC Clients for integrating ZITADEL API
- User, Organization, Project, etc. Management
<Callout>
This library is built by our community.
</Callout>
### Example Application
The [zitadel-flutter](https://github.com/zitadel/zitadel_flutter) repository includes an Example Application ready to start and show how an 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
<div style={{display: 'grid', 'gridColumnGap': '1rem', 'gridTemplateColumns': '1fr 1fr', 'maxWidth': '500px', 'margin': '0 auto'}}>
<img src="/docs/img/flutter/not-authed.png" alt="Unauthenticated" height="500px" />
<img src="/docs/img/flutter/authed.png" alt="Flutter Authenticated" height="500px" />
</div>
<div style={{display: 'grid', 'gridColumnGap': '1rem', 'gridTemplateColumns': '1fr 1fr', 'maxWidth': '800px', 'margin': '0 auto'}}>
<img src="/docs/img/flutter/web-not-authed.png" alt="Unauthenticated" height="500px" />
<img src="/docs/img/flutter/web-authed.png" alt="Flutter Authenticated" height="500px" />
</div>
apps/docs/content/sdk-examples/go.mdx
+104
View File
@@ -0,0 +1,104 @@
---
title: Go
sidebar_label: Go
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/golang.svg" alt="go logo"/>
</td>
<td>
<a href="https://go.dev/" target="_blank">Go</a> is an open-source, compiled programming language that is known for its simplicity, efficiency, and concurrency capabilities.
Get started integrating authentication to your Go Application by checking out our <a href="https://github.com/zitadel/zitadel-go" target="_blank">zitadel-go</a> SDK.
</td>
</tr>
</table>
### Resources
- [Example App Repository](https://github.com/zitadel/zitadel-go)
- [Go SDK](https://github.com/zitadel/zitadel-go)
- [Web APP Step-By-Step Guide](/examples/login/go)
- [API APP Step-By-Step Guide](/examples/secure-api/go)
- [Go OIDC Library](https://github.com/zitadel/oidc)
### Go SDK
The [zitadel-go](https://github.com/zitadel/zitadel-go) SDK is a wrapper around the [zitadel/oidc](https://github.com/zitadel/oidc) to integrate Login into your Web App and abstracts the handling of specific configurations for ZITADEL.
Additionally secure your business APIs and handle permission checks for your users.
Last part is the integration of the ZITADEL APIs to handle user and resource management.
The following features are covered by the SDK:
- Authentication in your Web App
- Authenticate your user with ZITADEL using OIDC
- Requesting ZITADEL userinfo endpoint to get user data
- Refresh Token
- Requesting User Roles from userinfo
- Check if user has specified role
- Logout
- Secure your APIs
- Authorization Check using OAuth2 Introspection
- Check User Roles on Endpoint
- Manage Resources through ZITADEL APIs
- Authenticate Service User
- Generated gRPC Clients for integrating ZITADEL API
- User, Organization, Project, etc. Management
The goal is to extend the SDK over the time with the following features:
- Build your own login UI using our Session API
### Go Examples
You can find different examples for building your Go application in the following package of the repository:
[zitadel-go/example](https://github.com/zitadel/zitadel-go/tree/next/example)
#### Web Application Example
What does the Web Application Example include:
- Home Page with Login Button
- Authenticating user with OIDC PKCE Flow
- Public Page: Accessible without authentication
- Private Page: Shows user information of authenticated user, only accessible after login
- Logout
[Example Web App](https://github.com/zitadel/zitadel-go/tree/next/example/app)
#### API Application Example
What does the API Application Example include:
- REST API Application secured with Spring Security and OAuth2
- Public Endpoint: Accessible without authentication
- Private Endpoint: Accessible with a token
- Administrator Endpoint: Accessible with a token of a user with an administrator role
[Example API App](https://github.com/zitadel/zitadel-go/tree/next/example/api/http)
### Step-By-Step Guide
For Go we do have two different Step-By-Step Guides.
One to create your web application with integrated login and one to create your API with permission checks for calling users.
The guides lead you through the whole process from configuring the right application in ZITADEL to a ready application with integrated login or authentication checks.
#### Web Application Guide
After completing the Step-By-Step Guide you will have:
1. Example Web Application with integrated ZITADEL Login
2. Example page accessible by authenticated user showing retrieved user information
4. Logout
5. Correct setup for your application in ZITADEL
[Web APP Step-By-Step Guide](/examples/login/go)
![](../../public/img/go/app-home.png)
![](../../public/img/go/app-profile.png)
#### API Application Guide
After completing the Step-By-Step Guide you will have:
1. Example REST API checking tokens against ZITADEL with OAuth2
2. Public Endpoint accessible by any user
3. Private Endpoint accessible by authenticated user
4. Private Endpoint accessible by user with role 'admin'
5. Correct setup for your application in ZITADEL
[API APP Step-By-Step Guide](/examples/secure-api/go)
apps/docs/content/sdk-examples/hono.mdx
+90
View File
@@ -0,0 +1,90 @@
---
title: Hono
sidebar_label: Hono
framework_url: https://hono.dev
auth_library: "@auth/core"
auth_library_url: https://authjs.dev
example_repo: https://github.com/zitadel/example-auth-hono
auth_flow: pkce
status: stable
---
## Overview
[Hono](https://hono.dev) is a small, simple, and ultra-fast web framework for the Edges that works on Cloudflare Workers, Fastly Compute, Deno, Bun, Vercel, Netlify, AWS Lambda, Lambda@Edge, and Node.js. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your Hono application.
#### Auth library
This example uses **[Auth.js](https://authjs.dev)** (formerly NextAuth.js), the standard authentication library for modern web frameworks. Auth.js implements the [OpenID Connect](https://openid.net/connect/) (OIDC) protocol with [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management helpers. The integration uses **[@hono/auth-js](https://www.npmjs.com/package/@hono/auth-js)**, the official Hono adapter for Auth.js, along with **[@auth/core](https://www.npmjs.com/package/@auth/core)** which handles the core OIDC flows and the **[Zitadel provider](https://authjs.dev/reference/core/providers/zitadel)**.
---
## What this example demonstrates
This example showcases a complete web application authentication pattern with [Hono](https://hono.dev) and [Zitadel](https://zitadel.com/docs). Users start on a public landing page, initiate authentication with Zitadel using the secure [PKCE flow](https://oauth.net/2/pkce/), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) after successful authentication. The application demonstrates several key features including sign-in with [authorization code flow + PKCE](https://oauth.net/2/pkce/), OAuth callback handling with secure [session storage](https://authjs.dev/concepts/session-strategies) using [JWT strategy](https://authjs.dev/concepts/session-strategies#jwt-session), route protection through [authentication middleware](https://hono.dev/docs/guides/middleware) that guards sensitive pages, automatic [token refresh](https://authjs.dev/guides/refresh-token-rotation) to maintain long-lived sessions without requiring re-authentication, access to user profile information including [OIDC standard claims](https://zitadel.com/docs/apis/openidoauth/claims) and [Zitadel-specific claims](https://zitadel.com/docs/apis/openidoauth/claims#reserved-claims) such as organization roles and metadata, and secure sign-out with [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) that terminates both the local session and the Zitadel session through the end-session endpoint.
The implementation uses [Handlebars templates](https://handlebarsjs.com/) for server-side rendering, [@hono/node-server](https://www.npmjs.com/package/@hono/node-server) for running on Node.js, secure [HTTP-only cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#security) for session management, and [CSRF protection](https://authjs.dev/concepts/session-strategies#csrf-protection) through Auth.js built-in tokens. The authentication flow follows OAuth 2.0 best practices with [Proof Key for Code Exchange](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) to prevent authorization code interception attacks.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your Zitadel application configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-hono).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use the exact environment variable names from the repository:**
```
NODE_ENV=development
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
SESSION_DURATION=3600
ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id_from_console
ZITADEL_CLIENT_SECRET=
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000
```
Replace these values with:
- Your actual **Zitadel instance URL** (the Issuer from your [instance settings](https://zitadel.com/docs/guides/manage/console/default-settings))
- The **Client ID** you copied when creating the application in the PKCE setup
- The **redirect URI** you configured in the PKCE setup (must match exactly)
- The **post-logout redirect URI** for handling logout callbacks
- A strong random **session secret** (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
> **Note:** While PKCE doesn't require a client secret for public clients, Auth.js requires a value for internal configuration. You can leave `ZITADEL_CLIENT_SECRET` empty or provide a random string.
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
The application will be running at `http://localhost:3000`. Visit the homepage to test the authentication flow.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [OAuth recommended flows](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows)
* [Framework docs](https://hono.dev)
* [Auth.js](https://authjs.dev)
* [Auth.js Hono adapter](https://www.npmjs.com/package/@hono/auth-js)
* [Example repository](https://github.com/zitadel/example-auth-hono)
apps/docs/content/sdk-examples/introduction.mdx
+127
View File
@@ -0,0 +1,127 @@
---
title: Examples and SDKs for Zitadel
sidebar_label: Introduction
---
import { Frameworks } from "@/components/frameworks";
You can integrate Zitadel quickly into your application and be up and running within minutes.
To achieve your goals as fast as possible, we provide you with SDKs, Example Repositories and Guides.
The SDKs and integration depend on the framework and language you are using.
<Callout>
In addition to our officially maintained examples, we also list community-contributed implementations.
These examples are provided by external developers and are not maintained by us.
While we believe they can be valuable resources and showcase diverse approaches, we cannot guarantee their completeness, functionality, or continued support.
If you encounter issues with a community-contributed example, please contact the respective maintainers directly.
We provide this list for informational purposes and to foster community engagement, but we do not assume responsibility for these external implementations.
</Callout>
## Clients
<Frameworks filter={(framework) => framework.client === true } />
## SDKs
<Frameworks filter={(framework) => framework.sdk === true } />
## Resources
<Frameworks filter={(framework) => 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 configuration 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](https://zitadel.com/signin).
## 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.
If we do not provide an specific example, SDK or guide, we strongly recommend using existing authentication libraries for your
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
- [B2B customer portal](https://github.com/zitadel/zitadel-nextjs-b2b): Showcase the use of personal access tokens in a B2B environment. Uses NextJS Framework.
- [Frontend with backend API](https://github.com/zitadel/example-quote-generator-app): A simple web application using a React front-end and a Python back-end API, both secured using Zitadel
- [Introspection](https://github.com/zitadel/examples-api-access-and-token-introspection): Python examples for securing an API and invoking it as a service user
- [Fine-grained authorization](https://github.com/zitadel/example-fine-grained-authorization): Leverage actions, custom metadata, and claims for attribute-based access control
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
Is your language/framework missing? Fear not, you can generate your gRPC API Client with ease.
1. Make sure to install [buf](https://buf.build/docs/installation/)
2. Create a `buf.gen.yaml` and configure the [plugins](https://buf.build/plugins) you need
3. Run `buf generate https://github.com/zitadel/zitadel#format=git,tag=v2.23.1` (change the versions to your needs)
Let us make an example with Ruby. Any other supported language by buf will work as well. Consult
the [buf plugin registry](https://buf.build/plugins) for more ideas.
### Example with Ruby
With gRPC we usually need to generate the client stub and the messages/types. This is why we need two plugins.
The plugin `grpc/ruby` generates the client stub and the plugin `protocolbuffers/ruby` takes care of the messages/types.
```yaml
version: v1
plugins:
- plugin: buf.build/grpc/ruby
out: gen
- plugin: buf.build/protocolbuffers/ruby
out: gen
```
If you now run `buf generate https://github.com/zitadel/zitadel#format=git,tag=v2.23.1` in the folder where
your `buf.gen.yaml` is located you should see the folder `gen` appear.
If you run `ls -la gen/zitadel/` you should see something like this:
```bash
ffo@ffo-pc:~/git/zitadel/ruby$ ls -la gen/zitadel/
total 704
drwxr-xr-x 2 ffo ffo 4096 Apr 11 16:49 .
drwxr-xr-x 3 ffo ffo 4096 Apr 11 16:49 ..
-rw-r--r-- 1 ffo ffo 4397 Apr 11 16:49 action_pb.rb
-rw-r--r-- 1 ffo ffo 141097 Apr 11 16:49 admin_pb.rb
-rw-r--r-- 1 ffo ffo 25151 Apr 11 16:49 admin_services_pb.rb
-rw-r--r-- 1 ffo ffo 6537 Apr 11 16:49 app_pb.rb
-rw-r--r-- 1 ffo ffo 1134 Apr 11 16:49 auth_n_key_pb.rb
-rw-r--r-- 1 ffo ffo 32881 Apr 11 16:49 auth_pb.rb
-rw-r--r-- 1 ffo ffo 6896 Apr 11 16:49 auth_services_pb.rb
-rw-r--r-- 1 ffo ffo 1571 Apr 11 16:49 change_pb.rb
-rw-r--r-- 1 ffo ffo 2488 Apr 11 16:49 event_pb.rb
-rw-r--r-- 1 ffo ffo 14782 Apr 11 16:49 idp_pb.rb
-rw-r--r-- 1 ffo ffo 5031 Apr 11 16:49 instance_pb.rb
-rw-r--r-- 1 ffo ffo 223348 Apr 11 16:49 management_pb.rb
-rw-r--r-- 1 ffo ffo 44402 Apr 11 16:49 management_services_pb.rb
-rw-r--r-- 1 ffo ffo 3020 Apr 11 16:49 member_pb.rb
-rw-r--r-- 1 ffo ffo 855 Apr 11 16:49 message_pb.rb
-rw-r--r-- 1 ffo ffo 1445 Apr 11 16:49 metadata_pb.rb
-rw-r--r-- 1 ffo ffo 2370 Apr 11 16:49 object_pb.rb
-rw-r--r-- 1 ffo ffo 621 Apr 11 16:49 options_pb.rb
-rw-r--r-- 1 ffo ffo 4425 Apr 11 16:49 org_pb.rb
-rw-r--r-- 1 ffo ffo 8538 Apr 11 16:49 policy_pb.rb
-rw-r--r-- 1 ffo ffo 8223 Apr 11 16:49 project_pb.rb
-rw-r--r-- 1 ffo ffo 1022 Apr 11 16:49 quota_pb.rb
-rw-r--r-- 1 ffo ffo 5872 Apr 11 16:49 settings_pb.rb
-rw-r--r-- 1 ffo ffo 20985 Apr 11 16:49 system_pb.rb
-rw-r--r-- 1 ffo ffo 4784 Apr 11 16:49 system_services_pb.rb
-rw-r--r-- 1 ffo ffo 28759 Apr 11 16:49 text_pb.rb
-rw-r--r-- 1 ffo ffo 24170 Apr 11 16:49 user_pb.rb
-rw-r--r-- 1 ffo ffo 13568 Apr 11 16:49 v1_pb.rb
```
Import these files into your project to start interacting with Zitadel's APIs.
apps/docs/content/sdk-examples/java.mdx
+100
View File
@@ -0,0 +1,100 @@
---
title: Java Spring Boot
sidebar_label: Java Spring Boot
---
<table>
<tr>
<td width="100px">
<img width="100px" src="/docs/img/tech/java.svg" alt="java logo"/>
</td>
<td>
<a href="https://www.java.com/" target="_blank">Java</a> is a general-purpose programming language designed for object-oriented programming.
<a href="https://spring.io/projects/spring-security/" target="_blank">Spring Security</a> is used to protect your applications from unauthorized access, protect sensitive data, and enforce access control policies.
Get started integrating authentication to your Java Web App or API by checking out our <a href="https://github.com/zitadel/zitadel-java" target="_blank">zitadel-java</a> Example
</td>
</tr>
</table>
### Resources
- [Example App Repository with Spring Security](https://github.com/zitadel/zitadel-java)
- [Example Web App with Spring Security](https://github.com/zitadel/zitadel-java/tree/main/web)
- [Example API App with Spring Security](https://github.com/zitadel/zitadel-java/tree/main/api)
- [Web APP Step-By-Step Guide](/examples/login/java-spring)
- [API APP Step-By-Step Guide](/examples/secure-api/java-spring)
### Java SDK
Java Spring Security is a widely used and common framework to integrate Authentication and Authorization into your Applications.
As of this at the moment there is no specific ZITADEL SDK, but we do show you how to integrate ZITADEL with Java Spring Security.
You can use this for both your Web as for your API Applications.
The following features are covered by Java Spring Security:
- Authenticate your user using OIDC
- Requesting ZITADEL userinfo endpoint to get user data
- Refresh Token
- Requesting User Roles from userinfo
- Check if user has specified role
- Logout
The goal is to have a ZITADEL Java SDK in the future which will cover the following:
- Wrapper around Java Spring Security
- Authentication with OIDC
- Authorization and checking Roles
- Integrate ZITADEL APIs to read and manage resources
- Integrate ZITADEL Session API to create your own login UI
### Java Examples
#### Web Application Example
What does the Web Application Example include:
- Home Page with Login Button
- Authenticating user with OIDC PKCE Flow
- Public Page: Accessible without authentication
- Private Page: Shows user information of authenticated user, only accessible after login
- Task Page: Only accessible after login and uses the API example. Requires the administrator role for the application for some interaction.
- Logout
[Example Web App with Spring Security](https://github.com/zitadel/zitadel-java/web)
#### API Application Example
What does the API Application Example include:
- REST API Application secured with Spring Security and OAuth2
- Public Endpoint: Accessible without authentication
- Private Endpoint: Accessible with a token
- Administrator Endpoint: Accessible with a token of a user with an administrator role
[Example API App with Spring Security](https://github.com/zitadel/zitadel-java/api)
### Step-By-Step Guide
For Java Spring we do have two different Step-By-Step Guides.
One to create your web application with integrated login and one to create your API with permission checks for calling users.
The guides lead you through the whole process from configuring the right application in ZITADEL to a ready application with integrated login or authentication checks.
#### Web Application Guide
After completing the Step-By-Step Guide, you will have:
1. Example Web Application with integrated ZITADEL Login
2. Example page accessible by authenticated user showing retrieved user information
3. Example page accessible by an authenticated user showing a task list
- Task list can be read by an authenticated user
- New tasks can be created by a user with an administrator role
4. Logout
5. Correct setup for your application in ZITADEL
[Web APP Step-By-Step Guide](/examples/login/java-spring)
![](../../public/img/java-spring/app-profile.png)
#### API Application Guide
After completing the Step-By-Step Guide, you will have:
1. Example REST API checking tokens against ZITADEL with OAuth2
2. Public Endpoint accessible by any user
3. Private Endpoint accessible by authenticated user
4. Private Endpoint accessible by the user with the role 'admin'
5. Correct setup for your application in ZITADEL
[API APP Step-By-Step Guide](/examples/secure-api/java-spring)
apps/docs/content/sdk-examples/laravel.mdx
+82
View File
@@ -0,0 +1,82 @@
---
title: Laravel
sidebar_label: Laravel
framework_url: https://laravel.com
auth_library: "Laravel Socialite"
auth_library_url: https://laravel.com/docs/socialite
example_repo: https://github.com/zitadel/example-auth-laravel
auth_flow: pkce
status: stable
---
## Overview
[Laravel](https://laravel.com) is a web application framework with expressive, elegant syntax. It provides a robust set of features for web applications, making it one of the most popular choices for building server-side applications. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
#### Auth library
This example uses **[Laravel Socialite](https://laravel.com/docs/socialite)**, the standard authentication library for Laravel applications. Laravel Socialite implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow through a custom Zitadel provider, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management through Laravel's authentication system.
---
## What this example demonstrates
This example shows a complete authentication implementation using [Laravel](https://laravel.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/pkce/), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) after successful authentication.
The application implements server-side session management with Laravel's built-in session handling, storing authentication state securely in encrypted cookies. Protected routes use Laravel middleware to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint).
The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles).
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-laravel).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
APP_KEY=your-app-key
APP_ENV=local
APP_DEBUG=true
SERVER_URL=http://localhost:3000
SERVER_PORT=3000
DB_CONNECTION=sqlite
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-zitadel-application-client-id
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer)
- The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID`
- The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL`
- A strong random string for `APP_KEY` (generate using: `php artisan key:generate`)
- A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `php -r "echo bin2hex(random_bytes(32));"`)
3. Install dependencies using [Composer](https://getcomposer.org) with `composer install` and start the development server with `composer run dev` to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Laravel documentation](https://laravel.com/docs)
* [Laravel Socialite documentation](https://laravel.com/docs/socialite)
* [Example repository](https://github.com/zitadel/example-auth-laravel)
apps/docs/content/sdk-examples/nestjs.mdx
+94
View File
@@ -0,0 +1,94 @@
---
title: NestJS
sidebar_label: NestJS
framework_url: https://nestjs.com
auth_library: "@auth/core"
auth_library_url: https://www.npmjs.com/package/@auth/core
example_repo: https://github.com/zitadel/example-auth-nestjs
auth_flow: pkce
status: stable
---
## Overview
[NestJS](https://nestjs.com) is a progressive Node.js framework for building efficient, reliable, and scalable server-side applications using [TypeScript](https://www.typescriptlang.org). This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your NestJS application.
#### Auth library
This example uses **[@auth/core](https://www.npmjs.com/package/@auth/core)**, the core authentication library powering [Auth.js](https://authjs.dev), which implements the [OpenID Connect (OIDC)](https://openid.net/connect/) flow, manages [PKCE](https://oauth.net/2/pkce/), performs token exchange, and exposes helpers for [session state](https://zitadel.com/docs/guides/integrate/login/oidc/login-users). The example integrates this through the **[@mridang/nestjs-auth](https://www.npmjs.com/package/@mridang/nestjs-auth)** [NestJS module](https://docs.nestjs.com/modules), which provides [decorators](https://docs.nestjs.com/custom-decorators), [guards](https://docs.nestjs.com/guards), and middleware for seamless authentication within the NestJS ecosystem.
---
## What this example demonstrates
This example implements a complete authentication flow using [PKCE](https://oauth.net/2/pkce/) with [Zitadel](https://oauth.net/2/pkce/) with [Zitadel](https://zitadel.com/docs) as the identity provider. Users begin on a public landing page and click a login button to authenticate through Zitadel's authorization server. After successful authentication, they're redirected to a protected profile page displaying their user information retrieved from the [ID token](https://oauth.net/2/pkce/) with [Zitadel](https://zitadel.com/docs) as the identity provider. Users begin on a public landing page and click a login button to authenticate through Zitadel's authorization server. After successful authentication, they're redirected to a protected profile page displaying their user information retrieved from the [ID token](https://zitadel.com/docs/apis/openidoauth/claims) and [access token](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint).
The application leverages [NestJS controllers](https://docs.nestjs.com/controllers) to handle authentication routes and [@mridang/nestjs-auth guards](https://docs.nestjs.com/controllers) to handle authentication routes and [@mridang/nestjs-auth guards](https://www.npmjs.com/package/@mridang/nestjs-auth) to protect routes requiring authentication. [Session management](https://docs.nestjs.com/controllers) to handle authentication routes and [@mridang/nestjs-auth guards](https://www.npmjs.com/package/@mridang/nestjs-auth) to protect routes requiring authentication. [Session management](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) is handled through encrypted [JWT-based sessions](https://docs.nestjs.com/controllers) to handle authentication routes and [@mridang/nestjs-auth guards](https://www.npmjs.com/package/@mridang/nestjs-auth) to protect routes requiring authentication. [Session management](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) is handled through encrypted [JWT-based sessions](https://authjs.dev/concepts/session-strategies#jwt-session) stored in secure, HTTP-only cookies. The example includes automatic [token refresh](https://docs.nestjs.com/controllers) to handle authentication routes and [@mridang/nestjs-auth guards](https://www.npmjs.com/package/@mridang/nestjs-auth) to protect routes requiring authentication. [Session management](https://zitadel.com/docs/guides/integrate/login/oidc/login-users) is handled through encrypted [JWT-based sessions](https://authjs.dev/concepts/session-strategies#jwt-session) stored in secure, HTTP-only cookies. The example includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) functionality using [refresh tokens](https://oauth.net/2/pkce/), ensuring users maintain their sessions without interruption when access tokens expire.
The logout implementation demonstrates [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. [CSRF protection](https://zitadel.com/docs/guides/integrate/login/oidc/logout) by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. [CSRF protection](https://owasp.org/www-community/attacks/csrf) during logout is achieved through a state parameter validated in the callback. The example also showcases accessing Zitadel's [UserInfo endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#userinfo_endpoint) to fetch real-time user data, including [custom claims](https://oauth.net/2/pkce/) with [Zitadel](https://zitadel.com/docs) as the identity provider. Users begin on a public landing page and click a login button to authenticate through Zitadel's authorization server. After successful authentication, they're redirected to a protected profile page displaying their user information retrieved from the [ID token](https://zitadel.com/docs/apis/openidoauth/claims), [roles](https://zitadel.com/docs/guides/integrate/login/oidc/logout) by redirecting users to Zitadel's end-session endpoint, terminating both the local application session and the Zitadel session. [CSRF protection](https://owasp.org/www-community/attacks/csrf) during logout is achieved through a state parameter validated in the callback. The example also showcases accessing Zitadel's [UserInfo endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#userinfo-endpoint) to fetch real-time user data, including [custom claims](https://zitadel.com/docs/apis/openidoauth/claims), [roles](https://zitadel.com/docs/guides/manage/console/roles), and organization membership.
All protected routes are secured using the [@mridang/nestjs-auth global guard](https://www.npmjs.com/package/@mridang/nestjs-auth), with the `@Public()` decorator marking routes that don't require authentication. The application uses [Handlebars templates](https://handlebarsjs.com) for server-side rendering and [Tailwind CSS](https://tailwindcss.com) for styling, providing a complete reference implementation for NestJS developers.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your Zitadel application configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-nestjs).
2. Create a `.env` file in the project root and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use the exact environment variable names from the repository:**
```
NODE_ENV=development
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
SESSION_SALT=your-cryptographic-salt
SESSION_DURATION=3600
ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id_from_console
ZITADEL_CLIENT_SECRET=your_randomly_generated_secret
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual Zitadel instance URL (the **Issuer**)
- The **Client ID** you copied when creating the application
- A randomly generated **Client Secret** (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
- A secure **Session Secret** (generate using the same command)
- A cryptographic **Session Salt** for cookie encryption
- The **redirect URI** you configured in the PKCE setup (must match exactly)
- The **post-logout redirect URI** for the logout callback
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
The application will be running at `http://localhost:3000`. Visit the URL to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Framework docs](https://nestjs.com)
* [Auth library (@auth/core)](https://www.npmjs.com/package/@auth/core)
* [NestJS auth module](https://www.npmjs.com/package/@mridang/nestjs-auth)
* [Example repository](https://github.com/zitadel/example-auth-nestjs)
apps/docs/content/sdk-examples/nextjs.mdx
+83
View File
@@ -0,0 +1,83 @@
---
title: Next.js
sidebar_label: Next.js
framework_url: https://nextjs.org
auth_library: next-auth
auth_library_url: https://next-auth.js.org
example_repo: https://github.com/zitadel/example-auth-nextjs
auth_flow: pkce
status: stable
---
## Overview
[Next.js](https://nextjs.org) is a React framework for building full-stack web applications. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your Next.js application.
#### Auth library
This example uses **[next-auth](https://www.npmjs.com/package/next-auth)** with **[openid-client](https://www.npmjs.com/package/openid-client)** to implement the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manage [PKCE](https://oauth.net/2/pkce/) code challenge generation, perform secure token exchange, and provide session management helpers.
---
## What this example demonstrates
This Next.js application demonstrates a secure authentication flow using Zitadel with the industry-standard [PKCE flow](https://oauth.net/2/pkce/). Users start on a public landing page, initiate login via the Zitadel authorization server, and after successful authentication are redirected back to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).
The application implements session management using NextAuth.js with a JWT-based session strategy. It includes automatic callback handling with secure token exchange, route protection for authenticated-only pages, and an example of requesting additional [OIDC scopes](https://zitadel.com/docs/apis/openidoauth/scopes) (including `offline_access` for refresh tokens and Zitadel-specific scopes for metadata and roles).
The logout flow implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** via the end-session endpoint, terminating both the local session and the Zitadel session before redirecting the user back to the application. It also demonstrates automatic token refresh to maintain long-lived sessions without requiring users to re-authenticate.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/api/auth/callback/zitadel` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/api/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production deployments, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/login-users):
1. Clone the [repository](https://github.com/zitadel/example-auth-nextjs).
2. Create a `.env.local` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). Use these environment variable names exactly as shown:
```
NODE_ENV=development
PORT=3000
SESSION_SECRET=your-very-secret-and-strong-session-key
SESSION_DURATION=3600
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-zitadel-application-client-id
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/api/auth/callback/zitadel
ZITADEL_POST_LOGIN_URL=/profile
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/api/auth/logout/callback
NEXTAUTH_URL=http://localhost:3000
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **ZITADEL_DOMAIN**)
- The **Client ID** you copied when creating the application
- A randomly generated **SESSION_SECRET** using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`
- A randomly generated **ZITADEL_CLIENT_SECRET** (required by Auth.js / NextAuth.js even though PKCE doesn't require it)
- The **redirect URIs** you configured in the PKCE setup (must match exactly)
3. Install dependencies using [npm](https://www.npmjs.com) by running `npm install`, then start the development server with `npm run dev` to verify the authentication flow end-to-end at `http://localhost:3000`.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Next.js documentation](https://nextjs.org)
* [NextAuth.js documentation](https://next-auth.js.org/)
* [Example repository](https://github.com/zitadel/example-auth-nextjs)
apps/docs/content/sdk-examples/nuxtjs.mdx
+85
View File
@@ -0,0 +1,85 @@
---
title: Nuxt.js
sidebar_label: Nuxt.js
framework_url: https://nuxt.com
auth_library: next-auth
auth_library_url: https://next-auth.js.org
example_repo: https://github.com/zitadel/example-auth-nuxtjs
auth_flow: pkce
status: stable
---
## Overview
[Nuxt.js](https://nuxt.com) is the intuitive [Vue.js](https://vuejs.org) framework that enables you to create full-stack web applications with server-side rendering, file-based routing, and auto-imports. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
#### Auth library
This example uses **[@sidebase/nuxt-auth](https://www.npmjs.com/package/@sidebase/nuxt-auth)**, a Nuxt module that wraps **[NextAuth.js/Auth.js](https://next-auth.js.org)** for seamless authentication integration. Under the hood, it leverages **[next-auth](https://www.npmjs.com/package/next-auth)** with the **[openid-client](https://www.npmjs.com/package/openid-client)** library to implement the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manage [PKCE](https://oauth.net/2/pkce/), perform token exchange, and handle [session management](https://authjs.dev/concepts/session-strategies).
---
## What this example demonstrates
This [Nuxt.js](https://nuxt.com) application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with the **[PKCE flow](https://oauth.net/2/pkce/)**. Users begin on a public landing page where they can initiate sign-in with Zitadel through the **[@sidebase/nuxt-auth](https://www.npmjs.com/package/@sidebase/nuxt-auth)** module. After successful authentication, they're redirected to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).
The example implements secure [session management](https://authjs.dev/concepts/session-strategies) using [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) with automatic [token refresh](https://authjs.dev/concepts/session-strategies) using [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) capabilities through [refresh tokens](https://authjs.dev/concepts/session-strategies) using [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) capabilities through [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token). Protected routes automatically redirect unauthenticated users to the sign-in flow using [Nuxt middleware](https://authjs.dev/concepts/session-strategies) using [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) capabilities through [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token). Protected routes automatically redirect unauthenticated users to the sign-in flow using [Nuxt middleware](https://nuxt.com/docs/guide/directory-structure/middleware), ensuring sensitive areas remain secure. The application also includes complete **[federated logout](https://authjs.dev/concepts/session-strategies) using [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) capabilities through [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token). Protected routes automatically redirect unauthenticated users to the sign-in flow using [Nuxt middleware](https://nuxt.com/docs/guide/directory-structure/middleware), ensuring sensitive areas remain secure. The application also includes complete **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** functionality that properly terminates both the local session and the Zitadel session through the [end-session endpoint](https://authjs.dev/concepts/session-strategies) using [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) capabilities through [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token). Protected routes automatically redirect unauthenticated users to the sign-in flow using [Nuxt middleware](https://nuxt.com/docs/guide/directory-structure/middleware), ensuring sensitive areas remain secure. The application also includes complete **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout), redirecting users back to the application with proper CSRF protection using state parameters.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/api/auth/callback/zitadel` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/`)
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the ZITADEL Management Console if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your Zitadel application configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-nuxtjs).
2. Create a `.env` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
PORT=3000
SESSION_DURATION=3600
NUXT_AUTH_SECRET=your-very-secret-and-strong-session-key
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-client-id
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/api/auth/callback/zitadel
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/
AUTH_ORIGIN=http://localhost:3000
```
Replace these values with:
- Your actual Zitadel instance URL (the **Issuer** from your [Zitadel instance settings](https://zitadel.com/docs/guides/manage/console/overview))
- The **Client ID** you copied when creating the application
- A randomly generated **NUXT_AUTH_SECRET** for session encryption (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
- The **callback URI** you configured in the PKCE setup (must match exactly)
- The **post-logout redirect URI** you configured in the PKCE setup
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
The application will be running at `http://localhost:3000` where you can test the complete authentication flow.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Framework docs](https://nuxt.com)
* [@sidebase/nuxt-auth](https://www.npmjs.com/package/@sidebase/nuxt-auth)
* [NextAuth.js/Auth.js](https://next-auth.js.org)
* [Example repository](https://github.com/zitadel/example-auth-nuxtjs)
apps/docs/content/sdk-examples/qwik.mdx
+87
View File
@@ -0,0 +1,87 @@
---
title: Qwik
sidebar_label: Qwik
framework_url: https://qwik.dev
auth_library: "@auth/core"
auth_library_url: https://www.npmjs.com/package/@auth/core
example_repo: https://github.com/zitadel/example-auth-qwik
auth_flow: pkce
status: stable
---
## Overview
[Qwik](https://qwik.dev) is a framework for building resumable web applications with instant-on interactivity and optimal performance. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across the app.
#### Auth library
This example uses **[@auth/qwik](https://www.npmjs.com/package/@auth/qwik)**, a Qwik adapter for **[@auth/core](https://www.npmjs.com/package/@auth/qwik)**, a Qwik adapter for **[@auth/core](https://www.npmjs.com/package/@auth/core)** (formerly Auth.js/NextAuth.js), which implements the [OpenID Connect (OIDC)](https://www.npmjs.com/package/@auth/qwik)**, a Qwik adapter for **[@auth/core](https://www.npmjs.com/package/@auth/core)** (formerly Auth.js/NextAuth.js), which implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://www.npmjs.com/package/@auth/qwik), performs token exchange, and exposes helpers for session state. The core library handles authentication across multiple frameworks and provides secure [token storage](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) with automatic [token refresh](https://www.npmjs.com/package/@auth/qwik)**, a Qwik adapter for **[@auth/core](https://www.npmjs.com/package/@auth/core)** (formerly Auth.js/NextAuth.js), which implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs token exchange, and exposes helpers for session state. The core library handles authentication across multiple frameworks and provides secure [token storage](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) capabilities.
---
## What this example demonstrates
This [Qwik](https://qwik.dev) application showcases a complete authentication implementation using [Zitadel](https://qwik.dev) application showcases a complete authentication implementation using [Zitadel](https://zitadel.com/docs) with the [Authorization Code Flow with PKCE](https://qwik.dev). The example includes secure sign-in functionality that redirects users to Zitadel's hosted login page, handles the OAuth callback to exchange authorization codes for [access tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint), and manages sessions with [JWT tokens](https://qwik.dev) application showcases a complete authentication implementation using [Zitadel](https://zitadel.com/docs) with the [Authorization Code Flow with PKCE](https://oauth.net/2/pkce/). The example includes secure sign-in functionality that redirects users to Zitadel's hosted login page, handles the OAuth callback to exchange authorization codes for [access tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint), and manages sessions with [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-jwt-response) stored in encrypted server-side cookies.
Route protection is implemented using [Qwik City's](https://qwik.dev/docs/qwikcity) `onRequest` handler, which performs server-side authentication checks before rendering protected pages. Unauthenticated users attempting to access secured routes are automatically redirected to the login page with a callback URL to return them to their intended destination after successful authentication. The application displays comprehensive user profile information including standard [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) like name and email, as well as Zitadel-specific claims such as [organization membership](https://zitadel.com/docs/guides/manage/console/organizations) and [project roles](https://zitadel.com/docs/guides/manage/console/projects).
Sign-out functionality implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's end-session endpoint, ensuring that users are logged out from both the application and Zitadel's single sign-on session. The logout process includes [CSRF protection](https://zitadel.com/docs/guides/integrate/login/oidc/logout#csrf-protection) using state parameters validated through secure cookies, followed by proper cleanup of session data and redirection back to the application.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback/zitadel` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/api/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-qwik).
2. Create a `.env.local` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications):
```
VITE_PORT=3000
VITE_SESSION_SECRET=your-very-secret-and-strong-session-key
VITE_SESSION_DURATION=3600
VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
VITE_ZITADEL_CLIENT_ID=your_client_id_from_console
VITE_ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
VITE_ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback/zitadel
VITE_ZITADEL_POST_LOGOUT_URL=http://localhost:3000/api/auth/logout/callback
```
Replace these values with:
- Your actual Zitadel instance URL (the **Issuer** from your [application settings](https://zitadel.com/docs/guides/integrate/login/oidc/login-users))
- The **Client ID** you copied when creating the application
- A randomly generated session secret (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
- A randomly generated client secret value (Auth.js requires this for internal configuration)
- The **redirect URI** you configured in the PKCE setup (must match exactly)
- The **post-logout redirect URI** you configured (must match exactly)
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
The application will be available at `http://localhost:3000`.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Framework docs](https://qwik.dev)
* [Auth library (@auth/core)](https://www.npmjs.com/package/@auth/core)
* [Qwik adapter (@auth/qwik)](https://www.npmjs.com/package/@auth/qwik)
* [Example repository](https://github.com/zitadel/example-auth-qwik)
apps/docs/content/sdk-examples/react.mdx
+84
View File
@@ -0,0 +1,84 @@
---
title: React
sidebar_label: React
framework_url: https://react.dev
auth_library: oidc-client-ts
auth_library_url: https://www.npmjs.com/package/oidc-client-ts
example_repo: https://github.com/zitadel/example-auth-react
auth_flow: pkce
status: stable
---
## Overview
[React](https://react.dev) is a JavaScript library for building user interfaces with component composition, declarative views, and a rich ecosystem. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your React application.
#### Auth library
This example uses **[react-oidc-context](https://www.npmjs.com/package/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**. The underlying [oidc-client-ts](https://www.npmjs.com/package/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) library implements the [OpenID Connect (OIDC)](https://www.npmjs.com/package/react-oidc-context)**, a React wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**. The underlying [oidc-client-ts](https://github.com/authts/oidc-client-ts) library implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manages [PKCE](https://www.npmjs.com/package/react-oidc-context) code challenge generation, performs secure [token exchange](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint), and exposes React hooks for managing authentication state throughout your application.
---
## What this example demonstrates
This [React](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://react.dev) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/pkce/) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://www.npmjs.com/package/react-oidc-context), which redirects them to [Zitadel's authorization endpoint](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/pkce/) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://www.npmjs.com/package/react-oidc-context), which redirects them to [Zitadel's authorization endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints) for authentication. After successful authentication, the application handles the OAuth callback, exchanges the authorization code for [access tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint), and establishes a secure [session](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/pkce/) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://www.npmjs.com/package/react-oidc-context), which redirects them to [Zitadel's authorization endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints).
Protected routes are secured using [react-oidc-context's](https://react.dev) application showcases a complete authentication flow using [Zitadel](https://zitadel.com/docs) with the secure [PKCE](https://oauth.net/2/pkce/) standard. Users begin on a public landing page where they can initiate login through [react-oidc-context](https://www.npmjs.com/package/react-oidc-context) `withAuthenticationRequired` higher-order component, which automatically redirects unauthenticated users to the login flow. The profile page displays user information retrieved from [OIDC claims](https://www.npmjs.com/package/react-oidc-context) `withAuthenticationRequired` higher-order component, which automatically redirects unauthenticated users to the login flow. The profile page displays user information retrieved from [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims), including profile details, email, and metadata. The application implements complete [federated logout](https://www.npmjs.com/package/react-oidc-context) `withAuthenticationRequired` higher-order component, which automatically redirects unauthenticated users to the login flow. The profile page displays user information retrieved from [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims), including profile details, email, and metadata. The application implements complete [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) functionality, properly terminating both the local session and the Zitadel session through the end-session endpoint.
The example leverages [React Router](https://reactrouter.com) for client-side navigation and [Vite](https://reactrouter.com) for client-side navigation and [Vite](https://vite.dev) as the build tool, demonstrating modern React development patterns with [TypeScript](https://reactrouter.com) for client-side navigation and [Vite](https://vite.dev) as the build tool, demonstrating modern React development patterns with [TypeScript](https://www.typescriptlang.org). All authentication state management, including [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) with offline access, is handled automatically by the [oidc-client-ts](https://reactrouter.com) for client-side navigation and [Vite](https://vite.dev) as the build tool, demonstrating modern React development patterns with [TypeScript](https://www.typescriptlang.org). All authentication state management, including [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) with offline access, is handled automatically by the [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) library under the hood.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/`)
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your Zitadel application configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-react).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
VITE_ZITADEL_CLIENT_ID=your_client_id_from_console
VITE_ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
VITE_ZITADEL_POST_LOGOUT_URL=http://localhost:3000/
VITE_POST_LOGIN_URL=/profile
VITE_PORT=3000
```
Replace these values with:
- Your actual Zitadel instance URL (the **Issuer** from your [Zitadel application settings](https://zitadel.com/docs/guides/integrate/login/oidc/login-users))
- The **Client ID** you copied when creating the application
- The **redirect URI** you configured in the PKCE setup (must match exactly)
- The **post-logout redirect URI** you configured
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
The application will be running at `http://localhost:3000` where you can test the complete authentication flow.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [React documentation](https://react.dev)
* [react-oidc-context](https://www.npmjs.com/package/react-oidc-context)
* [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)
* [React Router](https://reactrouter.com)
* [Example repository](https://github.com/zitadel/example-auth-react)
apps/docs/content/sdk-examples/solidstart.mdx
+87
View File
@@ -0,0 +1,87 @@
---
title: SolidStart
sidebar_label: SolidStart
framework_url: https://start.solidjs.com
auth_library: "@auth/core"
auth_library_url: https://www.npmjs.com/package/@auth/core
example_repo: https://github.com/zitadel/example-auth-solidstart
auth_flow: pkce
status: stable
---
## Overview
[SolidStart](https://start.solidjs.com) is a full-stack web framework built on top of [SolidJS](https://solidjs.com) that enables you to create performant web applications with a modern development experience. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain [sessions](https://authjs.dev/concepts/session-strategies) across the app.
#### Auth library
This example uses **[@auth/solid-start](https://www.npmjs.com/package/@auth/solid-start)**, the SolidStart adapter for [Auth.js](https://authjs.dev), which builds on **[@auth/core](https://www.npmjs.com/package/@auth/core)**. Auth.js implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow, manages [PKCE](https://oauth.net/2/pkce/), performs [token exchange](https://zitadel.com/docs/apis/openidoauth/grant-types), and exposes helpers for [session state](https://authjs.dev/concepts/session-strategies). The example also uses **[openid-client](https://www.npmjs.com/package/openid-client)** ([GitHub](https://github.com/panva/node-openid-client)) for manual token refresh operations and logout URL construction.
---
## What this example demonstrates
This example shows a complete authentication implementation using [SolidStart](https://start.solidjs.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page and click a login button to authenticate with Zitadel using the secure **[PKCE flow](https://oauth.net/2/pkce/)**. The [Auth.js](https://authjs.dev) library handles the [OAuth 2.0](https://zitadel.com/docs/guides/integrate/login/oidc/oauth-recommended-flows) authorization code exchange and manages secure [session storage](https://authjs.dev/concepts/session-strategies) using encrypted [JWT tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint). After successful authentication, users are redirected to a protected profile page displaying their user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) like name, email, and custom [Zitadel metadata](https://zitadel.com/docs/apis/openidoauth/claims#reserved-claims).
The application implements automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. When an [access token](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) expires, the refresh logic seamlessly exchanges the [refresh token](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) for new tokens in the background. [Route protection](https://start.solidjs.com/api/createAsync) is implemented using [SolidStart's server functions](https://start.solidjs.com/api/server$), ensuring only authenticated users can access sensitive areas. The logout flow implements [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout) with CSRF protection using state parameters, properly terminating both the local session and the Zitadel session before redirecting users back to the application.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/api/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-solidstart).
2. Create a `.env` file and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). Use the exact environment variable names from the repository:
```
NODE_ENV=development
PORT=3000
SESSION_SECRET="your-very-secret-and-strong-session-key"
SESSION_DURATION=3600
ZITADEL_DOMAIN="https://your-zitadel-domain"
ZITADEL_CLIENT_ID="your-client-id"
ZITADEL_CLIENT_SECRET="your-randomly-generated-client-secret"
ZITADEL_CALLBACK_URL="http://localhost:3000/auth/callback"
ZITADEL_POST_LOGIN_URL="/profile"
ZITADEL_POST_LOGOUT_URL="http://localhost:3000/api/auth/logout/callback"
NEXTAUTH_URL="http://localhost:3000"
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **Issuer**)
- The **Client ID** you copied when creating the application
- The **redirect URIs** you configured in the PKCE setup (must match exactly)
- A secure random string for `SESSION_SECRET` (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
- A secure random string for `ZITADEL_CLIENT_SECRET` for [Auth.js](https://authjs.dev) configuration compatibility
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server to verify the authentication flow end-to-end:
```bash
npm install
npm run dev
```
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [SolidStart documentation](https://start.solidjs.com)
* [Auth.js documentation](https://authjs.dev)
* [@auth/solid-start](https://www.npmjs.com/package/@auth/solid-start)
* [@auth/core](https://www.npmjs.com/package/@auth/core)
* [openid-client](https://www.npmjs.com/package/openid-client)
* [Example repository](https://github.com/zitadel/example-auth-solidstart)
apps/docs/content/sdk-examples/spring.mdx
+107
View File
@@ -0,0 +1,107 @@
---
title: Spring Boot
sidebar_label: Spring Boot
framework_url: https://spring.io/projects/spring-boot
auth_library: "Spring Security"
auth_library_url: https://spring.io/projects/spring-security
example_repo: https://github.com/zitadel/example-auth-spring
auth_flow: pkce
status: stable
---
## Overview
[Spring Boot](https://spring.io/projects/spring-boot) is a powerful, production-ready framework for building Java applications. This example shows how to integrate **Zitadel** into a Spring Boot web application using **OpenID Connect (OIDC)** and the **Authorization Code Flow + PKCE**.
It demonstrates a common web app pattern: users start on a public landing page, authenticate with Zitadel via a login button, and are then redirected to a protected profile page that displays user information. Logout is also implemented to end both the local session and the Zitadel session.
#### Auth library
This example uses **[Spring Security](https://spring.io/projects/spring-security)**, the standard framework for authentication and access control in Spring applications. Spring Security supports OIDC natively and manages the PKCE flow for you.
---
## What this example demonstrates
This example shows a complete authentication implementation using Spring Security’s OAuth 2.0 / OIDC support:
- **Public landing page** (`/`) accessible without authentication.
- **Sign-in with Zitadel** via Spring Security’s OAuth2 login entrypoint.
- **Route protection** so authenticated access is required for protected routes (e.g. `/profile`).
- **Profile page** that renders the authenticated user’s OIDC claims.
- **Server-side session management** handled by the servlet container + Spring Security.
- **Federated logout** that clears the local session and triggers RP-initiated logout against Zitadel, returning the user to a post-logout callback route.
---
## Getting started
### Prerequisites
Before you begin, ensure you have the following:
#### System Requirements
- Java Development Kit (JDK) 17 or later
- Maven (or use the included `mvnw` wrapper)
#### Account Setup
You’ll need a Zitadel account and an application configured for a Web app using Authorization Code + PKCE.
> **Important:** Configure the following URLs in your Zitadel application settings:
>
> - **Redirect URIs:** `http://localhost:3000/auth/callback`
> - **Post Logout Redirect URIs:** `http://localhost:3000/auth/logout/callback`
>
> These URLs must exactly match what your Spring Boot application uses. For production, add your production URLs.
### Run the example
1. Clone the repository.
2. Copy `.env.example` to `.env` and fill in your Zitadel details.
```dotenv
# Port number where your Spring Boot server will listen for incoming HTTP requests.
PORT=3000
# Session timeout in seconds. Users will be automatically logged out after this
# duration of inactivity. 3600 seconds = 1 hour.
SESSION_DURATION=3600
# Your Zitadel instance domain URL. Include the full https:// URL.
ZITADEL_DOMAIN="https://your-zitadel-domain"
# Application Client ID from your Zitadel application settings.
ZITADEL_CLIENT_ID="your-client-id"
# Provide a randomly generated string here.
ZITADEL_CLIENT_SECRET="your-randomly-generated-client-secret"
```
3. Build and start the server:
```bash
# 1. Clone the repository
git clone [email protected]:zitadel/example-auth-spring.git
cd example-auth-spring
# 2. Build the project and download dependencies
mvn clean install
# 3. Start the development server
mvn spring-boot:run
```
4. Open `http://localhost:3000` and walk through login → profile → logout.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Spring Boot documentation](https://spring.io/projects/spring-boot)
* [Spring Security documentation](https://spring.io/projects/spring-security)
* [Example repository](https://github.com/zitadel/example-auth-spring)
apps/docs/content/sdk-examples/sveltekit.mdx
+86
View File
@@ -0,0 +1,86 @@
---
title: SvelteKit
sidebar_label: SvelteKit
framework_url: https://kit.svelte.dev
auth_library: "@auth/core"
auth_library_url: https://www.npmjs.com/package/@auth/core
example_repo: https://github.com/zitadel/example-auth-sveltekit
auth_flow: pkce
status: stable
---
## Overview
[SvelteKit](https://kit.svelte.dev) is a framework for building web applications with flexible filesystem-based routing and a unified approach to server-side and client-side logic. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
#### Auth library
This example uses **[@auth/sveltekit](https://www.npmjs.com/package/@auth/sveltekit)**, the SvelteKit integration of **[@auth/core](https://www.npmjs.com/package/@auth/core)** (formerly NextAuth.js). Auth.js provides a complete authentication solution that handles the [OpenID Connect](https://zitadel.com/docs/apis/openidoauth/endpoints) protocol, manages [PKCE](https://oauth.net/2/pkce/) code generation and verification, performs secure token exchange, and provides session management utilities across your SvelteKit application.
---
## What this example demonstrates
This example provides a complete authentication implementation showing how to secure a [SvelteKit](https://kit.svelte.dev) application with [Zitadel](https://zitadel.com/docs). Users start on a public landing page and click a login button to authenticate through Zitadel's [authorization server](https://zitadel.com/docs/apis/openidoauth/endpoints) using the **[PKCE flow](https://oauth.net/2/pkce/)**. After successful authentication, they're redirected to a protected profile page that displays their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).
The example demonstrates route protection using [SvelteKit's server-side load functions](https://kit.svelte.dev/docs/load) that verify [session state](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) before rendering protected pages. Authentication state is managed through [@auth/sveltekit hooks](https://kit.svelte.dev/docs/load) that verify [session state](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) before rendering protected pages. Authentication state is managed through [@auth/sveltekit hooks](https://www.npmjs.com/package/@auth/sveltekit), which integrate with [SvelteKit's hooks system](https://kit.svelte.dev/docs/load) that verify [session state](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) before rendering protected pages. Authentication state is managed through [@auth/sveltekit hooks](https://www.npmjs.com/package/@auth/sveltekit), which integrate with [SvelteKit's hooks system](https://kit.svelte.dev/docs/hooks) to provide session data throughout your application. The implementation includes automatic [access token refresh](https://kit.svelte.dev/docs/load) that verify [session state](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) before rendering protected pages. Authentication state is managed through [@auth/sveltekit hooks](https://www.npmjs.com/package/@auth/sveltekit), which integrate with [SvelteKit's hooks system](https://kit.svelte.dev/docs/hooks) to provide session data throughout your application. The implementation includes automatic [access token refresh](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate.
The logout flow implements **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** with proper CSRF protection, terminating both the local application session and the Zitadel session before redirecting users back to your application. Custom error pages provide user-friendly messages for authentication failures, and the example includes comprehensive security headers configured through [SvelteKit's hooks](https://kit.svelte.dev/docs/hooks).
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your Zitadel application configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-sveltekit).
2. Create a `.env.local` file in the project root and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
SESSION_SECRET=your-very-secret-and-strong-session-key
SESSION_DURATION=3600
ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
ZITADEL_CLIENT_ID=your_client_id_from_console
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
NEXTAUTH_URL=http://localhost:3000
```
Replace these values with:
- A secure random string for `SESSION_SECRET` (generate using: `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`)
- Your actual Zitadel instance URL for `ZITADEL_DOMAIN` (the issuer URL)
- The **Client ID** you copied when creating the application
- A random string for `ZITADEL_CLIENT_SECRET` (Auth.js requires this even though PKCE doesn't strictly need it)
- The **redirect URI** you configured in the PKCE setup (must match exactly)
- The **post-logout redirect URI** you configured
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
4. Navigate to `http://localhost:3000` to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [SvelteKit documentation](https://kit.svelte.dev)
* [Auth.js (SvelteKit)](https://www.npmjs.com/package/@auth/sveltekit)
* [Auth.js Core](https://www.npmjs.com/package/@auth/core)
* [Example repository](https://github.com/zitadel/example-auth-sveltekit)
apps/docs/content/sdk-examples/symfony.mdx
+79
View File
@@ -0,0 +1,79 @@
---
title: Symfony
sidebar_label: Symfony
framework_url: https://symfony.com
auth_library: "Symfony Security"
auth_library_url: https://symfony.com/doc/current/security.html
example_repo: https://github.com/zitadel/example-auth-symfony
auth_flow: pkce
status: stable
---
## Overview
[Symfony](https://symfony.com) is a set of reusable PHP components and a PHP framework for web projects. It provides a robust set of features for web applications, making it one of the most popular choices for building server-side applications. This example demonstrates how to integrate **[Zitadel](https://zitadel.com/docs)** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your application.
#### Auth library
This example uses **[Symfony Security](https://symfony.com/doc/current/security.html)**, the standard authentication component for Symfony applications. Symfony Security implements the [OpenID Connect (OIDC)](https://zitadel.com/docs/apis/openidoauth/endpoints) flow through a custom authenticator, manages [PKCE](https://oauth.net/2/pkce/), performs secure token exchange, and provides session management through Symfony's firewall system.
---
## What this example demonstrates
This example shows a complete authentication implementation using [Symfony](https://symfony.com) with [Zitadel](https://zitadel.com/docs). Users start on a public landing page, click a login button to authenticate with Zitadel using the secure [PKCE flow](https://oauth.net/2/pkce/), and are redirected to a protected profile page displaying their [user information](https://zitadel.com/docs/apis/openidoauth/claims) after successful authentication.
The application implements server-side session management with Symfony's security system, storing authentication state securely through the framework's user provider pattern. Protected routes use Symfony Security's firewall configuration to automatically redirect unauthenticated users to the sign-in flow, ensuring only authenticated users can access sensitive areas. The profile page displays comprehensive user information including [OIDC claims](https://zitadel.com/docs/apis/openidoauth/claims) and [session metadata](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint).
The application demonstrates proper **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** by terminating sessions both locally and with Zitadel's [end-session endpoint](https://zitadel.com/docs/guides/integrate/login/oidc/logout), complete with CSRF protection using state parameters. Additionally, it includes automatic [token refresh](https://zitadel.com/docs/apis/openidoauth/endpoints) using [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) to maintain long-lived sessions without requiring users to re-authenticate. The example uses [Zitadel-specific scopes](https://zitadel.com/docs/apis/openidoauth/scopes) like `urn:zitadel:iam:user:metadata` and `urn:zitadel:iam:org:projects:roles` to access extended user attributes and role information for implementing [role-based access control (RBAC)](https://zitadel.com/docs/guides/manage/console/roles).
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs (e.g., `http://localhost:3000/auth/logout/callback`)
5. Copy your **Client ID** for use in the next steps
6. Optionally enable [refresh tokens](https://zitadel.com/docs/apis/openidoauth/grant-types#refresh-token) in Token Settings for long-lived sessions
> **Note:** Make sure to enable **Dev Mode** in the [Zitadel Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications) configured:
1. Clone the [repository](https://github.com/zitadel/example-auth-symfony).
2. Create a `.env` file (copy from `.env.example`) and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications). **Use these exact environment variable names:**
```
APP_SECRET=your-app-secret-key
SERVER_URL=http://localhost:3000
SERVER_PORT=3000
ZITADEL_DOMAIN=https://your-zitadel-domain
ZITADEL_CLIENT_ID=your-zitadel-application-client-id
ZITADEL_CLIENT_SECRET=your-randomly-generated-client-secret
ZITADEL_POST_LOGOUT_URL=http://localhost:3000/auth/logout/callback
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) for `ZITADEL_DOMAIN` (the issuer)
- The **Client ID** you copied when creating the application for `ZITADEL_CLIENT_ID`
- The **post-logout redirect URI** for `ZITADEL_POST_LOGOUT_URL`
- A strong random string for `APP_SECRET` (generate using: `php -r "echo bin2hex(random_bytes(32));"`)
- A randomly generated string for `ZITADEL_CLIENT_SECRET` (generate using: `php -r "echo bin2hex(random_bytes(32));"`)
3. Install dependencies using [Composer](https://getcomposer.org) with `composer install` and start the development server with `composer run dev` to verify the authentication flow end-to-end.
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Symfony documentation](https://symfony.com/doc)
* [Symfony Security documentation](https://symfony.com/doc/current/security.html)
* [Example repository](https://github.com/zitadel/example-auth-symfony)
apps/docs/content/sdk-examples/vue.mdx
+82
View File
@@ -0,0 +1,82 @@
---
title: Vue.js
sidebar_label: Vue.js
framework_url: https://vuejs.org
auth_library: oidc-client-ts
auth_library_url: https://www.npmjs.com/package/oidc-client-ts
example_repo: https://github.com/zitadel/example-auth-vuejs
auth_flow: pkce
status: stable
---
## Overview
[Vue.js](https://vuejs.org) is a progressive JavaScript framework for building user interfaces with reactive data binding, component composition, and a rich ecosystem. This example demonstrates how to integrate **Zitadel** using the **[OAuth 2.0 PKCE flow](https://oauth.net/2/pkce/)** to authenticate users securely and maintain sessions across your Vue.js application.
#### Auth library
This example uses **[vue-oidc-context](https://www.npmjs.com/package/vue-oidc-context)**, a Vue 3 wrapper around **[oidc-client-ts](https://www.npmjs.com/package/vue-oidc-context)**, a Vue 3 wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)**, which implements the [OpenID Connect](https://www.npmjs.com/package/vue-oidc-context) (OIDC) flow. The underlying [oidc-client-ts](https://www.npmjs.com/package/vue-oidc-context)**, a Vue 3 wrapper around **[oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts) library manages [PKCE](https://www.npmjs.com/package/vue-oidc-context), performs token exchange, and exposes helpers for [session state](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) management.
---
## What this example demonstrates
This [Vue.js](https://vuejs.org) application showcases a complete authentication pattern using [Zitadel](https://zitadel.com/docs) with [PKCE](https://oauth.net/2/pkce/). Users begin on a public landing page where they can initiate sign-in with Zitadel's authorization server. After successful authentication, the app handles the [OAuth callback](https://zitadel.com/docs/apis/openidoauth/endpoints) and redirects users to a protected profile page displaying their [user information and claims](https://zitadel.com/docs/apis/openidoauth/claims).
The application uses [vue-oidc-context](https://www.npmjs.com/package/vue-oidc-context) to wrap authentication logic around [Vue Router](https://www.npmjs.com/package/vue-oidc-context) to wrap authentication logic around [Vue Router](https://router.vuejs.org) navigation guards, automatically protecting routes and ensuring only authenticated users can access sensitive areas. The [withAuthenticationRequired](https://www.npmjs.com/package/vue-oidc-context) to wrap authentication logic around [Vue Router](https://router.vuejs.org) navigation guards, automatically protecting routes and ensuring only authenticated users can access sensitive areas. The [withAuthenticationRequired](https://github.com/authts/vue-oidc-context#protecting-routes) higher-order component secures individual routes by checking [session state](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) before rendering protected views.
The example includes secure sign-out functionality implementing **[federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's [end-session endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#end_session_endpoint), which terminates both the local application session and the Zitadel session. The app demonstrates proper handling of [refresh tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token_endpoint) using the `offline_access` [scope](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's [end-session endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#end-session-endpoint), which terminates both the local application session and the Zitadel session. The app demonstrates proper handling of [refresh tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) using the `offline_access` [scope](https://zitadel.com/docs/apis/openidoauth/scopes), and includes comprehensive [error handling](https://zitadel.com/docs/guides/integrate/login/oidc/logout)** through Zitadel's [end-session endpoint](https://zitadel.com/docs/apis/openidoauth/endpoints#end-session-endpoint), which terminates both the local application session and the Zitadel session. The app demonstrates proper handling of [refresh tokens](https://zitadel.com/docs/apis/openidoauth/endpoints#token-endpoint) using the `offline_access` [scope](https://zitadel.com/docs/apis/openidoauth/scopes), and includes comprehensive [error handling](https://github.com/authts/vue-oidc-context#error-handling) for authentication failures.
---
## Getting started
### Prerequisites
Before running this example, you need to create and configure a PKCE application in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview). Follow the PKCE application setup guide to:
1. Create a new Web application in your [Zitadel project](https://zitadel.com/docs/guides/manage/console/projects)
2. Configure it to use the PKCE authentication method
3. Set up your redirect URIs (e.g., `http://localhost:3000/auth/callback` for development)
4. Configure post-logout redirect URIs
5. Copy your **Client ID** for use in the next steps
> **Note:** Make sure to enable **Dev Mode** in the [ZITADEL Management Console](https://zitadel.com/docs/guides/manage/console/overview) if you're using HTTP URLs during local development. For production, always use HTTPS URLs and disable Dev Mode.
### Run the example
Once you have your [Zitadel application configured](https://zitadel.com/docs/guides/integrate/login/oidc/login-users), follow these steps:
1. Clone the [repository](https://github.com/zitadel/example-auth-vuejs).
2. Create a `.env` file in the project root and configure it with the values from your [Zitadel application](https://zitadel.com/docs/guides/manage/console/applications):
```
VITE_ZITADEL_DOMAIN=https://your-instance.zitadel.cloud
VITE_ZITADEL_CLIENT_ID=your_client_id_from_console
VITE_ZITADEL_CALLBACK_URL=http://localhost:3000/auth/callback
VITE_ZITADEL_POST_LOGOUT_URL=http://localhost:3000
VITE_POST_LOGIN_URL=/profile
```
Replace these values with:
- Your actual [Zitadel instance URL](https://zitadel.com/docs/guides/manage/console/default-settings) (the **Issuer**)
- The **Client ID** you copied when creating the application in the PKCE setup
- The **redirect URI** you configured (must match exactly)
- The **post-logout redirect URI** for [federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
3. Install dependencies using [npm](https://www.npmjs.com) and start the development server:
```bash
npm install
npm run dev
```
---
## Learn more and resources
* [PKCE concept](https://oauth.net/2/pkce/)
* [Federated logout](https://zitadel.com/docs/guides/integrate/login/oidc/logout)
* [OIDC integration guide](https://zitadel.com/docs/guides/integrate/login/oidc/login-users)
* [Vue.js documentation](https://vuejs.org)
* [Vue Router documentation](https://router.vuejs.org)
* [vue-oidc-context (wrapper)](https://www.npmjs.com/package/vue-oidc-context)
* [oidc-client-ts (primary library)](https://www.npmjs.com/package/oidc-client-ts)
* [oidc-client-ts GitHub](https://github.com/authts/oidc-client-ts)
* [Example repository](https://github.com/zitadel/example-auth-vuejs)