docs: console guide (#4468)

* console guide

* org

* orgs, projects

* applications

* project, roles, authz

* users, roles

* app config, imgs

* policy imgs

* users, metadata, imgs

* actions, projects, structure

* css

* rm overview component

* rm manager from sidebar

* fix some broken links, update 🦖

* fix broken links

* fix img shadow

* Update docs/docs/concepts/structure/applications.md

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* policy link

* link to projects guide

* Update docs/docs/guides/integrate/application/review-config.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* add external org authz guide

* Update docs/docs/guides/manage/console/users.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* link to example

* readd manager structure

* punto

* docs: domain settings email as username

* docs: links

* project, application settings, screenshots

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/instance-settings.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/organizations.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* iam role

* Update docs/docs/guides/manage/console/managers.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* Update docs/docs/guides/manage/console/managers.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* change username text

* Update docs/docs/guides/manage/console/roles.mdx

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* link example

* branding changes

* Update docs/docs/guides/manage/console/organizations.mdx

good point 👍

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>

* docs: loginnames

Co-authored-by: Fabi <38692350+hifabienne@users.noreply.github.com>
Co-authored-by: Fabienne <fabienne.gerschwiler@gmail.com>
This commit is contained in:
Max Peintner
2022-10-06 16:22:46 +02:00
committed by GitHub
parent c9870113f5
commit a4bbc756d8
138 changed files with 1296 additions and 779 deletions

View File

@@ -5,10 +5,10 @@ title: Self-Service
ZITADEL allows users to perform many tasks themselves.
For these tasks we either provide an user interface, or the tasks can be initiated or completed through ZITADEL's APIs.
It is important to understand that, depending on your use case, there will exist different user-types that want to perform different actions:
It is important to understand that, depending on your use case, there will exist different user-types that want to perform different actions:
- `Users` are the end-users of your application. Like with any CIAM solution, users should be able to perform tasks like register/join, update their profile, manage authenticators etc. There are certain actions that can be executed pre-login, yet others require the user to have a valid session.
- `Managers` are users with a [special manager role within ZITADEL](/docs/concepts/structure/managers) and can perform administrative actions such as system configuration or granting access rights to users.
- `Managers` are users with a [special manager role](../../guides/manage/console/managers) within ZITADEL and can perform administrative actions such as system configuration or granting access rights to users.
All self-service interfaces are available in different [languages](/docs/guides/manage/customize/texts#internationalization).
@@ -49,7 +49,7 @@ An external identity provider can be a Social Login Provider or a pre-configured
#### Account Linking
When you login with an external identity provider, and the user does not exist in ZITADEL, then an autoregister flow is triggered. The user is presented with two options:
When you login with an external identity provider, and the user does not exist in ZITADEL, then an autoregister flow is triggered. The user is presented with two options:
- Create a new account: A new account will be created as stated above
- Autolinking: The user is prompted to login with an existing [local account](#local-account). If successful, the existing identity from the external identity provider will be linked with the local account. A user can now login with either the local account or any of the linked external accounts.
@@ -138,7 +138,7 @@ A client can also implement this, by calling the [specific endpoint](/docs/apis/
## Profile
These actions are available for authenticated users only.
ZITADEL provides a self-service UI for the user profile out-of-the box under the path *{your_domain}/ui/console/users/me*.
ZITADEL provides a self-service UI for the user profile out-of-the box under the path _{your_domain}/ui/console/users/me_.
You can also implement your own version in your application by using our APIs.
### Change password
@@ -193,7 +193,7 @@ Thus we will explain service for two very common scenarios in ZITADEL:
- `Managers in isolation`: Granting administrative permissions within a single organization context.
- `Managers in delegation`: Granting administrative permissions to a user from a different organization where the organizations depend on each other
A list of [Manager Roles](/docs/concepts/structure/managers#roles) is available with a description of permissions.
A list of [Manager Roles](../../guides/manage/console/managers#roles) is available with a description of permissions.
Managers can be assigned to both human users and service users eg, for managing certain tasks programmatically.
### Managers in isolation

View File

@@ -1,17 +0,0 @@
![Organization Grant](/img/concepts/objects/organization_grants.png)
With ZITADEL you can grant selected roles within your project to an organization. The receiving organization can then create authorizations for their users on their own (self-service).
An example could be a service provider that offers a SaaS solution that has different permissions for employees working in Sales and Accounting. As soon as a new client purchases the service, the provider could grant the roles sales and accounting to that organization, allowing them to self-manage how they want to allocate the roles to their users.
The process of assigning certain roles by default or according to rules can be further automated by utilizing Service Users in the service providers business process.
Obviously, your organization can grant projects and receive projects. When you are granting, then the receiving organization will be displayed in the section GRANTED ORGANIZATIONS of your project.
![Project granted to organization](/img/console_projects_granted.png)
A granted project, on the other hand, belongs to a third party, granting you some rights to manage certain roles of their project. ZITADEL Console shows granted projects in a dedicated navigation menu, to clearly separate from your organizations projects.
![Granted Projects Overview](/img/console_granted_projects_overview.png)
Please note that you can also grant selected roles of a project to an individual user, instead of an organization. We will discuss this in more detail in a later section.

View File

@@ -0,0 +1,7 @@
ZITADEL Managers are Users who have permission to manage ZITADEL itself. This means that those users are allowed to login into your instance console and edit certain parts of the configuration.
There are some different levels for managers.
- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole Instance.
- **Org Managers**: Managers in the Organization Level are able to manage everything within the granted Organization.
- **Project Mangers**: In this level the user is able to manage a project.
- **Project Grant Manager**: The project grant manager is for projects, which are granted of another organization.

View File

@@ -4,9 +4,7 @@ The idea of projects is to have a vessel for all components who are closely rela
All applications within a project share the same roles, grants, and authorizations:
* **Applications** is your software that initiates the authorization flow. This could be a web app and a mobile app that share the same roles.
* **Roles** are a means of managing user access rights for a project.
* **Authorizations** define which users have which roles. Authorizations are also called “user grants”.
* **Granted Organizations** can manage selected roles for your project on their own.
![Organization grant](/img/console_projects_overview.png)
- **Applications** is your software that initiates the authorization flow. This could be a web app and a mobile app that share the same roles.
- **Roles** are a means of managing user access rights for a project.
- **Authorizations** define which users have which roles. Authorizations are also called “user grants”.
- **Granted Organizations** can manage selected roles for your project on their own.

View File

@@ -2,21 +2,8 @@
title: Applications
---
# Applications
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 API, maybe without even knowing. All applications share the roles and authorizations of their project.
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.
## Application Types
At the moment ZITADEL differs between three client types (with user interaction):
- Web (Server-side web applications such as java, .net, ...)
- Native (native, mobile or desktop applications)
- User Agent (single page applications / SPA, generally JavaScript executed in the browser)
As a fourth option there's the API (OAuth Resource Server), which generally has no direct user-interaction.
Depending on the app type registered, there are small differences in the possible settings.
Please read the following guide about the
[different-client-profiles](../../guides/integrate/oauth-recommended-flows.md#different-client-profiles).
To read more about available authentication types and how to setup applications, read this guide [here](../../guides/manage/console/applications)

View File

@@ -4,6 +4,10 @@ title: Granted Projects
# Granted Project
import GrantedProjectDescription from './_granted_project_description.mdx';
![Organization Grant](/img/concepts/objects/organization_grants.png)
<GrantedProjectDescription name="GrantedProjectDescription" />
With ZITADEL you can grant selected roles within your project to an organization. The receiving organization can then create authorizations for their users on their own (self-service).
An example could be a service provider that offers a SaaS solution that has different permissions for employees working in Sales and Accounting. As soon as a new client purchases the service, the provider could grant the roles sales and accounting to that organization, allowing them to self-manage how they want to allocate the roles to their users.
To learn more about how to setup Project grants, read this guide [here](../../guides/manage/console/projects#grant-a-project)

View File

@@ -1,8 +0,0 @@
---
title: Instance
---
import InstanceDescription from './_instance_description.mdx';
<InstanceDescription name="InstanceDescription" />

View File

@@ -0,0 +1,9 @@
---
title: Instance
---
import InstanceDescription from './\_instance_description.mdx';
<InstanceDescription name="InstanceDescription" />
More about how to configure your instance read our [instance guide](../../guides/manage/console/instance-settings).

View File

@@ -1,33 +0,0 @@
---
title: Managers
---
ZITADEL Managers are Users who have permission to manage ZITADEL itself. There are some different levels for managers.
- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole IAM.
- **Org Managers**: Managers in the Organization Level are able to manage everything within the granted Organization.
- **Project Mangers**: In this level the user is able to manage a project.
- **Project Grant Manager**: The project grant manager is for projects, which are granted of another organization.
To configure managers in ZITADEL go to the resource where you like to add it (e.g IAM, Organization, Project, GrantedProject).
In the right part of the console you can finde **MANAGERS** in the details part. Here you have a list of the current managers and can add a new one.
## Roles
| Role | Description |
|---|---|
| IAM_OWNER | Manage the IAM, manage all organizations with their content |
| IAM_OWNER_VIEWER | View the IAM and view all organizations with their content |
| IAM_ORG_MANAGER | Manage all organizations including their policies, projects and users |
| IAM_USER_MANAGER | Manage all users and their authorizations over all organizations |
| ORG_OWNER | Manage everything within an organization |
| ORG_OWNER_VIEWER | View everything within an organization |
| ORG_USER_MANAGER | Manage users and their authorizations within an organization |
| ORG_USER_PERMISSION_EDITOR | Manage user grants and view everything needed for this |
| ORG_PROJECT_PERMISSION_EDITOR | Grant Projects to other organizations and view everything needed for this |
| ORG_PROJECT_CREATOR | This role is used for users in the global organization. They are allowed to create projects and manage them. |
| PROJECT_OWNER | Manage everything within a project. This includes to grant users for the project. |
| PROJECT_OWNER_VIEWER | View everything within a project.|
| PROJECT_OWNER_GLOBAL | Same as PROJECT_OWNER, but in the global organization. |
| PROJECT_OWNER_VIEWER_GLOBAL | Same as PROJECT_OWNER_VIEWER, but in the global organization. |
| PROJECT_GRANT_OWNER | Same as PROJECT_OWNER but for a granted proejct. |

View File

@@ -0,0 +1,9 @@
---
title: Managers
---
import ManagerDescription from "./_manager_description.mdx";
<ManagerDescription name="ManagerDescription" />
To read more on how managers are created and which roles exist read the console guide [here](../../guides/manage/console/managers).

View File

@@ -6,7 +6,4 @@ import OrgDescription from './_org_description.mdx';
<OrgDescription name="OrgDescription" />
## Global Organization
In each ZITADEL system you will have a Global organization. If a user registers himself and no specific domain is given he will land in the Global organization.
Users in the Global Organization are managed by themselves and not by the organization manager.
More about how to configure your organization read our [organization guide](../../guides/manage/console/organizations).

View File

@@ -15,4 +15,3 @@ More details on the specific objects:
- [Applications](./applications)
- [Granted Projects](./granted_projects)
- [Users](./users)
- [Managers](./managers)

View File

@@ -3,170 +3,6 @@ title: Settings/Policies
---
Settings and policies are configurations of all the different parts of the Instance or an organization. For all parts we have a suitable default in the Instance.
The default configuration can be overridden for each organization, some policies are currently only available on the instance level. If thats the case it will be mentioned on the descriptions below.
The default configuration can be overridden for each organization, some policies are currently only available on the instance level. Learn more about our different policies [here](../../guides/manage/console/instance-settings.mdx).
You can find these settings in the instance page under settings, or on a specific organization menu organization in the section policies.
Each policy can be overridden and reset to the default.
## General
:::info
Only available on the instance settings
:::
At the moment general settings is only one configuration. This defines the default language of the whole instance.
![General Settings](/img/console_instance_policy_general.png)
## Notification
:::info
Only available on the instance settings
:::
In the notification settings you can configure your SMTP and an SMS Provider. At the moment only Twilio is available as SMS provider.
### 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.
Go to the ZITADEL [customer portal](https://zitadel.cloud) to configure a custom domain.
![Notification Providers](/img/console_instance_policy_notification.png)
### 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.
![Notification Providers](/img/console_instance_policy_notification_twilio.png)
## Login Policy
The Login Policy defines how the login process should look like and which authentication options a user has to authenticate.
| Setting | Description |
| --- | --- |
| Register allowed | Enable self register possibility in the login ui |
| Username Password allowed | Possibility to login with username and password |
| External IDP allowed | Possibility to login with an external identity (e.g Google, Microsoft, Apple, etc)|
| Force MFA | Force a user to register and use a multifactor authentication |
| Passwordless | Choose if passwordless login is allowed or not |
![Login Policy](/img/manuals/policies/console_org_login.png)
### Passwordless
Passwordless 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
In the multifactors section you can configure what kind of multifactors should be allowed. For passwordless to work, it's required to enable U2F (Universial Second Factor) with PIN. There is no other option at the moment.
Multifactors:
- U2F (Universal Second Factor) with PIN
Secondfactors:
- OTP (One Time Password)
- U2F (Universal Second Factor)
![Second- and Multifactors](/img/manuals/policies/console_org_second_and_multi_factors.png)
## 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
![Password Complexity Policy](/img/manuals/policies/console_org_pw_complexity.png)
## Lockout Policy
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 an account is locked, the administrator has to unlock it in the ZITADEL console
## 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 guide:
[Identity Brokering](../../guides/integrate/identity-brokering)
## Domain policy
In the domain policy you have two different settings.
One is the "user_login_must_be_domain", by setting this all the users within an organisation will be suffixed with the domain of the organisation.
The second is "validate_org_domains" if this is set to true all created domains on an organisation must be verified per acme challenge.
More about how to verify a domain [here](../../guides/manage/console/organizations#domain-verification-and-primary-domain).
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.
## Branding
With private labeling you can brand and customize your login page and emails, that it matches your CI/CD.
You can configure a light and a dark design.
Make sure you click the "Set preview as current configuration" button after you finish your configuration. Before this it will only be set as your preview configuration.
| Setting | Description |
| --- | --- |
| Logo | Upload your logo for the light and the dark design. |
| 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 |
| 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 |
![Private Labeling](/img/console_private_labeling.png)
## Privacy Policy and TOS
Each organization is able to configure its own privacy policy, terms of service and help.
A link to the current policies can be provided. On register each user has to accept these policies.
By clicking on an input field you can see the language attribute to integrate into a link, for the possibility to have different links for different languages.
The language of the user will be set into the url.
Example:
https://demo.com/tos-{{.Lang}}
![Privacy Policy](/img/manuals/policies/console_org_privacy.png)
## OIDC token lifetime and expiration
:::info
Only available on the instance settings
:::
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
![OIDC Token Lifetimes](/img/manuals/policies/console_policy_oidc.png)
## Secret appearance
:::info
Only available on the instance settings
:::
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
- Passwordless initialization code
- Application secrets
![OIDC Token Lifetimes](/img/manuals/policies/console_policy_secrets.png)
API wise, settings are often called policies. You can read the proto and swagger definitions [here](../../apis/introduction.mdx).

View File

@@ -4,27 +4,15 @@ title: Projects
# Project
import ProjectDescription from './_project_description.mdx';
import ProjectDescription from './\_project_description.mdx';
<ProjectDescription name="ProjectDescription" />
## Project Settings
On default the login screen will be shown in the private labeling settings of the system.
With the [primary domain scope](../../apis/openidoauth/scopes#reserves-scopes) it is possible to trigger the setting of the given organization.
But this will also restrict, the login to user of the given organization.
With the private labeling setting it is possible to choose which settings should trigger.
| Setting | Description |
| --- | --- |
| Unspecified | If nothing is specified the default will trigger. (System settings) |
| Enforce project resource owner policy | This setting will enforce the private labeling of the organization (resource owner) of the project through the whole login process. |
| Allow Login User resource owner policy | With this setting first the private labeling of the organization (resource owner) of the project will trigger. As soon as the user and its organization (resource owner) is identified by ZITADEL, the settings will change to the organization of the user. |
To learn how to set up a project read this console guide [here](../../guides/manage/console/projects.mdx).
## Applications
Applications define the different clients, that share the same roles.
Applications define the different clients, that share the same roles.
At the moment we support OIDC and almost every OAuth2 client. We'll be expanding this with SAML shortly.
Go to [Applications](./applications) for more details.
@@ -40,15 +28,7 @@ More about granted projects: [Granted Projects](./granted_projects)
## Roles
A role consists of different attributes. Only the key is relevant to the authorization and must therefore be unique.
The display name is only to provide a human-readable name if needed.
The display name is only to provide a human-readable name if needed.
And the group should enable a better handling in ZITADEL console, like give a user all the roles of a specific group. (Not implemented yet)
All applications in a project share the roles.
### Role specific Project Settings
| Setting | Description |
| --- | --- |
| Assert roles on authentication | If this setting is enabled role information is sent from userinfo endpoint and depending on your application settings in tokens and other types. |
| Check roles on authentication | If set, users are only allowed to authenticate if any role is assigned to their account. |
| Check for project on authentication | The user will only be able to authenticate if his organization is the owner or has a grant to the project. |
All applications in a project share the roles. Read more about roles [here](../../guides/manage/console/roles)

View File

@@ -5,3 +5,6 @@ title: Users
import UserDescription from './_user_description.mdx';
<UserDescription name="UserDescription" />
More about how to manage your users read our [users guide](../../guides/manage/console/users).