mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-09 15:45:12 +00:00
docs: introduce versioned docs and migrate to fuma (#11166)
## 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
co-authored by
Federico Coppede
Federico Coppede
parent
7b6395c348
commit
d8ea041c56
@@ -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" />
|
||||
@@ -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)
|
||||
@@ -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" />
|
||||
@@ -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)
|
||||
@@ -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).
|
||||
@@ -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)
|
||||
@@ -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"
|
||||
/>
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
@@ -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} />
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
## 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>
|
||||
|
||||
|
||||
|
||||
## 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).
|
||||
@@ -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.
|
||||
|
||||
|
||||
|
||||
## 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.
|
||||
@@ -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.
|
||||
@@ -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)
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user