andwati/zitadel
1
0
Fork 0
mirror of https://github.com/andwati/zitadel.git synced 2026-11-13 09:25:12 +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/guides/manage/cloud/billing.mdx
+52
View File
@@ -0,0 +1,52 @@
---
title: Billing
---
## Billing
In the billing page shows your configured payment methods and the invoice
![](../../../../public/img/manuals/portal/customer_portal_billing.png)
### Payment Method
If you click on the "+" Button a popup will be shown with the needed fields to add a new payment method.
At the moment we provide only "Credit Card" payment
Once a payment method is configured, it can be selected directly in the instance creation process.
## Customer
To be able to create correct billings we will need some customer information from you.
This includes the following fields:
- Name
- Country
- Email address
- Address line 1
- Address line 2
- Postal Code
- City
## Tax ID
If available, enter your tax ID type and VAT number.
The tax ID will be shown on the invoice.
<Callout title="Reverse Charge">
When you enter the tax ID we will automatically calculate taxability.
Depending on your billing address we will mark the invoice as reverse charge.
</Callout>
## Update Billing Information
You will only need to add billing information if your want to get the pro tier. There are two options on how to add your billing info.
1. Go to the billing menu and add a new payment method.
2. Add the billing information directly during the upgrade process.
## Invoices
We show all you invoices, and you are able to download them directly in the Customer Portal.
![](../../../../public/img/manuals/portal/customer_portal_invoices.png)
apps/docs/content/guides/manage/cloud/egress.mdx
+48
View File
@@ -0,0 +1,48 @@
---
title: ZITADEL Cloud Egress IP Addresses
sidebar_label: Egress IPs
description: A list of static IP addresses ZITADEL Cloud uses to make outbound connections to your services.
---
When configuring your firewall or network security groups, you may need to allow traffic **from** ZITADEL Cloud to your internal infrastructure.
This page lists the static Egress (outgoing) IP addresses used by ZITADEL Cloud regions.
## When do I need this?
You need to allowlist these IP addresses if you use features where ZITADEL initiates a connection to your systems. This is commonly required for the following scenarios:
### [Identity Providers & Federation](/guides/integrate/identity-providers/introduction)
If you are federating an external Identity Provider (IdP) that sits behind a firewall:
* **LDAP / Active Directory:** When ZITADEL connects to your LDAP server (typically port `636` for LDAPS).
* **OIDC / OAuth:** When ZITADEL connects to your IdP for:
* **Discovery:** Fetching configuration from `/.well-known/openid-configuration`.
* **Token Exchange:** Exchanging the authorization code at the `token_endpoint`.
* **User Info:** Retrieving user details from the `userinfo_endpoint`.
* **Keys:** Fetching signing keys from the `jwks_uri`.
* **SAML:** If ZITADEL needs to fetch the `metadata.xml` or artifact resolution services from an internal SAML IdP.
### [Notification Providers](/guides/manage/customize/notification-providers)
* [**SMTP:**](/guides/manage/customize/notification-providers#smtp-providers) If you configured a custom SMTP sender pointing to your own mail server.
* [**Webhook / HTTP provider:**](/guides/manage/customize/notification-providers#webhook-http-provider) If you use a custom gateway for SMS or Emails.
### Custom Logic
* **[Actions V1](/concepts/features/actions)**
* **[Actions V2](/concepts/features/actions_v2)**
## IP Addresses by Region
We recommend allowing the IP address corresponding to the region where your ZITADEL instance is hosted.
| Region | Egress IP Address |
| :--- | :--- |
| **Switzerland** | `34.65.158.196` |
| **Europe** | `34.107.19.72` |
| **United States** | `34.69.146.246` |
| **Australia** | `34.87.243.23` |
<Callout type="info">
To find out which region your ZITADEL Cloud instance is running in, check the [ZITADEL Customer Portal](https://zitadel.com/admin/instances).
</Callout>
apps/docs/content/guides/manage/cloud/instances.mdx
+91
View File
@@ -0,0 +1,91 @@
---
title: ZITADEL Instances
sidebar_label: Instances
---
The ZITADEL Customer Portal is used to manage all your different ZITADEL instances.
Instances are containers for your organizations, users and projects.
A recommended setup could look like the following:
1. Instance: "Dev Environment"
2. Instance: "Test Environment"
3. Instance: "Prod Environment"
In the free subscription model you have one instance included.
To be able to add more instances please upgrade to "ZITADEL Pro".
## Overview
The overview shows all the instances that are registered for your customer.
You can directly see the Custom Domain and data region.
With a click on an instance you get to the detail of the chosen instance.
![](../../../../public/img/manuals/portal/customer_portal_instance_overview.png)
## New instance
Click on the new button above the instance table to create a new instance.
1. Enter the name of your new instance
2. Add the credentials for your first administrator
- Username (prefilled)
- Password
3. Instance created! You can now see the details of your first instance.
<Callout type="info">
Every new instance gets a generated domain of the form [instancename][randomnumber].zitadel.cloud
</Callout>
![](../../../../public/img/manuals/portal/customer_portal_new_instance.gif)
## Detail
The detail shows you general information about your instance, the region and your usage.
![](../../../../public/img/manuals/portal/customer_portal_instance_detail.png)
### Upgrade to Pro
Your first instance is included in the free subscription.
As soon as you want to create your second instance or use a "pro" feature like choosing the region, you will have to upgrade to the Pro subscription.
To upgrade you must enter your billing information.
If you hit a limit from the free tier you will automatically be asked to add your credit card information and to subscribe to the pro tier.
You can also upgrade manually at any time.
1. Click the "Upgrade to PRO" button in the menu or go to the billing menu
2. If you choose the billing menu, you can now see your Free plan, click "Upgrade to Pro"
4. Add the missing data
- Payment method: Credit Card Information
- Customer: At least you have to fill the country
5. Save the information
![](../../../../public/img/manuals/portal/customer_portal_upgrade_tier.png)
### Add Custom Domain
We recommend register a Custom Domain to access your ZITADEL instance.
The primary Custom Domain of your ZITADEL instance will be the issuer of the instance. All other Custom Domains can be used to access the instance itself
1. Browse to the "Custom Domains" Tab
2. Click **Add Custom Domain**
3. Enter the domain you want and select the instance where the domain should belong to
4. In the next screen you will get all the information you will have to add to your DNS provider to verify your domain
> **_Please note:_** Do not delete the verification code, as ZITADEL Customer Portal will re-check the ownership of your domain from time to time
Be aware that it has some impacts if you change the primary domain of your instance.
1. The urls and issuer have to change in your app
2. Passkey authentication is based on the domain, if you change it, your users will not be able to login with the registered passkey authentication
![Add Custom Domain](../../../../public/img/manuals/portal/customer_portal_add_domain.png)
#### Verify Custom Domain
As soon as you have added your Custom Domain you will have to verify it, by adding a CNAME record to your DNS provider.
1. Go to your DNS provider
2. Add a new CNAME record (You can find the target on the detail page of your instance)
3. After adding the CNAME you need to wait till the domain is verified (this can take some time)
You will now be able to use the added Custom Domain to access your ZITADEL instance
apps/docs/content/guides/manage/cloud/overview/index.mdx
+19
View File
@@ -0,0 +1,19 @@
---
title: "Overview"
description: "Our customer portal is used to manage all your ZITADEL instances. You can also manage your subscriptions, billing, newsletters and support requests."
---
{/* THIS FILE IS AUTO-GENERATED FROM SIDEBAR-DATA.
ANY MANUAL CHANGES WILL BE OVERWRITTEN.
*/}
import { Card, Cards } from 'fumadocs-ui/components/card';
import { FileText, Folder, Link as LinkIcon } from 'lucide-react';
<Cards>
<Card title="Start" href="/guides/manage/cloud/start" icon={<FileText />} />
<Card title="Instances" href="/guides/manage/cloud/instances" icon={<FileText />} />
<Card title="Settings" href="/guides/manage/cloud/settings" icon={<FileText />} />
<Card title="Billing" href="/guides/manage/cloud/billing" icon={<FileText />} />
<Card title="Users" href="/guides/manage/cloud/users" icon={<FileText />} />
</Cards>
apps/docs/content/guides/manage/cloud/settings.mdx
+44
View File
@@ -0,0 +1,44 @@
---
title: Settings
---
In the settings you can change your team name, notification settings and delete your team.
![](../../../../public/img/manuals/portal/customer_portal_settings_general.png)
## Team name
Change your ZITADEL Cloud team name by entering a new name.
Confirm the changes by clicking the Change button.
## Notifications and newsletters
You can subscribe and unsubscribe to notifications and newsletters:
- Onboarding: Welcome information for new users
- Newsletter: Regular newsletter on ZITADEL
- Product News: Receive product updates
- Security: Receive notifications related to security issues
<Callout title="Technical Advisories">
If you want to stay up to date on our technical advisories, we recommend [subscribing here to the mailing list](/support/technical_advisory#subscribe-to-our-mailing-list).
Technical advisories are notices that report major issues with ZITADEL Self-Hosted or the ZITADEL Cloud platform that could potentially impact security or stability in production environments.
</Callout>
You can also manage your subscriptions by clicking the unsubscribe link in the emails.
<Callout title="Mandatory Information">
We are required to inform you about changes to the terms of service or based on regulatory requirements. You can't unsubscribe to these notifications.
</Callout>
## Delete team
Permanently delete your ZITADEL Cloud account.
This will delete your team and delete all associated information.
Click **Delete Account** and confirm the next step.
## Update billing information
Refer to the [billing guide](./billing).
apps/docs/content/guides/manage/cloud/start.mdx
+25
View File
@@ -0,0 +1,25 @@
---
title: Getting Started with ZITADEL
sidebar_label: Getting Started
---
If you are new to ZITADEL your first action is to create your first ZITADEL instance and an account to access the ZITADEL Customer Portal.
The ZITADEL customer Portal is used to manage all your different ZITADEL instances.
You can also manage your subscriptions, billing, newsletters and support requests.
Go to [ZITADEL Customer Portal](https://zitadel.com) and start by entering you email or use an existing account like Google.
![](../../../../public/img/manuals/portal/customer_portal_landing_page.png)
In a second step fill out your user data like First-, Last- and Team-name.
![](../../../../public/img/manuals/portal/customer_portal_landing_page_2.png)
If you did start with your email instead of a social login (e.g Google) you have to fill a password for your authentication.
In that case you will get an initialization mail to verify your account.
![](../../../../public/img/manuals/portal/customer_portal_landing_page_3.png)
You are now registered with a free account and ready to try all the features of ZITADEL.
Sign in to [ZITADEL Customer Portal](https://zitadel.com), to manage all you instances.
apps/docs/content/guides/manage/cloud/support.mdx
+34
View File
@@ -0,0 +1,34 @@
---
title: ZITADEL Support
sidebar_label: Customer Support
---
<Callout>
We describe our [support services](/legal/service-description/support-services) and information required in more detail in our legal section. Beware that not all features may be supported by your subscription and consult the [support states](https://help.zitadel.com/zitadel-support-states).
</Callout>
## General
We always recommend first having a look at our [documentation](/docs), [discord chat](https://zitadel.com/chat) and [GitHub repository](https://github.com/zitadel/zitadel). You can also ask our AI assistant for help before contacting Support.
![](../../../../public/img/manuals/portal/customer_portal_general_support.png)
![](../../../../public/img/manuals/portal/customer_portal_general_support_inkeep.png)
## Support Request
Create a new support request with the following information:
- Subject
- Detailed description
- Attachments (Optional)
- Ticket Priority
- Ticket Category
- Hosting
- Affected Instance (Only for cloud instances)
- Database Version (Only for self-hosted instances)
![](../../../../public/img/manuals/portal/customer_portal_support.png)
![](../../../../public/img/manuals/portal/customer_portal_support_2.png)
After submitting the form, you will receive a confirmation email, and our team will be in touch with you shortly.
apps/docs/content/guides/manage/cloud/users.mdx
+31
View File
@@ -0,0 +1,31 @@
---
title: Customer Portal Administrators
sidebar_label: Customer Portal Administrators
---
Manage all your administrators who are allowed to access the Customer Portal.
For the moment all users with access to the Customer Portal will have the role "Admin".
![](../../../../public/img/manuals/portal/customer_portal_administrator_list.png)
## Add new administrator
1. Go to the Administrators tab in the ZITADEL Customer Portal
2. Click the button "Create"
3. Fill in the Firstname, Lastname, Email and the username
4. Click create
The user will receive a verification email. Clicking the button in the email will lead to the user activation screen where password creation is required.
![](../../../../public/img/manuals/portal/customer_portal_add_admin.png)
## Delete administrator
1. Go to the Administrators tab in the ZITADEL Customer Portal
2. Click the bin icon in the users table for the user you like to delete
3. You will get a popup, where you have to enter the login name of the user to confirm that you like to delete the user
4. Click the "delete" button
The user will be deleted and has no access to the Customer Portal anymore
![](../../../../public/img/manuals/portal/customer_portal_delete_admin.png)
apps/docs/content/guides/manage/console/_add_manager.mdx
+6
View File
@@ -0,0 +1,6 @@
When adding a new manager, you can select multiple roles some of which are only allowed to read data.
This can be especially useful if you add service users for one of your projects where you only need read access.
Per default you will only search for users within the selected organization. If you like to give a role to a user outside the organization you need to switch to the global search and type the exact loginname of the users. This will prevent users from guessing users from other organizations.
<img alt="Managers" src="/docs/img/guides/console/addmanager.png" width="390px" />
apps/docs/content/guides/manage/console/_application-types.mdx
+5
View File
@@ -0,0 +1,5 @@
- [**Web**](#web) (Server-side web applications such as java, .net, ...)
- [**Native**](#native) (native, mobile or desktop applications)
- [**User Agent**](#user-agent) (single page applications / SPA, generally JavaScript executed in the browser)
- [**API**](#api) (OAuth Resource Server)
- [**SAML**](#saml)
apps/docs/content/guides/manage/console/_create-user.mdx
+45
View File
@@ -0,0 +1,45 @@
To create a new user, go to Users and click on **New**. Enter the required contact details and save by clicking “Create”.
<Callout>
If you started with Zitadel before version 3, you might have the "Human User [deprecated]" UI.
In this case please enable the Feature Flag "Use V2 Api in Management Console for User creation" in the Default Settings.
</Callout>
<Tabs>
<Tab value="human" label="Human User" default>
<img src="/docs/img/guides/console/invitehuman.png" width="680px" alt="Invite Human" />
When creating a new user you have different options.
First add the email, and select if the email address should be added automatically as "verified".
In the last section you can choose the authentication options:
- **Setup authentication later for this user**: This flow might be useful if an employee starts at a later point but you already want to prepare the account. The user will not have an authentication method, before they will be able to login, they need to setup a method.
- **Send an invitation E-Mail for authentication setup and E-Mail verification**: The user will receive an email and be able to setup an authentication method (e.g Password, Passkey, External SSO).
- When using the [Zitadel Login V1](/guides/integrate/login/hosted-login) the user will be prompted to setup a password
- When using the [Zitadel Login V2](/guides/integrate/login/hosted-login#hosted-login-version-2) the user has the option to choose the authentication method (password, passkey, identity provider), based on the configuration of the organization
<img src="/docs/img/guides/console/setupauthmethod.png" width="680px" alt="Invite Human - Setup authentication method" />
- **Set an initial password for the user**: The user will receive an email and be able to setup an authentication method (e.g Password, Passkey, External SSO)
</Tab>
<Tab value="human_deprecated" label="Human User [deprecated]">
<img src="/docs/img/guides/console/addhuman.png" width="680px" alt="Add Human" />
After a human user is created, by default, an initialization mail with a code is sent to the registered email. This code then has to be verified on first login.
If you want to omit this mail, you can check the **email verified** and **set initial password** toggle.
If no password is set initially, the initialization mail prompting the user to set his password is sent.
</Tab>
<Tab value="service" label="Service User">
<img
src="/docs/img/guides/console/addmachine.png"
width="540px"
alt="Add Service User"
/>
</Tab>
</Tabs>
You can prompt the user to add a second factor method too by checking the **Force MFA** toggle in [Login behaviour settings](/guides/manage/console/default-settings#login-behavior-and-access).
When logged in, a user can then manage the profile in the management console, adding a profile picture, external IDPs and Passkeys.
<img src="/docs/img/guides/console/myprofile.png" alt="Profile Self Manage" />
apps/docs/content/guides/manage/console/actions-overview.mdx
+101
View File
@@ -0,0 +1,101 @@
---
title: Actions
sidebar_label: Overview
---
## Overview
An Identity and Access Management system is a highly interactive environment. ZITADEL includes a powerful feature called **Actions**, which allows you to programmatically react to specific events within the system.
Actions allow you to define custom scripts (JavaScript) that are executed based on specific triggers (Flows). This enables advanced customization, such as modifying tokens, calling external APIs during login, or customizing authentication flows.
<img
src="/docs/img/guides/console/actionsmenu.png"
width="700px"
alt="Actions menu"
/>
## How Actions Work
The Actions architecture consists of three main components:
1. **Action:** The JavaScript code containing your business logic.
2. **Trigger Type:** The specific event in ZITADEL (e.g., "Post Authentication") where code execution is allowed.
3. **Flow:** The configuration that links an Action to a Trigger Type.
### The JavaScript Runtime
ZITADEL interprets your Action scripts as JavaScript.
* **Compliance:** Scripts must be **ECMAScript 5.1(+)** compliant.
* **Engine:** The underlying engine is [goja](https://github.com/dop251/goja). Refer to their documentation for detailed references about the underlying library features and limitations.
### Structure of an Action Script
The script of an action must contain a function that matches the Action's name. ZITADEL calls this function at runtime.
The function receives two primary objects:
* `ctx` (Context): Provides **readable** information about the current request (User, Request Info, etc.).
* `api` (API): Provides **methods** to mutate state (Set Claims, Deny Access, etc.).
**Example:**
If your action is named **doSomething**, your script must look like this:
```js
function doSomething(ctx, api){
// read from ctx and manipulate with api
}
```
### Available Modules
You can use the following built-in modules inside your JavaScript code:
* [**HTTP module**](../../../apis/actions/modules#http): To call external APIs / Webhooks.
* [**Logging module**](../../../apis/actions/modules#log): To log information to stdout (useful for debugging).
* [**UUID module**](../../../apis/actions/modules#uuid): To generate UUIDs.
Stuck customizing ZITADEL actions? Find samples for setting OIDC claims, SAML attributes, extending JIT provisioning data, calling external APIs, and more in [this repository](https://github.com/zitadel/actions).
## Managing Actions in Management Console
### 1. Create an Action
To add an action, navigate to your Organization's top navigation and select **Actions**. Click the **New** button and provide:
* **Name:** Must match the function name in your script.
* **Script:** Your JavaScript code.
* **Timeout:** How long the script is allowed to run before being terminated.
* **Allowed to Fail:** If checked, the flow will continue even if the script throws an error.
<img src="/docs/img/guides/console/action.png" alt="Create Action" width="450px" />
### 2. Create a Flow (Link Action to Trigger)
Merely creating an Action does not run it. You must create a **Flow** to define *when* it runs.
1. Select the **Flow Type** (e.g., External Authentication).
2. Select the **Trigger** (e.g., Post Authentication).
3. Add your Action to the list of executed scripts.
<img src="/docs/img/guides/console/flow.png" alt="Flow" width="400px" />
**Example Scenario:**
You create an **External Authentication** Flow with a **Post Authentication** trigger. Now, whenever a user authenticates via an external IDP (like Google or Azure AD), your Action is triggered immediately after the authentication step but before the session is finalized.
## Available Flow Types
Trigger types define the point during the execution of a request. Each trigger defines which readable information (`ctx`) and mutable properties (`api`) are passed into the called function.
Currently, ZITADEL supports the following flows:
* [**Internal Authentication**](../../../apis/actions/internal-authentication): Triggers during login with ZITADEL (username/password).
* [**External Authentication**](../../../apis/actions/external-authentication): Triggers during login with an external Identity Provider.
* [**Complement Token**](../../../apis/actions/complement-token): Triggers when tokens (ID Token / Access Token) are created, allowing you to add custom claims.
* [**Customize SAML Response**](../../../apis/actions/customize-samlresponse): Triggers when a SAML response is generated.
## References
* [Guide: Customize Behavior with Actions](/guides/manage/customize/behavior)
* [ZITADEL Roadmap](https://zitadel.com/roadmap)
apps/docs/content/guides/manage/console/actions.mdx
+26
View File
@@ -0,0 +1,26 @@
---
title: ZITADEL Actions
sidebar_label: Actions
---
An Identity and Management system is a very interactive place. ZITADEL has built in functionality to react to its events. This functionality is called **Actions** and can be accessed from your organizations top navigation.
<img
src="/docs/img/guides/console/actionsmenu.png"
width="700px"
alt="Actions menu"
/>
Actions allow you to define scripts which are then run on certain triggers.
To add an action, click at the **new** button and provide a script and a name.
You can specify a timeout and whether the action is allowed to fail too.
<img src="/docs/img/guides/console/action.png" alt="Create Action" width="450px" />
To run those scripts, a flow with a trigger has to be created.
This could for example be a **External Authentication** Flow, with a **Post Authentication** trigger.
<img src="/docs/img/guides/console/flow.png" alt="Flow" width="400px" />
Now whenever a user gets authenticated externally with an IDP, a action is triggered after the authentication itself.
If you want to know more where actions can be useful, take a look at the feature [here](/concepts/features/actions) or directly jump to an example of a custom behavior [here](/guides/manage/customize/behavior).
apps/docs/content/guides/manage/console/applications-overview.mdx
+190
View File
@@ -0,0 +1,190 @@
---
title: Applications
sidebar_label: Applications
sidebar_position: 5
---
import ThemedImage from "@/components/docusaurus/themed-image";
import AuthType from "../../integrate/application/_auth-type.mdx";
import ReviewConfig from "../../integrate/application/_review-config.mdx";
import AppType from "./_application-types.mdx";
## What is an application?
Applications are the entry point to your [Project Overview](/guides/manage/console/projects-overview)
. Users either login into one of your clients (Frontend) and interact with them directly, or use one of your APIs (Backend).
All applications within a project share the same **Roles** and **Authorizations**. This means you define a role once (e.g., `admin`) on the Project level, and it applies across all your web, mobile, and API applications.
To access your applications, navigate to your Project in the Management Console and select your application.
<img
alt="Granted project"
src="/docs/img/guides/console/applications.png"
width="750px"
/>
## Create an Application
To add an application to your project, click on the **New** button and select your application type.
<img
alt="Add application"
src="/docs/img/guides/console/addapplication.png"
width="120px"
/>
## Application Types
ZITADEL offers five client types to cover different architectural patterns:
<AppType components={props.components} />
The first three options (Web, Native, and User Agent) require user interaction. The fourth option (API) is for machine-to-machine communication without direct user interaction.
Depending on the app type, there are small differences in the possible settings. To get a good understanding about user profiles and recommended flows, read the [Recommended Flows Guide](../../integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
### Web
Web applications are **server-side rendered** applications that users interact with.
* **Examples:** Applications using Java (Spring/Thymeleaf), .NET (Razor), PHP, Python (Django/Flask), or enabling SSO in tools like GitLab.
* **NextJS:** A NextJS app is typically a Web Application because it can execute server-side code (SSR/API routes) to keep secrets safe.
* **Authentication:** Uses Authorization Code Flow (PKCE recommended) with a Client Secret.
<AuthType components={props.components} appType="web" />
### Native
Native Applications are installed on a thin client, such as a smartphone or desktop computer.
* **Examples:** Android Apps, iOS Apps, Desktop Apps (Electron, Tauri).
* **Authentication:** Uses the Key file generated by ZITADEL to authenticate or Authorization Code Flow with PKCE (for user login).
<AuthType components={props.components} appType="native" />
### User Agent
User Agent Applications are executed entirely in the web browser (Client-Side).
* **Examples:** Single Page Applications (SPA) built with React, Angular, Vue, or Svelte that do not have a backend server.
* **Authentication:** Uses Authorization Code Flow with PKCE (implicit flow is supported but not recommended).
<AuthType components={props.components} appType="user-agent" />
### API
These are applications without human interaction, accessed by other applications or services (Machine-to-Machine).
* **Examples:** Background workers, CLIs, Daemons, Microservices.
* **Authentication:** Uses Client Credentials (JWT Profile or Basic Auth) or Private Key JWT.
<AuthType components={props.components} appType="api" />
### SAML
If your application doesn't support the OIDC standard but supports SAML 2.0, choose this type. SAML is an XML-based open standard for exchanging authentication and authorization data.
After creating a SAML app, you can either:
1. Add a link to a SAML metadata file.
2. Upload the metadata XML file directly.
You can find example configurations for SAML 2.0 in our [integrate services](../../integrate/login/saml) guides.
## Configuration
### Redirect URIs
App Types with user interaction (Web, Native, and User Agent) require Redirect URIs. These are the allowed URLs where ZITADEL sends the user after a successful login.
* **Security:** ZITADEL strictly checks these URIs during the login process. They must match exactly what is defined in your application code.
* **Protocols:** Native applications can use custom protocols (e.g., `myapp://`) instead of `http/https`.
<img
alt="Redirect URIs"
src="/docs/img/guides/console/redirecturis.png"
width="600px"
/>
### Development Mode
If you are developing locally or need to redirect users to a non-secure protocol (other than `https://`), you must enable **Development mode**.
When disabled, ZITADEL enforces strict security and only allows `https`.
<img
alt="Development mode"
src="/docs/img/guides/console/developmentmode.png"
width="600px"
/>
**Glob Patterns:**
Development mode allows the use of glob patterns in Redirect URIs for flexibility:
| Special Terms | Meaning |
| :--- | :--- |
| `*` | Matches any sequence of **non-path-separators**. |
| `/**/` | Matches zero or more directories. |
| `?` | Matches any single non-path-separator character. |
| `[class]` | Matches any single character against a class of characters (e.g., `[a-z]`). |
| `{alt1,...}` | Matches a sequence if one of the comma-separated alternatives matches. |
<Callout type="note">
Double stars (`**`) should appear surrounded by path separators (e.g., `/**/`). A pattern like `path/to/**.txt` is invalid; use `path/to/**/*.txt`.
</Callout>
<Callout type="tip">
IPv6
When IPv6 URIs are used as redirects in development mode, square brackets must be escaped as they are special terms for globs. Example: `http://\[::1\]:80`
</Callout>
### Review Configuration
<ReviewConfig components={props.components} authType="code" />
## Application Settings
After creating an application, you can modify its configuration.
* **Auth Method:** You can switch authentication methods (e.g., from Basic to Private Key JWT) via the toggle or dropdowns.
* **OIDC Compliance:** The Management Console checks if your configuration is OIDC compliant and shows tasks for completion if anything is missing.
<Callout type="caution">
You **cannot** change the Application Type (e.g., from Web to Native) after creation. You must delete and recreate the application.
</Callout>
<img
alt="Application Settings"
src="/docs/img/guides/console/application.png"
width="800px"
/>
### Token Settings
In the **Token Settings** section, you can customize the tokens issued for this application:
* **Token Type:** Switch between **Bearer Token** (Opaque) and **JWT**.
* **Content:** Check options to include User Roles and User Information inside the ID Token.
* **ClockSkew:** Optionally set a time buffer added to the expiration time of the issued token to handle server time differences.
<img
alt="Token settings"
src="/docs/img/guides/console/app-token-settings.png"
width="600px"
/>
### Additional Origins
If your application makes requests from domains other than the Redirect URI (e.g., a Javascript app fetching data from an API on a different domain), you can specify them here to configure CORS (Cross-Origin Resource Sharing).
<img
alt="Additional origins"
src="/docs/img/guides/console/additional-origins.png"
width="500px"
/>
## Security Considerations
Ensure the configuration of application settings is limited to authorized users only.
* Use [Administrator roles](./managers) to limit permissions for your users to make changes to your applications.
* When [granting projects](../../../concepts/structure/granted_projects) to other organizations, the receiving organization **cannot** see or change the application configuration. They can only assign roles.
## References
- [Recommended OIDC Flows](../../integrate/login/oidc/oauth-recommended-flows)
apps/docs/content/guides/manage/console/applications.mdx
+200
View File
@@ -0,0 +1,200 @@
---
title: ZITADEL Applications
sidebar_label: Applications
---
import ThemedImage from "@/components/docusaurus/themed-image";
import AuthType from "../../integrate/application/_auth-type.mdx";
import ReviewConfig from "../../integrate/application/_review-config.mdx";
import AppType from "./_application-types.mdx";
## What is an application?
Applications are the entry point to your project.
Users either login into one of your clients and interact with them directly or use one of your APIs.
All applications share the roles and authorizations of their project.
To access your applications, navigate to your project and select your application.
<img
alt="Granted project"
src="/docs/img/guides/console/applications.png"
width="750px"
/>
## Create application
To add an application to your project, click on the add button and select your application type.
<img
alt="Add application"
src="/docs/img/guides/console/addapplication.png"
width="120px"
/>
## Application Types
At the moment ZITADEL offers five client types:
<AppType components={props.components} />
The first three options (Web, Native and User Agent) require user interaction, the fourth option (API) has no direct user-interaction.
Depending on the app type, there are small differences in the possible settings.
To get a good understanding about user profiles and recommended flows, read the following [guide](../../integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
### Web
Web applications are **server side rendered** applications users interact with. For example if you develop an application using Thymeleaf in Java or Razor in .NET or want to enable SSO in Gitlab.
Typical **React or Angular** apps **are not** a Web applications in this case.
A **NextJS** on the contrary would be because it allows you to implement server side code.
Following authentication types can be used:
<AuthType components={props.components} appType="web" />
### Native
Native Applications installed on a thin client. For example on a smartphone or computer. This can for example be Android and iOS Applications.
These applications uses the Key file generated by ZITADEL to authenticate.
<AuthType components={props.components} appType="native" />
### User Agent
User Agent Applications that are executed in a web browser, for example single page applications executed in the browser developed with JavaScript frameworks like [Angular](../../../examples/login/angular) or [React](../../../examples/login/react)
Following **authentication methods** can be used:
<AuthType components={props.components} appType="user-agent" />
### API
These are Applications without human interaction. These applications are accessed by other applications, so called machine to machine communication.
Following authentication types can be used:
<AuthType components={props.components} appType="api" />
After selecting your Apps Type and Authentication Method, you may need to specify redirect URIs.
### SAML
If your application doesn't support the OIDC standard, but SAML this is the right application type to choose. SAML is an open standard used for authentication based on XML.
After entering a name and choosing the application type "SAML", you will get to the SAML configuration screen.
You can either add a link to a SAML metadata file or upload it directly.
SAML metadata is an XML document which contains information necessary for interaction with SAML-enabled identity or service providers.
You can find some example configurations for SAML 2.0 in our [integrate services](/guides/integrate/services) guides
## Redirect URIs
App Types with User interaction (Web, Native and User Agent) require redirect URIs.
Those redirects URIs are used to redirect the user back to your application on successful login.
These URIs are defined in your application code and are checked by ZITADEL if they correspond to your applications configuration.
Redirect URIs are checked during the login process.
Native applications can use a different protocol than http or https in order to redirect your user.
<img
alt="Redirect URIs"
src="/docs/img/guides/console/redirecturis.png"
width="600px"
/>
### Development mode
In order to develop locally, or you want to redirect users to any other protocol than https://, you must enable **Development mode**.
When disabled only https is allowed, as ZITADEL's configuration is secure by default.
<img
alt="Development mode"
src="/docs/img/guides/console/developmentmode.png"
width="600px"
/>
Development mode also allows glob patterns in redirect URIs with the following special terms in the patterns:
| Special Terms | Meaning |
| ------------- | ---------------------------------------------------------------------------------------------------------- |
| `*` | matches any sequence of non-path-separators |
| `/**/` | matches zero or more directories |
| `?` | matches any single non-path-separator character |
| `[class]` | matches any single non-path-separator character against a class of characters [see "character classes"][1] |
| `{alt1,...}` | matches a sequence of characters if one of the comma-separated alternatives matches |
[1]: https://github.com/bmatcuk/doublestar?tab=readme-ov-file#character-classes
Special character can be escaped with a backslash (`\`).
Double stars (`**`) should appear surrounded by a path separators such as `/**/`.
A mid-pattern double star (`**`) behaves like bash's glob star option: a pattern
such as `path/to/**.txt` would return the same results as `path/to/*.txt`. The
pattern you're looking for is `path/to/**/*.txt`.
*Source: [github.com/bmatcuk/doublestar](https://github.com/bmatcuk/doublestar?tab=readme-ov-file#patterns)*
> When IPv6 URIs are used as redirects in development mode, square brackets must be escaped as they are also Special Terms for globs. `http://\[::1\]:80`
## Review Configuration
<ReviewConfig components={props.components} authType="code" />
## Application settings
After creating the application, you can still change its configuration if you for example need a offline_access support (Refresh token).
You can easily change your authentication method via the colored toggle on top or directly change configuration via the input and dropdown fields.
> Note: Changing application type is not possible. In this case you have to create a new application.
<img
alt="Redirect URIs"
src="/docs/img/guides/console/application.png"
width="800px"
/>
On the top of the page you can check if your application is OIDC compliant.
Tasks for completion are shown in the field.
<img
alt="OIDC Compliance"
src="/docs/img/guides/console/oidc-compliance.png"
width="600px"
/>
### Token settings
In the token settings you can change the type from **Bearer Token** to **JWT**, and check some settings whether you need user roles and user information in the ID Token or not.
On the bottom you can optionally set a **ClockSkew** time which is added to the expiration time of the issued token.
<img
alt="Token settings"
src="/docs/img/guides/console/app-token-settings.png"
width="600px"
/>
### Redirect settings
Like on creation, you can modify you redirect settings here.
Note that for local development you most likely have to enable development mode, as redirects to http:// are otherwise blocked.
On Native Apps you can also skip the Login Success Page.
<img
alt="Redirect URIs"
src="/docs/img/guides/console/redirect-uris.png"
width="500px"
/>
### Additional origins
If you need to allow additional origins which should **NOT** be used as redirect you can specify them in the **Additional origins** section.
<img
alt="Additional origins"
src="/docs/img/guides/console/additional-origins.png"
width="500px"
/>
apps/docs/content/guides/manage/console/console-overview.mdx
+57
View File
@@ -0,0 +1,57 @@
---
title: Management Console
sidebar_label: Management Console
---
## Overview
The ZITADEL Management Console is the web-based Dashboard UI designed to facilitate the management and administration of ZITADEL resources and configurations. It serves as a central hub where [Managers](/concepts/structure/managers) can perform tasks related to identity and access management, configure authentication methods, and manage the organization's infrastructure.
While the Management Console is primarily a tool for administrators, it can also be accessed by end-users to manage their own profiles (e.g., password reset, MFA setup), unless you [restrict access](/guides/solution-scenarios/restrict-console) to build your own custom UI.
## Accessing the Management Console
The management console is available by navigating to the [Custom Domain](/concepts/features/custom-domain) of your instance and appending the path `/ui/console`.
## Navigation and Context
When logged in, you are greeted by the home page, which allows you to set shortcuts to frequently used settings and projects.
### Context Switcher
ZITADEL is a multi-tenant system. The Management Console features a **Context Switcher** in the **top-left** corner. This allows you to switch between the different **Organizations** you manage.
Depending on your use case:
* **B2C:** You might stick to your global organization.
* **B2B:** You will frequently switch between multiple organizations to manage specific customer settings.
<img
src="/docs/img/guides/console/contextswitcher.png"
alt="Context switcher"
width="400px"
/>
To understand how to structure your organizations, read our [Solution Scenario](/guides/solution-scenarios/configurations) guides.
## Key Capabilities
The Management Console enables administrators to perform the following critical tasks:
1. **Default Settings:** Managers can configure global system defaults. This includes authentication methods, security policies (like password complexity or lockout policies), and other system-wide parameters.
2. **Resource Management:** Create, update, and delete essential resources such as [Organizations](./organizations-overview), [Projects](./projects-overview), and [Applications](./applications-overview).
3. **User Management:** Manage the lifecycle of [User accounts](./users-overview). This includes creating new users, updating profiles, resetting passwords, and deactivating accounts.
4. **Access Control:** Define and manage permissions. Administrators can assign [Roles](/guides/manage/console/roles) to users and configure fine-grained access controls for specific resources.
5. **Manager Assignment:** Delegate administrative tasks by assigning **Administrator** roles (e.g., Org Owner, Project Owner) to specific users, ensuring proper oversight and segregation of duties.
6. **Customization and Branding:** Customize the look and feel of ZITADEL. You can upload custom logos, select color schemes, and apply [branding](/guides/manage/customize/branding) to match your corporate identity.
7. **Audit Logging:** Access [Audit Logs](/concepts/features/audit-trail) to track user activity and configuration changes. This is essential for monitoring security events and maintaining regulatory compliance.
## Security and Restrictions
### Prevent Management Console Access
In many implementations, specifically white-label B2C scenarios, you may want to prevent end-users from accessing the generic ZITADEL Management Console entirely.
Administrators can restrict access to the management console, forcing users to interact only with your own applications or custom user interfaces.
Please follow the [Restrict Management Console Access guide](/guides/solution-scenarios/restrict-console) to achieve this.
## References
* [Administrator Roles Concept](/concepts/structure/managers)
apps/docs/content/guides/manage/console/default-settings.mdx
+396
View File
@@ -0,0 +1,396 @@
---
title: ZITADEL Default Settings
sidebar_label: Default Settings
---
Default settings work as default or fallback settings for your organizational settings. Most of the time you only have to set default settings for the cases where you don't need specific behavior in the organizations themselves or you only have one organization.
To access default settings, use the settings page at `{instanceDomain}/ui/console/settings` or click at the default settings button on the **top-right** of the page and then navigate to settings in the navigation.
<img
src="/docs/img/guides/console/instancebutton.png"
alt="Instance Button"
width="450px"
/>
When you configure your default settings, you can set the following:
- **Organizations**: A list of your organizations
- [**Features**](#features): Feature Settings let you try out new features before they become generally available. You can also disable features you are not interested in.
- [**Notification settings**](#notification-settings): Setup Notification and Email Server settings for initialization-, verification- and other mails. Setup Twilio as SMS notification provider.
- [**Login Behavior and Access**](#login-behavior-and-access): Multifactor Authentication Options and Enforcement, Define whether passkeys are allowed or not, Set Login Lifetimes and advanced behavior for the login interface.
- [**Identity Providers**](#identity-providers): Define IDPs which are available for all organizations
- [**Password Complexity**](#password-complexity): Requirements for Passwords ex. Symbols, Numbers, min length and more.
- [**Password Expiry**](#password-expiry): Set an expiry for passwords. After the expiration, a user will be prompted to change their password during the next login.
- [**Lockout**](#lockout): Set the maximum attempts a user can try to enter the password or any (T)OTP method. When the number is exceeded, the user gets locked out and has to be unlocked.
- [**Domain settings**](#domain-settings): Whether users use their email or the generated username to login. Other Validation, SMTP settings
- [**Branding**](#branding): Appearance of the login interface.
- [**Message Texts**](#message-texts): Text and internationalization for emails
- [**Login Interface Texts**](#login-interface-texts): Text and internationalization for the login interface
- [**External Links**](#external-links): Links to your own Terms of Service and Privacy Policy regulations, Help Page, Support email, documentation link...
- [**OIDC Token Lifetimes and Expiration**](#oidc-token-lifetimes-and-expiration): Token lifetime and expiration settings.
- [**Secret Generator**](#secret-generator): Appearance and expiration of the generated codes and secrets used in mails for verification etc.
## Features
Feature Settings let you try out new features before they become generally available. You can also disable features you are not interested in.
The Page lets you choose between the settings `Enabled`, `Disabled` or `Inherit`.
If a feature is set to `Inherit`, it becomes available once its enabled per default.
<img
src="/docs/img/console_feature_settings.png"
alt="Feature page"
width="700px"
/>
Features can range from UI changes in the management console, to new APIs or performance improvements.
<Callout type="warn">
Be careful on which features you enable as they can be in an experimental state.
</Callout>
## Branding
We recommend setting your Branding and SMTP settings initially as it will comfort your customers having a familiar UI for login and receiving notifications from your domain and mail addresses.
![](../../../../public/img/console_private_labeling.png)
In the Branding settings, you can upload you Logo for the login interface, set your own colors for buttons, background, links, and choose between multiple behaviors. You don't need to be an expert as those settings can all be set without any knowledge of CSS.
| Setting | Description |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Logo | Upload your logo for the light and the dark design. This is used mainly in the login interface. |
| Icon | Upload your icon for the light and the dark design. Icons are used for smaller components. For example in management console on the top left as the home button. |
| Colors | You can set four different colors to design your login page and email. (Background-, Primary-, Warn- and Font Color) |
| Font | Upload your custom font |
| Advanced Behavior | **Hide Loginname suffix**: If enabled, your loginname suffix (Domain) will not be shown in the login page. **Disable Watermark**: If you disable the watermark you will not see the "Powered by ZITADEL" in the login page |
Make sure you click the "Apply configuration" button after you finish your configuration. This will ensure your design is visible for your customers.
Branding settings applied on you instance act as a default for all your organizations. If you need custom branding on a organization take a look at our guide under [organization setting](./organizations#organization-settings).
## Notification settings
In the notification settings you can configure when to notify users about certain events and you can customize your SMTP Server settings and your SMS Provider.
At the moment Twilio is available as SMS provider.
### Notification
You can configure on which changes the users will be notified. The text of the message can be changed in the [Message texts](#message-texts)
<img
src="/docs/img/guides/console/notification.png"
alt="Notification"
width="400px"
/>
### SMTP
On each instance we configure our default SMTP provider. To make sure, that you only send some E-Mails from domains you own, you need to add a Custom Domain on your instance.
You can configure many SMTP providers using templates for popular providers. The templates will add known settings like host, port or default user and will suggest values for user and/or password.
<Callout>
You have to activate your SMTP provider so Zitadel can use it to send your emails. Only one provider can be active.
</Callout>
<Callout type="warn">
The built-in SMTP provider is intended **only for testing and evaluation purposes**.
Email delivery through this service may be **delayed or temporarily unstable**.
For any **production setup**, you must configure your own SMTP provider to ensure reliable and consistent email delivery.
</Callout>
Go to the ZITADEL [customer portal](https://zitadel.cloud) to configure a Custom Domain.
To configure your custom SMTP please fill the following fields:
- Sender email address
- Sender name
- Enable or Disable Transport Layer Security (TLS)
- Host
- User
- SMTP Password
<img src="/docs/img/guides/console/smtp.png" alt="SMTP" width="800px" />
While you create/update a SMTP provider you have the chance to test your SMTP configuration
<img src="/docs/img/guides/console/smtp_test.png" alt="SMTP" width="800px" />
In the SMTP providers table you can hover on a provider row to show buttons that allow you to activate/deactivate a provider, test your smtp settings and delete a provider
<img src="/docs/img/guides/console/smtp_table.png" alt="SMTP" width="800px" />
### SMS
No default provider is configured to send some SMS to your users. If you like to validate the phone numbers of your users make sure to add your twilio configuration by adding your Sid, Token and either a Sender Number or a Verification Service Sid.
Setting a Verification Service Sid allows using the Twilio Verify Service instead of the Messages Service for verification.
<img src="/docs/img/guides/console/twilio.png" alt="Twilio" />
## Login Behavior and Access
The Login Policy defines how the login process should look like and which authentication options a user has to authenticate.
| Setting | Description |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Username Password allowed | Possibility to login with username and password. If this is disabled only login with external identity providers will be allowed |
| Register allowed | Enable self register possibility in the login ui, this enables username password registration as well as registration with configured external identity providers |
| External IDP allowed | Possibility to login with an external identity (e.g Google, Microsoft, Apple, etc), If you like to allow external Identity providers add them to the providers list |
| Hide password reset | Disable the self-service option for users to reset their password. |
| Domain discovery allowed | If this setting is enabled, the user doesn't have to exist when entering the username. It is required to have verified domains on the organization. Example: ZITADEL is registered as organization with the domain zitadel.com and Entra ID as identity provider. A user enters [email protected] in the login but the user doesn't exist. The domain can be mapped to the organization and therefore the user can be redirected to the Entra ID. |
| Ignore unknown usernames | This setting can be enabled, if no error message should be shown if the user doesn't exist. Example: A user enters the login name [email protected], the user doesn't exist, but will be redirected to the password screen. After entering a password, the user will get an error that either username or password are wrong. |
| Disable login with email address | By default users can additionally [login with the email attribute](/guides/solution-scenarios/configurations#use-an-email-address-as-username) of their user. Check this option to disable. |
| Disable login with phone number | By default users can additionally [login with the phonenumber attribute](/guides/solution-scenarios/configurations#use-a-phone-number-as-username) of their user. Check this option to disable. |
<img
src="/docs/img/guides/console/loginpolicy.png"
alt="Login Behavior and Access"
width="800px"
/>
### Default Redirect URI
The Default Redirect URI will be used, if a user calls the login page directly.
More specifically, typically a client will initiate login with an auth request.
The auth request contains a client-id and a redirect uri, that must match the configuration in ZITADEL.
If there is no [auth request](https://zitadel.com/playgrounds/oidc), users will be redirected to the Default Redirect URI, which is by default `https://${CUSTOM_DOMAIN}/ui/console/`
Reasons why ZITADEL doesn't have a redirect URI:
- The login has not been called with an OIDC authorize request
- The user landed on the login through an email link, e.g. Password Reset, Initialize User
We recommend setting your own default redirect URI, if you do not want end users to access ZITADEL Management Console.
Change default redirect url of instance: `https://${CUSTOM_DOMAIN}/ui/console/instance?id=login`
<img
src="/docs/img/guides/solution-scenarios/console-default-redirect.png"
alt="Login Policy Advanced Setting: Default Redirect URL"
width="600px"
/>
### Passkeys
Passkey authentication means that the user doesn't need to enter a password to login. In our case the user has to enter his loginname and as the next step proof the identity through a registered device or token.
There are two different types one is depending on the device (e.g. Fingerprint, Face recognition, WindowsHello) and the other is independent (eg. Yubikey, Solokey).
### Multifactor (MFA)
In the multifactors section you can configure what kind of multifactors should be allowed. For passkeys to work, it's required to enable U2F (Universal Second Factor) with PIN. There is no other option at the moment.
Multifactors:
- U2F (Universal Second Factor) with PIN, e.g FaceID, WindowsHello, Fingerprint, Hardwaretokens like Yubikey
Second factors (2FA):
- Time-based One Time Password (TOTP), Authenticator Apps like Google/Microsoft Authenticator, Authy, etc.
- Universal Second Factor (U2F), e.g FaceID, WindowsHello, Fingerprint, Hardware tokens like Yubikey
- One Time Password with Email (Email OTP)
- One Time Password with SMS (SMS OTP)
Force a user to register and use a multifactor authentication, by checking the option "Force MFA".
Ensure that you have added the MFA methods you want to allow.
Or you can enable the "Force MFA for local authenticated users", which will enforce this rule only on local authentication, but not on users authenticated through an Identity Provider.
### Login Lifetimes
Configure the different lifetimes checks for the login process:
- **Password Check Lifetime** specifies after which period a user has to reenter his password during the login process
- **External Login Check Lifetime** specifies after which period a user will be redirected to the IDP during the login process
- **Multi-factor Init Lifetime** specifies after which period a user will be prompted to setup a 2-Factor / Multi-factor during the login process (value 0 will deactivate the prompt)
- **Second Factor Check Lifetime** specifies after which period a user has to revalidate the 2-Factor during the login process
- **Multi-factor Login Check Lifetime** specifies after which period a user has to revalidate the Multi-factor during the login process
## Identity Providers
You can configure all kinds of external identity providers for identity brokering, which support OIDC (OpenID Connect).
Create a new identity provider configuration and enable it in the list afterwards.
For a detailed guide about how to configure a new identity provider for identity brokering have a look at our [identity provider guides](/guides/integrate/identity-providers/introduction).
## Password Complexity
With the password complexity policy you can define the requirements for a users password.
The following properties can be set:
- Minimum Length
- Has Uppercase
- Has Lowercase
- Has Number
- Has Symbol (Everything that is not a number or letter)
<img
src="/docs/img/guides/console/complexity.png"
alt="Password Complexity"
width="600px"
/>
## Password Expiry
With the password expiry policy you can set an expiration for user password.
After the expiration, a user will be prompted to change their password during the next authentication.
Note, that ZITADEL will not warn or notify the user about the expiry, yet. If you want your users to be notified, you can read this setting and send the notification yourself.
The following properties can be set:
- Maximum validity in days
- Expiration warning after days
<img
src="/docs/img/guides/console/expiry.png"
alt="Password Expiry Policy"
width="600px"
/>
## Lockout
Define when an account should be locked.
The following settings are available:
- Maximum Password Attempts: When the user has reached the maximum password attempts the account will be locked, If this is set to 0 the lockout will not trigger.
- Maximum OTP Attempts: When the user has reached the maximum (T)OTP attempts the account will be locked, If this is set to 0 the lockout will not trigger.
If an account is locked, the administrator has to unlock it in the ZITADEL Management Console
<img src="/docs/img/guides/console/lockout.png" alt="Lockout" width="600px" />
## Domain settings
### Add organization domain as suffix to loginnames
If you enable this setting, all loginnames will be suffixed with the organization domain. If this settings is disabled, you have to ensure that usernames are unique over all organizations.
### Validate Org domains
If this is enabled all created domains on an organization must be verified per dns/acme challenge.
More about how to verify a domain [here](/guides/manage/console/organizations-overview#domain-verification-guide).
If it is set to false, all registered domain will automatically be created as verified and the users will be able to use the domain for login.
### SMTP Sender Address matches Custom Domain
If enabled, the SMTP server address must match the instance's primary Custom Domain.
With that you can ensure that users receive notifications from the same domain that is used for login.
### Use email as username
To be able to use the email as username you have to disable the attribute "User Loginname must contain orgdomain" on your domain settings.
This means that all your users will not be suffixed with the domain of your organization and you can enter the email as username.
All usernames will then be globally unique within your instance.
You can either set this attribute on your whole ZITADEL instance or just on some specific organizations.
Please refer to the [configuration guide](/guides/solution-scenarios/configurations#use-email-to-login) for more information.
## External links
With this setting you are able to configure your privacy policy, terms of service, help links and help/support email address.
On register each user has to accept these policies.
This policy can be also be overridden by your organizations.
When focused on an input field you can see the language attribute, which can then be integrated into your link.
Example:
`https://demo.com/tos-{{.Lang}}`
<img
src="/docs/img/guides/console/external_links_1.png"
alt="External Links"
width="600px"
/>
Also you can set the link associated to the Documentation button in the console. Set an empty text if you don't want to show a Documentation button in your console. If you need a custom button to be shown in the management console you can set the button text and the link associated to the button (if the button text is button no text will be shown).
<img
src="/docs/img/guides/console/external_links_2.png"
alt="Custom button"
width="600px"
/>
## Message texts
These are the texts for your notification mails. Available for change are:
| Message Text | Description |
|-----------------|----------------------------------------------------------------------------------------------------------------------------|
| Domain Claim | The Mail after an organisation claimed a domain for itself. Users on other organisations with this domain will be notified |
| Initialization | The mail after a user has been created. A code is part of the message which then must be verified on first login |
| Passkey | The Mail to register an additional passkey device by a link |
| Password Reset | The Mail to reset the password by a link |
| Verify Email | The mail after the email has been changed. A code is part of the message which then must be verified on the next login |
| Password Changed | Notify the user, that the password has been changed. Can be configured in [Notification](#notification) |
You can set the locale of the translations on the right.
<img
src="/docs/img/guides/console/messagetexts.png"
alt="Message texts"
width="600px"
/>
## Login interface texts
These are the texts for the login. Just like for message texts, you can select the locale on the right.
<img
src="/docs/img/guides/console/logintexts.png"
alt="Login texts"
width="600px"
/>
## Languages
Drag allowed languages to the left column. Languages in the right column are not shown to your users.
Choose a default language which acts as a fallback, if no language header is set.
<img src="/docs/img/console_languages.png" alt="Languages" width="800px" />
## OIDC token lifetimes and expiration
Configure how long the different oidc tokens should life.
You can set the following times:
- Access Token Lifetime
- ID Token Lifetime
- Refresh Token Expiration
- Refresh Token Idle Expiration
<img
src="/docs/img/guides/console/oidcsettings.png"
alt="OIDC Token Lifetimes"
width="400px"
/>
## Secret generator
ZITADEL has some different codes and secrets, that can be specified.
You can configure what kind of characters should be included, how long the secret should be and the expiration.
The following secrets can be configured:
- Initialization Mail Code
- Email verification code
- Phone verification code
- Password reset code
- Passkey initialization code
- Application secrets
- One Time Password (OTP) - SMS
- One Time Password (OTP) - Email
<img
src="/docs/img/guides/console/secretappearance.png"
alt="Secret generator"
width="400px"
/>
If your done with your default settings, you can proceed setting up your organizations. Again, make sure you get an understanding on how your project is structured and then continue.
apps/docs/content/guides/manage/console/managers.mdx
+65
View File
@@ -0,0 +1,65 @@
---
title: ZITADEL Managers
sidebar_label: Managers
---
import ManagerDescription from "../../../concepts/structure/_manager_description.mdx";
import AddManager from "./_add_manager.mdx";
import PermissionTable from '@/components/PermissionTable';
import permissionData from "../../../../../../cmd/defaults.yaml";
<ManagerDescription components={props.components} name="ManagerDescription" />
To configure managers in ZITADEL go to the resource where you like to add it (e.g Instance, Organization, Project, GrantedProject).
In the right part of the management console you can find **MANAGERS** in the details part. Here you have a list of the current managers and can add a new one.
<img alt="Managers" src="/docs/img/guides/console/managers.png" width="200px" />
<AddManager components={props.components} name="AddManager" />
## Roles
| Name | Role | Description |
| ----------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
| IAM Owner | IAM_OWNER | Manage the IAM, manage all organizations with their content |
| IAM Owner Viewer | IAM_OWNER_VIEWER | View the IAM and view all organizations with their content |
| IAM Org Manager | IAM_ORG_MANAGER | Manage all organizations including their policies, projects and users |
| IAM User Manager | IAM_USER_MANAGER | Manage all users and their authorizations over all organizations |
| IAM Admin Impersonator | IAM_ADMIN_IMPERSONATOR | Allow impersonation of admin and end users from all organizations |
| IAM Impersonator | IAM_END_USER_IMPERSONATOR | Allow impersonation of end users from all organizations |
| IAM Login Client | IAM_LOGIN_CLIENT | Get all permissions needed to implement your own Login UI. |
| Org Owner | ORG_OWNER | Manage everything within an organization |
| Org Owner Viewer | ORG_OWNER_VIEWER | View everything within an organization |
| Org User Manager | ORG_USER_MANAGER | Manage users and their authorizations within an organization |
| Org User Permission Editor | ORG_USER_PERMISSION_EDITOR | Manage user grants and view everything needed for this |
| Org Project Permission Editor | ORG_PROJECT_PERMISSION_EDITOR | Grant Projects to other organizations and view everything needed for this |
| Org Project Creator | ORG_PROJECT_CREATOR | This role is used for users in the global organization. They are allowed to create projects and manage them. |
| Org Admin Impersonator | ORG_ADMIN_IMPERSONATOR | Allow impersonation of admin and end users from the organization |
| Org Impersonator | ORG_END_USER_IMPERSONATOR | Allow impersonation of end users from the organization |
| Project Owner | PROJECT_OWNER | Manage everything within a project. This includes to grant users for the project. |
| Project Owner Viewer | PROJECT_OWNER_VIEWER | View everything within a project. |
| Project Owner Global | PROJECT_OWNER_GLOBAL | Same as PROJECT_OWNER, but in the global organization. |
| Project Owner Viewer Global | PROJECT_OWNER_VIEWER_GLOBAL | Same as PROJECT_OWNER_VIEWER, but in the global organization. |
| Project Grant Owner | PROJECT_GRANT_OWNER | Same as PROJECT_OWNER but for a granted project. |
## Configure roles
If you run a self hosted ZITADEL instance you can define your custom roles by overwriting the defaults.yaml
In the InternalAuthZ section you will find all the roles and which permissions they have.
Example:
```bash
InternalAuthZ:
RolePermissionMappings:
- Role: "IAM_OWNER"
Permissions:
- "iam.read"
- "iam.write"
```
# Manager Permission Matrix
This table is generated dynamically from our configuration file.
<PermissionTable data={permissionData} />
apps/docs/content/guides/manage/console/organizations-overview.mdx
+160
View File
@@ -0,0 +1,160 @@
---
title: Organizations
sidebar_label: Organizations
---
## Overview
ZITADEL is organized around the idea of multi-tenancy. An **Organization** is the vessel where your projects and users live. It is comparable to a tenant in a SaaS system or an organizational unit (OU) in a directory-based system.
Key characteristics of Organizations in ZITADEL include:
* **Multi-tenancy:** Multiple organizations can be managed within one [instance](/concepts/structure/instance).
* **Isolation:** Users and data from one organization are separated from others.
* **Delegation:** Organizations can grant each other rights to self-manage certain aspects of the IAM (e.g., roles for access management).
In a B2B use case, an organization typically represents a business partner who requires their own branding, specific access settings, or distinct federated login providers.
![Overview ZITADEL Organizations](../../../../public/img/concepts/objects/organization.png)
## Structure and Delegation
### Projects within Organizations
You can use **Projects** within your organization to manage the security context of closely related components, such as roles, grants, and authorizations for multiple clients. You can set up multiple projects within a single organization.
### Organization Grants
ZITADEL allows you to give *other* organizations permission to manage certain aspects of a project within *your* organization.
For example, you could set up a project with roles that define access to your software, but allow a partner organization to allocate those roles to their own users independently. As a service provider, this allows you to establish a self-service culture for your business customers.
![Organization Grant](../../../../public/img/concepts/objects/organization_grants.png)
## Managing Organizations
### Create a new organization
To create a new organization, click on the organizations dropdown in the Management Console and select **New organization**.
You have two options regarding the initial administrator:
1. **Current User:** Create the organization with your currently logged-in user as the organization manager. A membership for the new organization will be added to your account.
2. **New Account:** Directly create a new account to manage the organization.
<img
width="400px"
src="/docs/img/console_org_select.png"
alt="Select Organization"
/>
### Self-Service Registration
If you want to enable your customers to create organizations themselves, ZITADEL provides a built-in registration form at:
`https://$CUSTOM-DOMAIN/ui/login/register/org`
The customer simply fills in the organization name and contact details to get started.
<img
width="400px"
src="/docs/img/console_org_register.png"
alt="Register new organization"
/>
### Default Organization
On the **Default settings** page (`${CUSTOM_DOMAIN}`/ui/console/orgs), you can designate a specific organization as the "Default".
* Click the **...** on the right-hand side of the table and select **Set as default organization**.
* The current default is marked by a "Default" label.
When no specific organization is selected (e.g., during an auth request or via [Domain Discovery](/guides/solution-scenarios/domain-discovery)), users are directed to this default organization for login and self-registration.
## Usernames and Domains
Each organization has its own pool of users, covering both human and service users. How these users authenticate depends on your domain configuration.
### Login Name Formats
By default, if the setting **User Loginname must contain orgdomain** is **disabled**, usernames are unique across the entire instance.
If you require usernames to be scoped to the organization (common in multi-tenant setups), you can enable **User Loginname must contain orgdomain** in your [Domain settings](./default-settings#domain-settings). Login names will then follow the format:
`{username}@{domainname}.{zitadeldomain}`
**Example:**
If a user has the username `john.doe` in an organization with the domain `acme`, the generated login name is:
`[email protected]`
### Custom Domain Names
You can verify your own domain names (e.g., `acme.ch`) to simplify the user experience. Once verified:
1. ZITADEL generates additional login names for users.
2. The user `john.doe` can log in via `[email protected]` OR `[email protected]`.
<Callout type="info">
Only one user with the username `john.doe` can exist within the organization `ACME`, regardless of which domain suffix they use to log in.
</Callout>
### Primary Domain
An organization can have multiple domain names, but only one is **Primary**. The primary domain determines:
* Which login name is displayed to the user in the UI.
* What information is asserted in `access_tokens` (specifically the `preferred_username` claim).
<Callout type="caution">
Setting a Primary Domain affects users.
If a user `coyote` exists in the global organization with the login name `[email protected]`, and you subsequently verify `acme.ch` for a specific organization, the global user's login name will be replaced with `coyote@{randomvalue.tld}`. ZITADEL will notify users affected by this change.
</Callout>
## Domain Verification Guide
If the **validate org domains** setting in [Domain Settings](./default-settings#domain-settings) is set to `true`, you must prove ownership of your domain via DNS or HTTP challenge.
<Callout type="info">
You can disable domain verification requirements in the [default settings](/guides/manage/console/default-settings#domain-settings) if you are running a self-hosted instance and do not require strict validation.
</Callout>
1. Navigate to your **Organization Settings**.
2. Select the menu entry **Verified domains**.
3. Click on the domain name you wish to verify. A dialog will appear offering DNS or HTTP challenge methods.
<img
width="400px"
src="/docs/img/console_verify_domain.png"
alt="Verify Domain Dialog"
/>
4. **DNS Challenge Example:** Create a TXT record with your DNS provider using the value provided by ZITADEL.
* [Cloudflare Guide](https://www.zoho.com/mail/help/adminconsole/cloudflare.html#alink1)
* [Squarespace Guide](https://support.squarespace.com/hc/en-us/articles/205812388-Domain-verification-with-a-TXT-Record-alternative-method-)
* [Name.com Guide](https://www.name.com/support/articles/115004972547-adding-a-txt-record)
* [EasyDNS Guide](https://kb.easydns.com/knowledge/how-to-make-a-dns-entry/)
5. Once verified, click **Verify**.
6. (Optional) Click **Set as primary** to make this the default domain for user login names.
<Callout type="caution">
Do not delete the DNS verification record after success. ZITADEL re-checks domain ownership periodically.
</Callout>
## Organization Settings
Organizations can inherit configuration from the instance defaults or override them with specific policies. Settings configured at the Organization level take priority over Default settings.
* [**Login Behavior and Access**](./default-settings#login-behavior-and-access): MFA options, passwordless authentication rules, and session lifetimes.
* [**Identity Providers**](./default-settings#identity-providers): Configure IDPs available specifically for this organization.
* [**Password Complexity**](./default-settings#password-complexity): Specific requirements for passwords (length, symbols, etc.).
* [**Lockout**](./default-settings#lockout): Max login attempts before an account is locked.
* [**Branding**](./default-settings#branding): Custom appearance for the login interface.
* [**Message Texts**](./default-settings#message-texts): Custom text and internationalization for emails.
* [**Login Interface Texts**](./default-settings#login-interface-texts): Custom text for the login UI.
* [**External Links**](./default-settings#external-links): Links to your specific Terms of Service, Privacy Policy, and Support.
### Applying Custom Branding
To apply a custom design (e.g., for a specific B2B customer):
1. Navigate to the Organization settings.
2. Configure the **Branding** section.
3. Ensure the **Login Behavior** on your **Project** is configured to allow organization-specific branding. Read more about project branding [here](./projects-overview#branding).
### Triggering Organization Context
When a user begins the login process, ZITADEL automatically determines the user's organization based on their entered login name and redirects them to the appropriate organization context. Users cannot select their organization manually.
By default, the ZITADEL Login uses the instance default settings. To trigger the specific settings (and branding) of an organization, you must provide the organization scope in your authentication request:
```bash
urn:zitadel:iam:org:id:{id}
```
This value is a [reserved scope](/apis/openidoauth/scopes#reserved-scopes) within ZITADEL.
apps/docs/content/guides/manage/console/organizations.mdx
+144
View File
@@ -0,0 +1,144 @@
---
title: ZITADEL Organizations
sidebar_label: Organizations
---
import OrgDescription from "../../../concepts/structure/_org_description.mdx";
import Column from "@/components/column";
## What is an organization?
An Organization is where your projects and users live. Looking at a B2B use case, an organization represents a business partner who typically has its own branding and has different access settings like additional federated login providers.
Users from one organization are separated from others.
## Create a new organization
To create a new organization, click on the organizations dropdown and then select “New organization”.
You can either create a new organization with your logged in user as the organization manager or directly create another account.
If you choose your logged in user as organization manager, a membership for the new organization will be added to the account.
<img
width="400px"
src="/docs/img/console_org_select.png"
alt="Select Organization"
/>
If you want to enable your customers to create their organization by themselves, we provide a creation form for an organization. `https://${CUSTOM_DOMAIN}/ui/login/register/org`
The customer needs to fill in the form with the organization name and the contact details.
<img
width="400px"
src="/docs/img/console_org_register.png"
alt="Register new organization"
/>
## How ZITADEL handles usernames
If your domain setting "user loginname must contain orgdomain" is disabled, your username will be unique within the whole instance.
At the moment the username only allows e-mail formatted input. (This will be changed soon)
### User Loginname must contain orgdomain
If this behavior is not suitable for you, ZITADEL has the option to suffix the usernames with the organization domain.
This setting is called **User Loginname must contain orgdomain** and is part of your [Domain settings](./default-settings#domain-settings).
Those loginnames consist of the format `{username}@{domainname}.${CUSTOM_DOMAIN}`.
If your user had the username `john.doe`, the generated loginname would be `[email protected]`.
This also means that only one user with the username `john.doe` can exist in your organization called `ACME`.
If you verify your domain name or add additional domains, ZITADEL will generate those additional login names for you.
If the organization would own the domain `acme.ch` and verify it, then the resulting loginname would be `[email protected]` in addition to the already generated `[email protected]`.
The user can now use either login name to authenticate with your application.
> Note: You can set this setting on your instance as well as your organizations. All available usernames are shown on the top of the user pages.
## Domain verification and primary domain
Once you have successfully registered your organization, ZITADEL will automatically generate a domain name for your organization (eg, acme.zitadel.cloud).
Users that you create within your organization will be suffixed with this domain name.
You can improve the user experience, by suffixing users with a domain name that is in your control.
If the "validate org domains" settings in the [Domain Settings](./default-settings#domain-settings) is set to true, you have to prove the ownership of your domain, by DNS or HTTP challenge.
If the setting is set to false, the created domain will automatically be set to verified.
An organization can have multiple domain names, but only one domain can be primary.
The primary domain defines which login name ZITADEL displays to the user, and what information gets asserted in access_tokens (`preferred_username`).
Please note that domain verification also removes the login name from all users, who might have used this combination in the global organization (ie. users not belonging to a specific organization).
Relating to our example with acme.ch: If a user ‘coyote’ exists in the global organization with the login name [email protected], then after verification of acme.ch, this login name will be replaced with `coyote@{randomvalue.tld}`.
ZITADEL will notify users affected by this change.
## Verify your domain name
<Callout>
You can also disable domain verification with DNS challenge in the [default settings](/guides/manage/console/default-settings#domain-settings).
</Callout>
1. Browse to your organization settings
2. Select the menu entry **Verified domains**
3. To start the domain verification click the domain name and a dialog will appear, where you can choose between DNS or HTTP challenge methods.
<img
width="400px"
src="/docs/img/console_verify_domain.png"
alt="Select Organization"
/>
4. For example, create a TXT record with your DNS provider for the used domain and click verify. ZITADEL will then proceed and check your DNS. Here are some useful links explaining how you can add TXT records for popular domain providers:
- [Cloudflare](https://www.zoho.com/mail/help/adminconsole/cloudflare.html#alink1)
- [Squarespace](https://support.squarespace.com/hc/en-us/articles/205812388-Domain-verification-with-a-TXT-Record-alternative-method-)
- [Name.com](https://www.name.com/support/articles/115004972547-adding-a-txt-record)
- [EasyDNS](https://kb.easydns.com/knowledge/how-to-make-a-dns-entry/)
- [DNS Made Easy](https://support.dnsmadeeasy.com/support/solutions/articles/47001001376-create-a-txt-record)
5. When the verification is successful you have the option to activate the domain by clicking **Set as primary**
<Callout type="warn">
Do not delete the verification code, as ZITADEL will re-check the ownership of your domain from time to time
</Callout>
## Organization Settings
In organizations you also have settings that have higher priority than on your default settings, and therefore override them.
Those settings are the same as your default settings.
> Note: that the following links, redirect to default settings to omit redundancy.
- [**Domain settings**](./default-settings#domain-settings): Whether users use their email or the generated username to login. Other Validation, SMTP settings
- [**Branding**](./default-settings#branding): Appearance of the login interface.
- [**Notification settings**](./default-settings#notification-settings): Setup Notification and Email Server settings for initialization-, verification- and other mails. Setup Twilio as SMS notification provider.
- [**Login Behavior and Access**](./default-settings#login-behavior-and-access): Multifactor Authentication Options and Enforcement, Define whether passkeys are allowed or not, Set Login Lifetimes and advanced behavior for the login interface.
- [**Identity Providers**](./default-settings#identity-providers): Define IDPs which are available for all organizations
- [**Password Complexity**](./default-settings#password-complexity): Requirements for Passwords ex. Symbols, Numbers, min length and more.
- [**Lockout**](./default-settings#lockout): Set the maximum attempts a user can try to enter the password or any (T)OTP method. When the number is exceeded, the user gets locked out and has to be unlocked.
- [**Verified domains**](/guides/manage/console/organizations-overview#usernames-and-domains): This is where you manage your organization specific domains which can be used to build usernames
- [**Message Texts**](./default-settings#message-texts): Text and internationalization for emails
- [**Login Interface Texts**](./default-settings#login-interface-texts): Text and internationalization for the login interface
- [**External Links**](./default-settings#external-links): Links to your own Terms of Service and Privacy Policy regulations, Help Page, Support email, documentation link...
If you need custom branding on a organization (for example in a B2B scenario, where organizations are allowed to use their custom design), navigate back to the home page, choose your organization in the header above, navigate to the organization settings and set the custom design here.
The behavior of the login page, applying custom design, is then defined on your projects detail page. Read more about it [here](./projects#branding)
## Show Organization Login
As you should know by now ZITADEL knows the concept of Organizations.
You can define [default settings](/guides/manage/console/default-settings) for your ZITADEL, or you can overwrite them for an [Organization](#organization-settings).
Per default the ZITADEL Login will always show what is defined per default. As soon as the Organization context is given, the settings defined on the specific organization can be triggered.
This means when you want to trigger the settings of an organization directly, make sure to send the organization scope in the authentication request.
```bash
urn:zitadel:iam:org:id:{id}
```
Read more about the [scopes](/apis/openidoauth/scopes#reserved-scopes) or try it out in our [OIDC Playground](https://zitadel.com/playgrounds/oidc).
## Default organization
On the Default settings page (`${CUSTOM_DOMAIN}`/ui/console/orgs) you can set an organization as default organization.
Click the "..." on the right hand side of the table and select "Set as default organization".
The current default organization is marked by a label "Default".
When no organization was selected (eg, with the auth request or through [Domain Discovery](/guides/solution-scenarios/domain-discovery)), then all users are allowed to login and users can self-register to this default organization.
apps/docs/content/guides/manage/console/overview.mdx
+29
View File
@@ -0,0 +1,29 @@
---
title: ZITADEL Management Console
sidebar_label: Overview
---
## What is management console?
Management Console is the Dashboard UI for your instance. It can be accessed from all configured Custom Domains, defined in the Customer Portal.
The management console is used to configure global default settings and can be used by multiple Managers.
Read more about [Console Managers](./managers) here.
It can also be used by your application users to modify their profile, although we recommend that you build your own User Interface.
When you are logged in, you are greeted by the home page. This page allows you to set shortcuts to settings and projects.
The management console has a context switcher on the **top-left** where your current organization is set.
Depending on your use case, multiple organizations can be created (B2B) or you can stick to your global organization (B2C). To get an understanding of your use cases and how we recommend setting up your organizations, read the [Solution Scenario](../../solution-scenarios/introduction) guides.
<img
src="/docs/img/guides/console/contextswitcher.png"
alt="Context switcher"
width="400px"
/>
If your new to management console, you'll probably want to set some settings initially. Continue reading Default settings on the next page.
## Prevent management console access
In some use cases you want to prevent users from accessing the ZITADEL management console.
Please follow this [guide](/guides/solution-scenarios/restrict-console) to achieve that.
apps/docs/content/guides/manage/console/projects-overview.mdx
+138
View File
@@ -0,0 +1,138 @@
---
title: Organize applications, services, and roles with projects
sidebar_label: Projects
sidebar_position: 4
---
import ProjectDescription from "../../../concepts/structure/_project_description.mdx";
## What is a project?
<ProjectDescription components={props.components} name="ProjectDescription" />
A Project is the vessel that holds your Applications and Roles. It defines the security context for a specific software solution.
### Example Scenario
Imagine you are building a **Point of Sales (POS)** platform. In ZITADEL, you would create one Project (e.g., named `POS`).
* **Applications:** Your web portal for administration, your iOS app, and your Android app would all be defined as **Applications** within this single Project.
* **Roles:** You would create **Roles** (e.g., `admin`, `cashier`, `viewer`) inside this Project.
* **Authorization:** All applications in this project share these roles, allowing you to create unified authorizations for your users across all platforms.
![POS Project](../../../../public/img/guides/console/posproject.png)
## Core Components
### Applications
Applications define the different clients (web apps, native mobile apps, server-side APIs) that share the same roles and security context.
At the moment, we support OIDC and almost every OAuth2 client. We'll be expanding this with SAML shortly.
Go to [Applications](./applications-overview) for more details.
### Roles
A role consists of different attributes, but only the **Key** is relevant to the authorization and must be unique within the project.
* **Key:** The identifier used in code (e.g., `role.admin`).
* **Display Name:** A human-readable name for the UI.
* **Group:** Enables better handling in the ZITADEL Management Console (e.g., giving a user all roles of a specific group).
Read more about managing roles [here](./roles).
## The Default Project
When creating a new ZITADEL instance, you will find an automatically created project in the first organization.
This **Default Project** (named "ZITADEL") protects the ZITADEL Management Console and APIs.
<Callout type="caution">
We do not recommend changing any settings in the Default Project or using it for your own applications, as this could influence the behavior of ZITADEL itself.
</Callout>
![Default Project](../../../../public/img/guides/solution-scenarios/console-default-project.png)
## Create a Project
To create a project:
1. Navigate to your Organization in the Console.
2. Go to **Projects** (or visit `https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/projects`).
3. Click the **Create New Project** button.
<img
alt="Empty Project"
src="/docs/img/console_projects_empty.png"
width="270px"
/>
4. Enter your project name and continue.
## Granted Projects (B2B)
A powerful feature of ZITADEL is the ability to **Grant** a project to other organizations. This is essential for B2B scenarios where you sell your software to business partners.
* **The Concept:** You enable another organization to use your Project.
* **Delegation:** The granted organization can manage the authorizations of *their own users* for your project. They can assign the roles you defined to their employees without your intervention.
* **Isolation:** You can select specifically which roles are available to the granted organization. This allows you to restrict features (e.g., "Premium" roles) per customer.
Using the POS example above: You could grant the `POS` project to a partner organization. That partner can then log in with their own domain, use their own branding, and manage their own cashier users, all while using your underlying application structure.
<img
alt="Granted project"
src="/docs/img/guides/console/grantedprojectgrid.png"
width="320px"
/>
### How to Grant a Project
1. Navigate to the Project you want to share (e.g., `POS`).
2. In the **Grants** section, click **New**.
<img src="/docs/img/guides/console/grantsmenu.png" alt="Grants" width="170px" />
3. Enter the **Domain** of the partner organization you want to grant access to.
* *Tip: If you don't know the domain, navigate to the Organization detail page to find it.*
4. Search and select the organization.
5. Select the **Roles** you want to grant to this organization and click **Save**.
## Project Settings
You can customize the behavior of your project, particularly regarding how login screens look and how tokens are issued.
### Branding
If you have different designs for your organizations (Private Labeling), you can define the login behavior on the project detail page.
<img
src="/docs/img/guides/console/projectbranding.png"
alt="Project branding"
width="400px"
/>
| Setting | Description |
| :--- | :--- |
| **Unspecified** | If nothing is specified, the system default settings will trigger. |
| **Enforce project's policy** | This forces the branding of the organization that *owns* the project throughout the entire login process. Useful if you want your users to always see *your* brand, even if they belong to a partner org. |
| **Allow login user policy** | The login starts with the project's branding. However, as soon as the user is identified (e.g., by entering their email), the branding switches to match the user's organization. |
In a B2B use case, you would typically use **Allow login user policy**. If you want to skip the detection step, you can preselect an organization using the [primary domain scope](/apis/openidoauth/scopes#reserved-scopes) (e.g., `urn:zitadel:iam:org:domain:primary:{domainname}`).
### Role Settings
You can configure strict security checks regarding roles during authentication.
<img
src="/docs/img/guides/console/rolesettings.png"
width="700px"
alt="Role settings"
/>
* **Assert Roles on Authentication:** Role information is sent from the Userinfo endpoint (and in tokens, depending on app settings).
* **Check authorization on Authentication:** Users are **only** allowed to login if they have at least one role assigned for this project. If they have no roles, access is denied immediately.
* **Check for Project on Authentication:** Checks if the user's organization actually has a grant for this project. If not, the user cannot be authenticated.
### Roles in Tokens
If you want roles to appear directly inside your Access or ID Tokens (to avoid calling the Userinfo endpoint), you must enable this per application.
1. Navigate to your **Application**.
2. Open **Token Settings**.
3. Check **Assert Roles on Authentication**.
<img
src="/docs/img/guides/console/tokenroles.png"
width="700px"
alt="Roles in token"
/>
You can learn more about Application and Token settings [here](./applications-overview).
apps/docs/content/guides/manage/console/projects.mdx
+109
View File
@@ -0,0 +1,109 @@
---
title: ZITADEL Projects
sidebar_label: Projects
---
import ProjectDescription from "../../../concepts/structure/_project_description.mdx";
## What is a project?
<ProjectDescription components={props.components} name="ProjectDescription" />
### Example
If you'd build a Point of Sales Platform, you would have one Project (maybe called `POS`) and all your applications (one Webapplication for administration, and your mobile applications for your users iOS and Android), would be part of it.
You would have to create roles for administration and your clients in this very project, and then create authorizations based on them.
![](../../../../public/img/guides/console/posproject.png)
## Create a project
To create a project, navigate to your organization, then projects or directly via `https://${CUSTOM_DOMAIN}.zitadel.cloud/ui/console/projects`, and then click the button to create a new project.
<img
alt="Empty Project"
src="/docs/img/console_projects_empty.png"
width="270px"
/>
then enter your project name and continue.
## What is a granted project?
Now imagine you could use the POS platform from the example not only for yourself but sell it to other business partners too.
Those partners would maybe have the need to have their own domain, their own branding and add additional social login options.
Setting this up in ZITADEL is very easy since all organizations can overwrite their settings.
You would only need a method to grant them access.
To add a grant to another organization is done from the project itself. Navigate to grants and hit the new button.
Now, enter the domain of the partner organization (if you can't remember it, navigate to the organization and pick it up from the detail page), hit search and then continue.
Now select the roles you want this organization to use and save.
This enables you to lock a certain organization out of a feature if you don't want their users to use it.
You can learn more about roles [here](./roles).
Organizations can then create authorizations for their users on their own. The project is shown them separated from their own projects.
<img
alt="Granted project"
src="/docs/img/guides/console/grantedprojectgrid.png"
width="320px"
/>
## Grant a project
1. Visit the project `POS` that you have created before, then in the section **Grants** click **New**.
<img src="/docs/img/guides/console/grantsmenu.png" alt="Grants" width="170px" />
2. Search the organization you want to grant using the auto complete input and continue.
3. Select some roles you would like to grant to the organization and confirm.
4. You should now see the granted organization in the section **grants**.
## Project Settings
### Branding
If you have different designs for your organizations or probably and use project grants, you can define the login behavior on the project detail page.
<img
src="/docs/img/guides/console/projectbranding.png"
alt="Project branding"
width="400px"
/>
You can choose from
| Setting | Description |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Unspecified | If nothing is specified the default will trigger. (System settings) |
| Enforce project's policy | This setting will enforce the private labeling of the organization of the project through the whole login process. |
| Allow login user policy | With this setting first the private labeling of the organization of the project will trigger. As soon as the user and its organization is identified by ZITADEL, the settings will change to the organization of the user. |
In a B2B use case, you would typically use the organization setting. If you want to omit organization detection, you can preselect an organization with the [primary domain scope](/apis/openidoauth/scopes#reserved-scopes) (ex. `urn:zitadel:iam:org:domain:primary:{domainname}`).
### Role settings
Below the branding settings, you can check different checkboxes to get even more custom behavior on authentication.
- **Assert Roles on Authentication**:
Role information is sent from Userinfo endpoint and depending on your application settings in tokens and other types.
- **Check authorization on Authentication**: If set, users are only allowed to authenticate if any role is assigned to their account.
- **Check for Project on Authentication**:
It is checked whether the user's organization has this project. If not, the user cannot be authenticated.
<img
src="/docs/img/guides/console/rolesettings.png"
width="700px"
alt="Role settings"
/>
If you want to have roles in your token, this has to be set in your applications as this is dependent on your application type. Navigate to your application and check this setting if you want so.
<img
src="/docs/img/guides/console/tokenroles.png"
width="700px"
alt="Roles in token"
/>
You can learn more about [Application and Token settings](./applications#token-settings) in the next section.
apps/docs/content/guides/manage/console/roles.mdx
+54
View File
@@ -0,0 +1,54 @@
---
title: ZITADEL Roles and Authorizations
sidebar_label: Roles and Authorizations
---
If you would build out the [POS use case example](./projects#example) you would probably need an application for administration.
In this application you would probably have somebody accessing as an accountant and somebody as an administrator, who is somebody with enhanced rights.
To build this out, you would have to add this distinction as roles.
To add roles, jump to the section **Roles** and create those new roles with the following values
- Key: admin
- Display Name: Administrator
- Group: Administration
and
- Key: account
- Display Name: Accountant
- Group: Administration
<img src="/docs/img/guides/console/addrole.png" alt="Add roles" />
The **Key** is used for coding (can then for example be requested in the ID Token).
The **Display Name** is just for you remembering its use case
The **Group** is for making multiple roles selectable more easy.
<img src="/docs/img/guides/console/roles.png" width="750px" alt="Roles" />
> The role client is for an other application of the project `POS`, as all possible roles from your POS applications are defined in your project.
## Authorizations
Now to make use of this roles, add an authorization.
An authorization combines a user of your organization with one or multiple roles.
> You can also add users of other organizations. Click on the hint below the username field to create an [external user grant](/concepts/features/external-user-grant).
<img src="/docs/img/guides/console/authusers.png" width="500px" alt="Auth users" />
If your wanted to test your application with your own user, navigate to the **Authorizations** section under your project and click on **new**.
Type your username, hit continue, select the roles you want your user to have and save. If you want to add all roles of the Administration group, you can click on the group to select all.
<img
src="/docs/img/guides/console/authorization.png"
width="750px"
alt="Authorization"
/>
Now you can retrieve those roles in your application. ZITADEL has [multiple settings](./projects#project-settings) for you to access them more easily. Navigate to the **General** section of your project and check your needed ones.
> Note: We did set up our authorizations from projects, but this can be achieved from multiple locations in console. You can view and add authorizations from your organization, your projects, or from your users page.
apps/docs/content/guides/manage/console/users-overview.mdx
+107
View File
@@ -0,0 +1,107 @@
---
title: Users
sidebar_label: Users
sidebar_position: 3
---
import CreateUser from './_create-user.mdx';
## Overview
ZITADEL supports authentication and authorization for different user types. We mainly differentiate between **Human Users** (interactive) and **Service Users** (machine-to-machine).
<img src="/docs/img/guides/console/usersmenu.png" width="420px" alt="User types" />
## Types of Users
### Human Users
Human users represent actual people who log in via an interactive interface (e.g., a login page).
* **Profile:** Has an email address, password, and optional profile data (phone, nickname, gender, language).
* **Authentication:** Can authenticate via password, multiple factors (MFA), or passwordless authentication (Passkeys).
* **Flow:** The application redirects the user to ZITADEL, which handles the credentials and issues a token to the application.
Read more on how to [login users with ZITADEL](/guides/integrate/login/login-users).
### Service Users (Machine Accounts)
Service users represent machines, backend services, or IoT devices requiring non-interactive access.
* **Profile:** Only has a name, description, and username.
* **Authentication:** Authenticates via **JWT Profile** or **Personal Access Tokens (PAT)**. Both methods support expiration settings.
* **Usage:** Primarily used to gain access to the ZITADEL Management API or to secure backend-to-backend communication.
To see how service users are utilized in practice, check out our [NextJS B2B Demo application](https://github.com/zitadel/zitadel-nextjs-b2b).
### Federated Users
Federated users are identities managed by a third-party Identity Provider (IdP) such as Google, Azure AD, or GitHub.
* **Identity Brokering:** Users log in via the external IdP ("Single Sign-On").
* **Account Linking:** Federated identities are [linked](../../../concepts/features/account-linking) to internal ZITADEL users to facilitate role assignment and audit trails.
### External Users
In a multi-tenancy architecture, users are typically isolated within [Organizations](./organizations-overview).
However, using [External User Grants](../../../concepts/features/external-user-grant), an organization can invite users from *another* organization to access their projects. These invited users are referred to as **External Users** within the context of the inviting organization.
### Managers
Any user—whether Human or Service User—can be assigned an [Administrator Role](/concepts/structure/managers).
A user with an administrator role is not just an end-user of your application but also has permissions to manage specific aspects of the ZITADEL instance, organization, or project (e.g., `ORG_OWNER`, `PROJECT_OWNER`).
## Considerations
### Uniqueness of Users
* **Scope:** Users exist strictly within **one** [Organization](./organizations-overview). It is currently not possible to move users between organizations.
* **Identifier:** User accounts are uniquely identified by their `id` or their `loginname` combined with the `organization domain` (e.g., `[email protected]`).
* **Emails:** You can reuse the same email address for different user accounts across organizations.
### Structuring User Pools
How you organize users depends on your scenario:
* **B2B / Multi-Tenancy:** We recommend creating separate organizations for each business customer (e.g., based on their domain). Grant your projects to these organizations so they can manage their own users.
* **B2C / CIAM:** You might want to store all users in a single organization and enable a specific set of social logins for that organization.
<Callout type="info">
You can only verify a domain (e.g., `acme.com`) on **one** organization. If multiple teams share the same email domain but need separate management, they might need to be consolidated into a single organization.
</Callout>
### Hierarchy
ZITADEL does not enforce a native hierarchy or inheritance for users or organizations. We recommend structuring users along the smallest unit of groups (Organizations). You can use organization metadata or your own business logic to map complex hierarchies if needed.
## Managing Users
### Create User
<CreateUser components={props.components} />
### Metadata
ZITADEL provides a key-value storage system for users, which is essential for building complex applications.
**Example Use Case:**
In a Point of Sales application, you could add a `stripeCustomerId` as a metadata key to a user. Your client application can then read this metadata to fetch payment details directly from the Stripe API.
<img
width="460px"
src="/docs/img/guides/console/usermetadata.png"
alt="User Metadata"
/>
**Accessing Metadata:**
Metadata can be requested via the Auth and Management APIs, the Userinfo endpoint, or asserted directly into the ID Token.
1. **Userinfo Endpoint:** Add the scope `urn:zitadel:iam:user:metadata` to your authentication request.
2. **ID Token:** To include metadata in the token, navigate to your **Application Settings** and toggle **User Info inside ID Token**.
<img
src="/docs/img/guides/console/appidtokensettings.png"
width="650px"
alt="ID Token settings"
/>
### Authorizations
User authorizations (roles) are displayed on user profile pages.
To access these roles in your application:
* **Userinfo Endpoint:** Check the **Assert roles on authentication** box in your [Project Settings](./roles#authorizations).
* **ID Token:** Toggle **User roles inside ID Token** in your [Application Settings](./applications-overview).
## References
- [Manage users in the Management Console](./users-overview#managing-users)
- [Migrate to ZITADEL](/guides/migrate/introduction)
- [User onboarding and registration](/guides/integrate/onboarding)
apps/docs/content/guides/manage/console/users.mdx
+57
View File
@@ -0,0 +1,57 @@
---
title: ZITADEL Users
sidebar_label: Users
---
import CreateUser from './_create-user.mdx';
ZITADEL differs two different types of users:
- Users (Humans)
- Service Users (Machine Accounts)
<img src="/docs/img/guides/console/usersmenu.png" width="420px" alt="User types" />
A human user has an email address and a password, and can additionally save information about phone, nickname, gender, language.
A service user only has a name and a description aside his username.
A service user can be authenticated with JWT profile or Personal Access Tokens. Both methods can specify an expiry.
A human user can authenticate itself with his password, add multiple factors for additional security, and enable passkey authentication.
Service users are primarily used to gain access for a backend service or iot device. The fact that service users can also be ZITADEL managers is used to restrict access to specific projects or organizations.
To get an understanding on how service users are used, take a look at our NextJS B2B Demo application.
## Create User
<CreateUser components={props.components} />
## Metadata
When building complex applications, having the possibility to add metadata is essential.
ZITADEL provides a key value storage for users on the user pages.
Just navigate to the section **Metadata** and click on **edit**.
> In our [Point of Sales example](./projects#example) from the projects guide, you could add a `stripeCustomerId` as a metadata key. In your client application you could then easily fetch the customer from Stripe APIs for your payments.
<img
width="460px"
src="/docs/img/guides/console/usermetadata.png"
alt="User Metadata"
/>
Metadata can requested via our auth and management APIs, from userinfo endpoint or ID Token.
To get your metadata from the userinfo endpoint, add `urn:zitadel:iam:user:metadata` to your authentication request. Take a look at our reserved scopes [here](/apis/openidoauth/scopes#reserved-scopes) or take a look at our [metadata guide](../customize/user-metadata).
You can then toggle **User Info inside ID Token** in your application settings, if you need this information in the ID Token too.
<img
src="/docs/img/guides/console/appidtokensettings.png"
width="650px"
alt="ID Token settings"
/>
## Authorizations
As described in [Roles and Authorizations](./roles), authorizations are shown on user profile pages too.
If you need user roles in the user info endpoint, check the **Assert roles on authentication** checkbox in your project as described in [Authorizations](./roles#authorizations).
If you need them in your ID Token, toggle **User roles inside ID Token** in application settings.
apps/docs/content/guides/manage/customize/behavior.mdx
+50
View File
@@ -0,0 +1,50 @@
---
title: Behavior Customization
---
In this guide, you will create a [ZITADEL action](../../../concepts/features/actions).
After users register using an external identity provider, the action assigns them a role.
## Prerequisites
Before you start, make sure you have everything set up correctly.
- You need to be at least a ZITADEL _ORG_OWNER_
- Your ZITADEL organization needs to have the actions feature enabled. - [Your ZITADEL organization needs to have at least one external identity provider enabled](../../integrate/identity-providers/introduction)
- [You need to have at least one role configured for a project](../console/projects)
## Copy some information for the action
1. Select the **Projects** navigation item.
1. Select a project that has a role configured.
1. Copy the projects **Resource Id** on the screens top right.
1. Scroll to the **ROLES** section and note some roles key.
## Create the action
1. Select the **Actions** navigation item.
1. In the **Actions <i className="las la-code"></i>** section, select the **+ New** button.
1. Give the new action the name `addGrant`.
1. Paste this snippet into the multiline textfield.
1. Replace the snippets placeholders and select **Save**.
```js reference
https://github.com/zitadel/actions/blob/main/examples/add_user_grant.js
```
## Run the action when a user registers
Now, make the action hook into the [external authentication flow](/apis/actions/external-authentication).
1. In the **Flows <i className="las la-exchange-alt"></i>** section, select the **+ New** button.
1. Select the **Flow Type** _External Authentication_.
1. Select the **Trigger Type** _Post Creation_.
1. In the **Actions** dropdown, check _addGrant_.
1. Select the **Save** button.
New users automatically are assigned a role now if they register by authenticating with an external identity provider.
## What's next?
- [Read more about the concepts around actions](/concepts/features/actions)
- [Read more about all the options you have with actions](/guides/manage/console/actions-overview)
apps/docs/content/guides/manage/customize/branding.mdx
+58
View File
@@ -0,0 +1,58 @@
---
title: Brand Customization
---
ZITADEL offers various customization options for your projects brand design. The branding can be configured on two different levels.
The configuration on the instance level will set the default settings, which are triggered for all users if not overwritten on an organization specifically.
The second possibility is to configure it on each organization. This guide will describe the second possibility.
For this head over to the Branding Setting on your Organization Page.
## How it works
You are able to customize the light and a dark mode separately.
All your changes will be shown in the preview window on the right side.
As soon as you are happy with your configuration click the "Apply configuration" button.
After this your settings will trigger in your system. The login and the emails will be sent with your branding.
## Settings
![](../../../../public/img/console_private_labeling.png)
### Logo
Upload your logo for the chosen theme, as soon as it is uploaded the preview on the right side of the screen should show it.
### Colors
In the next part you can configure your colors.
Background color is self-explanatory, the primary color will be used for buttons, links and some highlights.
The warn color is used for all the error messages and warnings and the font color for texts.
### Font
Last step to apply to your branding is the font upload.
The best way is to upload a ttf file after a successful upload you will see it in the font part, but not in the preview.
### Advanced Settings
In the advanced behavior you can choose if the loginname suffix (domain e.g [email protected]) should be shown in the loginname screen or not and if the “ZITADEL watermark” should be hidden.
## Trigger the private labeling for the login
If you like to trigger your settings for your applications you have different possibilities.
### 1. Primary Domain Scope
Send a [reserved scope](/apis/openidoauth/scopes) with your [authorization request](../../integrate/login/oidc/login-users) to trigger your organization.
The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to login.
You can use our [OpenID Authentication Request Playground](https://zitadel.com/playgrounds/oidc) to learn more about how to trigger an [organization's policies and branding](https://zitadel.com/playgrounds/oidc#organization-policies-and-branding).
### 2. Setting on your Project
Set the private labeling setting on your project to define which branding should trigger.
## Reset to default
If you don't like your customization anymore click the "reset policy" button.
All your settings will be removed and the default settings of the system will trigger.
apps/docs/content/guides/manage/customize/notification-providers.mdx
+167
View File
@@ -0,0 +1,167 @@
---
title: SMS, SMTP and HTTP Provider for Notifications
sidebar_label: Notification Providers
---
ZITADEL can send messages to users via different notification providers, such as SMS, SMTP, or Webhook (HTTP Provider).
While you can add multiple providers to different channels, messages will only be delivered via the active provider.
Message and notification texts can be [customized](./texts) for an instance or for each organization.
## SMS providers
ZITADEL integrates with Twilio as SMS provider.
## SMTP providers
For easy configuration, there are some integration templates available such as:
- Amazon SES
- Mailgun
- Mailjet
- SendGrid
- ...
Aside from those, it is also possible to configure a generic SMTP provider. With a generic SMTP provider you specify what
the SMTP server, username and what kind of auth method you want to use. Currently, the Console only supports plain auth.
However, with [the API's](https://zitadel.com/docs/apis/resources/admin/admin-service-add-email-provider-smtp) you can
configure XOAUTH2 as well.
<Callout title="Default Provider ZITADEL Cloud">
A default SMTP provider is configured for ZITADEL Cloud customers.
This provider meant for development and testing purposes and you must replace this provider with your custom SMTP provider for production use cases to guarantee security and reliability of your service.
</Callout>
## Webhook / HTTP provider
Webhook (HTTP Provider) allows you to fully customize the messages and use integrate with any provider or custom solution to deliver the messages to users.
A provider with HTTP type will send the messages and the data to a pre-defined webhook as JSON.
### Configuring a HTTP provider
<Tabs>
<Tab value="sms" label="SMS" default>
First [add a new SMS Provider of type HTTP](/reference/api/admin/zitadel.admin.v1.AdminService.AddSMSProviderHTTP) to create a new HTTP provider that can be used to send SMS messages:
```bash
curl -L 'https://${CUSTOM_DOMAIN}/admin/v1/sms/http' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ${TOKEN}' \
-d '{
"endpoint": "http://relay.example.com/provider",
"description": "provider description"
}'
```
Where `endpoint` defines the Webhook endpoint to which the data should be sent to.
The result will contain an ID of the provider that we need in the next step.
You can configure multiple SMS providers at the same time.
To use the HTTP provider you need to [activate the SMS provider](/reference/api/admin/zitadel.admin.v1.AdminService.ActivateSMSProvider):
```bash
curl -L 'https://${CUSTOM_DOMAIN}/admin/v1/sms/:id/_activate' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ${TOKEN}' \
-d '{}'
```
The `id` is the provider's ID from the previous step.
See full API reference for [SMS Providers](/reference/api/admin) for more details.
</Tab>
<Tab value="email" label="Email">
First [add a new Email Provider of type HTTP](/reference/api/admin/zitadel.admin.v1.AdminService.AddEmailProviderHTTP) to create a new HTTP provider that can be used to send Email messages:
```bash
curl -L 'https://${CUSTOM_DOMAIN}/admin/v1/email/http' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ${TOKEN}' \
-d '{
"endpoint": "http://relay.example.com/provider",
"description": "provider description"
}'
```
Where `endpoint` defines the Webhook endpoint to which the data should be sent to.
The result will contain an ID of the provider that we need in the next step.
You can configure multiple Email providers at the same time.
To use the HTTP provider you need to [activate the Email provider](/reference/api/admin/zitadel.admin.v1.AdminService.ActivateEmailProvider):
```bash
curl -L 'https://${CUSTOM_DOMAIN}/admin/v1/email/:id/_activate' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer ${TOKEN}' \
-d '{}'
```
The `id` is the provider's ID from the previous step.
See full API reference for [Email Providers](/reference/api/admin/zitadel.admin.v1.AdminService.ListEmailProviders) for more details.
</Tab>
</Tabs>
### HTTP provider payload
In case of the Twilio and Email providers, the messages will be sent as before, in case of the HTTP providers the content of the messages is the same but as a HTTP call.
Here an example of the body of an payload sent via Email HTTP provider:
```json
{
"contextInfo": {
"eventType": "user.human.initialization.code.added",
"provider": {
"id": "285181292935381355",
"description": "test"
},
"recipientEmailAddress": "[email protected]"
},
"templateData": {
"title": "Zitadel - Initialize User",
"preHeader": "Initialize User",
"subject": "Initialize User",
"greeting": "Hello GivenName FamilyName,",
"text": "This user was created in Zitadel. Use the username Username to login. Please click the button below to finish the initialization process. (Code 0M53RF) If you didn't ask for this mail, please ignore it.",
"url": "http://example.zitadel.com/ui/login/user/init?authRequestID=\u0026code=0M53RF\u0026loginname=Username\u0026orgID=275353657317327214\u0026passwordset=false\u0026userID=285181014567813483",
"buttonText": "Finish initialization",
"primaryColor": "#5469d4",
"backgroundColor": "#fafafa",
"fontColor": "#000000",
"fontFamily": "-apple-system, BlinkMacSystemFont, Segoe UI, Lato, Arial, Helvetica, sans-serif",
"footerText": "InitCode.Footer"
},
"args": {
"changeDate": "2024-09-16T10:58:50.73237+02:00",
"code": "0M53RF",
"creationDate": "2024-09-16T10:58:50.73237+02:00",
"displayName": "GivenName FamilyName",
"firstName": "GivenName",
"lastEmail": "[email protected]",
"lastName": "FamilyName",
"lastPhone": "+41791234567",
"loginNames": [
"Username"
],
"nickName": "",
"preferredLoginName": "Username",
"userName": "Username",
"verifiedEmail": "[email protected]",
"verifiedPhone": ""
}
}
```
There are 3 elements to this message:
- `contextInfo`, with information on why this message is sent like the Event, which Email or SMS provider is used and which recipient should receive this message
- `templateData`, with all texts and format information which can be used with a template to produce the desired message
- `args`, with the information provided to the user which can be used in the message to customize
apps/docs/content/guides/manage/customize/restrictions.mdx
+18
View File
@@ -0,0 +1,18 @@
---
title: Feature Restrictions
---
New self-hosted and [ZITADEL Cloud instances](https://zitadel.com/signin) are unrestricted by default.
Self-hosters can change this default using the DefaultInstance.Restrictions configuration section.
Users with the role IAM_OWNER can change the restrictions of their instance using the [Feature Restrictions Admin API](/reference/api/admin).
Currently, the following restrictions are available:
- *Disallow public organization registrations* - If restricted, only users with the role IAM_OWNERS can create new organizations. The endpoint */ui/login/register/org* returns HTTP status 404 on GET requests, and 409 on POST requests.
- *AllowedLanguages* - The following rules apply if languages are restricted:
- Only allowed languages are listed in the OIDC discovery endpoint */.well-known/openid-configuration*.
- Login UI texts are only rendered in allowed languages.
- Notification message texts are only rendered in allowed languages.
- Custom Texts can be created for disallowed languages as long as ZITADEL supports that language. Therefore, all texts can be customized before allowing a language.
Feature restrictions for an instance are intended to be configured by a user that is managed within that instance.
However, if you are self-hosting and need to control your virtual instances usage, [read about the APIs for limits and quotas](/self-hosting/manage/usage_control) that are intended to be used by system users.
apps/docs/content/guides/manage/customize/texts.mdx
+73
View File
@@ -0,0 +1,73 @@
---
title: Customized Texts
---
You are able to customize the texts used from ZITADEL. This is possibly on the instance or organization level.
## Message Texts
Sometimes the users will get an email or phone message from ZITADEL (e.g Password Reset Request).
ZITADEL already has some good standard texts, but maybe you would like to customize it for your organization.
Go to the message text policy on your organization and you will find the different kinds of messages that are sent from ZITADEL.
Choose the template and the language you like to edit.
You can now change all the texts from a message.
As soon as you click into a input field you will see some attribute chips below the field.
These are the parameters you can include on this specific message.
![](../../../../public/img/console_message_texts.png)
## Login Texts
Like the message texts you are also able to change the texts on the login interface.
First choose the screen and the language you like to edit.
You will see the default texts in the input field and you can overwrite them by typing into the box.
![](../../../../public/img/console_login_texts.png)
## Reset to default
If you don't like your customization anymore click the "reset policy" button.
All your settings will be removed and the default settings of the system will trigger.
## Internationalization / i18n
ZITADEL is available in the following languages
- German (de)
- English (en)
- Spanish (es)
- French (fr)
- Indonesian (id)
- Italian (it)
- 日本語 (ja)
- Polish（pl）
- 简体中文（zh）
- Bulgarian (bg)
- Portuguese (pt)
- Macedonian (mk)
- Czech (cs)
- Russian (ru)
- Dutch (nl)
- Swedish (sv)
- Hungarian (hu)
- 한국어 (ko)
- Romanian (ro)
- Turkish (tr)
- Ukrainian (uk)
- Arabic (ar)
A language is displayed based on your agent's language header.
If a users language header doesn't match any of the supported or [restricted](#restrict-languages) languages, the instances default language will be used.
If you need support for a specific language we highly encourage you to [contribute translation files](https://github.com/zitadel/zitadel/blob/main/CONTRIBUTING.md) for the missing language.
## Restrict Languages
If you only want to enable a subset of the supported languages, you can configure the languages you'd like to allow using the [restrictions API](./restrictions).
The login UI and notification messages are only rendered in one of the allowed languages and fallback to the instances default language.
Also, the instances OIDC discovery endpoint will only list the allowed languages in the *ui_locales_supported* field.
All language settings are also configurable in the management consoles *Languages* default settings.
![](../../../../public/img/guides/console/languages.png)
apps/docs/content/guides/manage/customize/user-metadata.mdx
+227
View File
@@ -0,0 +1,227 @@
---
title: User Metadata
---
This guide shows you how to request metadata from a user.
ZITADEL offers multiple methods to retrieve metadata.
Pick the one that works best for your solution.
## Use cases for metadata
Typical use cases for user metadata include:
- Link the user to an internal identifier (eg, userId, contract number, etc.)
- Save custom user data when registering a user
- Route upstream traffic based on user attributes
## Before you start
Before you start you need to add some metadata to an existing user.
You can do so by using [Console](../console/users) or [setting user metadata](/reference/api/management/zitadel.management.v1.ManagementService.SetUserMetadata) through the management API.
Most of the methods below require you to login with the correct user while setting some scopes.
Make sure you pick the right user when logging into the test application.
Use the [OIDC authentication request playground](https://zitadel.com/playgrounds/oidc) or the configuration of an [example client](/sdk-examples/introduction) to set the required scopes and receive a valid access token.
<Callout title="Getting a token">
In case you want to test out different settings configure an application with code flow (PKCE).
Grab the code from the url parameter after a successful login and exchange the code for tokens by calling the [token endpoint](/apis/openidoauth/endpoints#token-endpoint).
You will find more information in our guides on how to [authenticate users](/guides/integrate/login/oidc/login-users).
</Callout>
## Use tokens to get user metadata
Use one of these methods to get the metadata for the currently logged in user.
In case you want to manage metadata for other users than the currently logged in user, then you must use the [management service](#manage-user-metadata-through-the-management-api).
### Request metadata from userinfo endpoint
With the access token we can make a request to the [userinfo endpoint](/apis/openidoauth/endpoints#introspection-endpoint) to get the user's metadata.
This method is the preferred method to retrieve a user's information in combination with opaque tokens, to insure that the token is valid.
You must pass the [reserved scope](/apis/openidoauth/scopes#reserved-scopes) `urn:zitadel:iam:user:metadata` in your authentication request.
If you don't include this scope the response will contain user data, but not the metadata object.
Request the user information by calling the [userinfo endpoint](/apis/openidoauth/endpoints#introspection-endpoint):
```bash
curl --request GET \
--url "https://${CUSTOM_DOMAIN}/oidc/v1/userinfo" \
--header "Authorization: Bearer $ACCESS_TOKEN"
```
Replace `$ACCESS_TOKEN` with your user's access token.
The response will look something like this
```json
{
"email": "[email protected]",
"email_verified": true,
"family_name": "Runner",
"given_name": "Road",
"locale": "en",
"name": "Road Runner",
"preferred_username": "[email protected]",
"sub": "166.....729",
"updated_at": 1655467738,
//highlight-start
"urn:zitadel:iam:user:metadata": {
"ContractNumber": "MTIzNA"
}
//highlight-end
}
```
You can grab the metadata from the reserved claim `"urn:zitadel:iam:user:metadata"` as key-value pairs.
Note that the values are base64 encoded.
So the value `MTIzNA` decodes to `1234`.
### Send metadata inside the ID token
You might want to include metadata directly into the ID Token.
For that you need to enable "User Info inside ID Token" in your application's settings.
![](../../../../public/img/console_projects_application_token_settings.png)
Now request a new token from ZITADEL by logging in with the user that has metadata attached.
Make sure you log into the correct client/application where you enabled the settings.
The result will give you something like:
```json
{
"access_token": "jZuRixKQTVecEjKqw...kc3G4",
"token_type": "Bearer",
"expires_in": 43199,
"id_token": "ey...Ww"
}
```
When you decode the value of `id_token`, then the response will include the metadata claim:
```json
{
"amr": ["password", "pwd", "mfa", "otp"],
"at_hash": "lGIblkTr8faHz2zd0oTddA",
"aud": [
"170086824411201793@portal",
"209806276543185153@portal",
"170086774599581953"
],
"auth_time": 1687418556,
"azp": "170086824411201793@portal",
"c_hash": "dA3wre4ytCJCn11f7cIm0A",
"client_id": "1700...1793@portal",
"email": "[email protected]",
"email_verified": true,
"exp": 1687422272,
"family_name": "Runner",
"given_name": "Road",
"iat": 1687418672,
"iss": "https://...-abcd.zitadel.cloud",
"locale": null,
"name": "Road Runner",
"preferred_username": "[email protected]",
"sub": "170848145649959169",
"updated_at": 1658329554,
//highlight-start
"urn:zitadel:iam:user:metadata": {
"ContractNumber": "MTIzNA"
}
//highlight-end
}
```
Note that the values are base64 encoded.
So the value `MTIzNA` decodes to `1234`.
<Callout title="decoding the jwt token">
Use a website like [jwt.io](https://jwt.io/) to decode the token.
With jq installed you can also use `jq -R 'split(".") | .[1] | @base64d | fromjson' <<< $ID_TOKEN`
</Callout>
### Request metadata from authentication API
You can use the authentication service to request and search for the user's metadata.
The introspection endpoint and the token endpoint in the examples above do not require a special scope to access.
Yet when accessing the authentication service, you need to pass the [reserved scope](/apis/openidoauth/scopes#reserved-scopes) `urn:zitadel:iam:org:project:id:zitadel:aud` along with the authentication request.
This scope allows the user to access ZITADEL's APIs, specifically the authentication API that we need for this method.
Use the [OIDC authentication request playground](https://zitadel.com/playgrounds/oidc) or the configuration of an [example client](/sdk-examples/introduction) to set the required scopes and receive a valid access token.
<Callout title="Invalid audience">
If you get the error "invalid audience (APP-Zxfako)", then you need to add the reserved scope `urn:zitadel:iam:org:project:id:zitadel:aud` to your authentication request.
</Callout>
You can request the user's metadata with the [List My Metadata](/reference/api/auth/zitadel.auth.v1.AuthService.ListMyMetadata) method:
```bash
curl -L -X POST "https://${CUSTOM_DOMAIN}/auth/v1/users/me/metadata/_search" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
--data-raw '{
"query": {
"offset": "0",
"limit": 100,
"asc": true
},
"queries": [
{
"keyQuery": {
"key": "${METADATA_KEY}",
"method": "TEXT_QUERY_METHOD_EQUALS"
}
}
]
}'
```
Replace `${ACCESS_TOKEN}` with your user's access token.
Replace `${CUSTOM_DOMAIN}` with your ZITADEL instance's url.
Replace `${METADATA_KEY}` with they key you want to search for (f.e. "ContractNumber")
<Callout title="Get all metadata">
You can omit the queries array to retrieve all metadata key-value pairs.
</Callout>
An example response for your search looks like this:
```json
{
"details": {
"totalResult": "1",
"processedSequence": "2935",
"viewTimestamp": "2023-06-21T16:01:52.829838Z"
},
"result": [
{
"details": {
"sequence": "409",
"creationDate": "2022-08-04T09:09:06.259324Z",
"changeDate": "2022-08-04T09:09:06.259324Z",
"resourceOwner": "170086363054473473"
},
"key": "ContractNumber",
"value": "MTIzNA"
}
]
}
```
## Register user with custom metadata
When you build your own registration UI you have the possibility to have custom fields and add them to the metadata of your user.
Learn everything about how to build your own registration UI [here](/guides/integrate/onboarding/end-users#build-your-own-registration-form).
## Manage user metadata through the management API
The previous methods allowed you to retrieve metadata only for the `sub` in the access token.
In case you want to get the metadata for another user, you need to use the management service.
The user that calls the management service must have [manager permissions](/guides/manage/console/managers).
A user can be either a human user or a service user.
You can get [metadata of a user filtered by your query](/apis/resources/mgmt/management-service-list-user-metadata) or [get a metadata object from a user by a specific key](/apis/resources/mgmt/management-service-get-user-metadata).
The management service allows you to set and delete metadata, see the [API documentation for users](/reference/api/user).
apps/docs/content/guides/manage/terraform-provider.mdx
+37
View File
@@ -0,0 +1,37 @@
---
title: ZITADEL Terraform Provider
sidebar_label: Terraform Provider
---
The [ZITADEL Terraform Provider](https://registry.terraform.io/providers/zitadel/zitadel/latest/docs) is a tool that allows you to manage ZITADEL resources through Terraform.
In other words, it lets you define and provision infrastructure for ZITADEL using Terraform configuration files.
This Terraform provider acts as a bridge, allowing you to manage various aspects of your ZITADEL instance directly through the [ZITADEL API](/apis/introduction), using Terraform's declarative configuration language.
It can be used to create, update, and delete ZITADEL resources, as well as to manage the relationships between those resources.
## Before you start
Make sure you create the following resources in ZITADEL and have [Terraform installed](https://learn.hashicorp.com/tutorials/terraform/install-cli):
- [A ZITADEL Instance](../start/quickstart)
- [A service user](/guides/integrate/service-users/authenticate-service-users) with [enough authorization](/guides/manage/console/managers) to manage the desired resources
## Manage ZITADEL resources through terraform
The full documentation and examples are available on the [Terraform registry](https://registry.terraform.io/providers/zitadel/zitadel/latest/docs).
To provide a small guide to where to start:
1. Create a folder where all the terraform files reside.
2. Configure the provider to use the right domain, port and token, with for example a `main.tf`file [as shown in the example](https://registry.terraform.io/providers/zitadel/zitadel/latest/docs).
3. Add a `zitadel_org` resource to the `main.tf` file, to create and manage a new organization in the instance, [as shown in the example](https://registry.terraform.io/providers/zitadel/zitadel/latest/docs/resources/org).
4. Add any resources to the organization in the `main.tf` file, [as example a human user](https://registry.terraform.io/providers/zitadel/zitadel/latest/docs/resources/human_user).
5. (Optional) Use Terraform in the directory with the command `terraform plan`, to see which resources would be created and how.
6. Apply the changes and start managing your resources with terraform with `terraform apply`.
7. (Optional) Delete your created resources with `terraform destroy` to clean-up.
## References
- [Deploy ZITADEL in your infrastructure](/self-hosting/deploy/overview)
- [ZITADEL CLI](/self-hosting/manage/cli/overview)
- [Configuration Options in ZITADEL](/self-hosting/manage/configure)
apps/docs/content/guides/manage/user/reg-create-user.mdx
+49
View File
@@ -0,0 +1,49 @@
---
title: Register and Create User
---
The ZITADEL API has different possibilities to create users.
This can be used, if you are building your own registration page.
Use the following API call to create your users:
[Create User (Human)](/reference/api/user/zitadel.user.v2.UserService.AddHumanUser)
## With Username and Password
If you are collecting all the user information and a password, you can directly create the user with the password.
With the `password_change_required` flag you can choose if the user has to change the password on the first login or not.
This might make sense if an administrator created the user.
## With passkey
You can directly ask for a link to create the passkey registration for the user.
Fill the user data and set the attribute `request_passwordless_registration` to true.
You will get a link for the registration and an expiration time in the response.
If you add `requestPlatformType` as query parameter to the link you can define what type the platform should be.
- **platform**: Device itself e.g. FaceID, Fingerprint etc.
- **crossPlatform** A hardware token e.g SoloKey
- **unspecified** The user is free to choose
If nothing is requested, the type will not be restricted and all possibilities of the device will be taken into account.
### Add passkey to existing user
If you already have a user in ZITADEL, it is possible to add passkey later.
[Add Passkey Registration ](/apis/resources/mgmt)
Send the user_id in the request and you will get a link and an expiration as response.
You can then customize the link the same as described above in the creation process.
The second possibility is to send the link directly to the user per email.
Use the following request in that case:
[Send Passkey Registration ](/apis/resources/mgmt)
## Verified Email Address
When creating users you can define wether you want to verify their email address before activating the user.
In case you want to create the user with an verified email address set the `isEmailVerified` property to `true`.
No initialization email will be sent to the user.
apps/docs/content/guides/manage/user/scim2.mdx
+124
View File
@@ -0,0 +1,124 @@
---
title: SCIM v2.0
---
Zitadel’s **[SCIM v2](https://scim.cloud/) service provider interface** enables standardized provisioning and lifecycle management of users and other IAM resources.
By implementing the official *System for Cross-domain Identity Management (SCIM) v2.0* specification, Zitadel allows seamless and automated user creation, updates, deactivation, and deprovisioning across systems.
## API
For full reference details of Zitadel’s SCIM API, consult the API documentation [here](/apis/scim2).
## Provisioning domain
A **provisioning domain** represents an external administrative domain—separate from the service provider—typically introduced for legal, organizational, or technical reasons.
Refer to the SCIM specification definitions in **RFC7643**:
https://datatracker.ietf.org/doc/html/rfc7643#section-1.2
Zitadel uses provisioning domains to scope the handling of the SCIM **`externalId`**, ensuring that different customers or systems provisioning users do not conflict with each other.
### Setting a provisioning domain
A provisioning domain can be assigned to a **machine user** by adding the following metadata entry:
- **Key:** `urn:zitadel:scim:provisioningDomain`
- **Value:** the name of the provisioning domain
### How Zitadel stores `externalId`
If a machine user has a provisioning domain set, any SCIM `externalId` provided during user provisioning or lookup is stored under:
`urn:zitadel:scim:{provisioningDomain}:externalId`
If *no* provisioning domain is configured, Zitadel falls back to a simplified metadata key:
`urn:zitadel:scim:externalId`
This ensures that different provisioning sources remain isolated, and the correct `externalId` is returned when queried through SCIM.
## Mapping
The following table describes how Zitadel maps SCIM User attributes to Zitadel user fields.
Attributes without a direct Zitadel equivalent are stored in **user metadata**.
For more information about user metadata, see [here](../customize/user-metadata).
| SCIM | Zitadel | Remarks |
|------------------------|-----------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `id` | `userId` | |
| `username` | `username` | |
| `name.formatted` | `profile.displayName` | The SCIM attribute `displayName` takes precedence over `name.formatted` |
| `name.familyName` | `profile.familyName` | |
| `name.middleName` | `metadata[urn:zitadel:scim:name.middleName]` | |
| `name.honorificPrefix` | `metadata[urn:zitadel:scim:name.honorificPrefix]` | |
| `name.honorificSuffix` | `metadata[urn:zitadel:scim:name.honorificSuffix]` | |
| `displayName` | `profile.displayName` | The SCIM attribute `displayName` takes precedence over `name.formatted` |
| `nickName` | `profile.nickName` | |
| `profileUrl` | `metadata[urn:zitadel:scim:profileUrl]` | |
| `title` | `metadata[urn:zitadel:scim:title]` | |
| `preferredLanguage` | `profile.preferredLanguage` | |
| `locale` | `metadata[urn:zitadel:scim:locale]` | |
| `timezone` | `metadata[urn:zitadel:scim:timezone]` | |
| `active` | `state` | `Initial` and `Active` are mapped to `active = true`, all other states are mapped to `active = false`.<br />The `active` value can only be updated if the user is in the state `Active` or `Inactive`. |
| `password` | `password` | |
| `emails` | `email` | Only the `primary` email is stored in Zitadel, if there is no `primary` email, the first one is stored. By default emails from SCIM are considered verified, this can be adjusted in the [configuration](#configuration). |
| `phoneNumbers` | `phone` | Only the `primary` phone number is stored in Zitadel, if there is no `primary` phone number, the first one is stored. By default phone numbers from SCIM are considered verified, this can be adjusted in the [configuration](#configuration). |
| `ims` | `metadata[urn:zitadel:scim:ims]` | Serialized as JSON. |
| `photos` | `metadata[urn:zitadel:scim:photos]` | Serialized as JSON. |
| `addresses` | `metadata[urn:zitadel:scim:addresses]` | Serialized as JSON. |
| `entitlements` | `metadata[urn:zitadel:scim:entitlements]` | Serialized as JSON. |
| `roles` | `metadata[urn:zitadel:scim:roles]` | Serialized as JSON. |
| `externalId` | `metadata[urn:zitadel:scim:externalId]`<br />`metadata[urn:zitadel:scim:{provisioningDomain}:externalId]` | See [provisioning domain](#provisioning-domain). |
## Configuration
This section provides details on the runtime configuration of the SCIM interface of Zitadel.
### Defaults
- Emails from SCIM are treated as **verified**
- Phone numbers from SCIM are treated as **verified**
- Bulk SCIM operations can include up to **100 operations**
- Maximum SCIM request body size is **1 MB**
This behavior can be adjusted through the Zitadel runtime configuration settings:
```yaml
SCIM:
EmailVerified: true
PhoneVerified: true
MaxRequestBodySize: 1_000_000
Bulk:
MaxOperationsCount: 100
```
## Limitations
Zitadel’s SCIM implementation follows the core SCIM specification but includes the following limitations.
### Supported schemas
Zitadel currently supports only the SCIM User schema: `urn:ietf:params:scim:schemas:core:2.0:User`
Group provisioning and other extended schemas are not supported.
### Required attributes
In addition to SCIM-standard required fields, Zitadel requires:
* `name.familyName`
* `name.givenName`
* `emails`: at least one email is required
### Duplicated attribute mapping
The SCIM user attributes `name.formatted` and `displayName` are both mapped to the `profile.displayName` attribute in
Zitadel.
If both are provided, `displayName` always takes precedence and is the value that will be stored and returned in future SCIM queries.
## Resources
- **[Zitadel SCIM API Documentation](/apis/scim2)**: Documentation of Zitadel's SCIM API implementation.
- **[SCIM](https://scim.cloud/)**: The Webpage of SCIM.
- **[RFC7643](https://tools.ietf.org/html/rfc7643) Core Schema**:
The Core Schema provides a platform-neutral schema and extension model for representing users and groups.
- **[RFC7644](https://tools.ietf.org/html/rfc7644) Protocol**:
The SCIM Protocol is an application-level, REST protocol for provisioning and managing identity data on the web.
- **[RFC7642](https://tools.ietf.org/html/rfc7642) Definitions, Overview, Concepts, and Requirements**:
This document lists the user scenarios and use cases of System for Cross-domain Identity Management (SCIM).