docs: Admin training (#2436)

* docs: zitadel concepts

* docs: zitadel concepts

* docs: zitadel concepts

* docs: graphics

* docs: graphics

* docs: image zoom

* docs: readme fix

* docs: applications

* fix: graphics

* add plugins

* fix: links

* Update docs/docs/concepts/zitadel/objects/projects.md

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* Update docs/docs/concepts/zitadel/objects/projects.md

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* Update docs/docs/concepts/zitadel/objects/projects.md

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* Update docs/docs/concepts/zitadel/objects/projects.md

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* Update docs/docs/concepts/zitadel/objects/projects.md

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* Update docs/docs/concepts/zitadel/objects/projects.md

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

* Update docs/docs/concepts/zitadel/objects/applications.md

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

Co-authored-by: Livio Amstutz <livio.a@gmail.com>

docs/docs/concepts/general/eventstore.md

@@ -2,7 +2,7 @@
 title: Eventstore
 ---
 
-ZITADEL is built on the [event sourcing pattern](architecture), where changes are stored as events in an eventstore.
+ZITADEL is built on the [event sourcing pattern](../zitadel/architecture.md), where changes are stored as events in an eventstore.
 
 ## What is an eventstore?
 

docs/docs/concepts/zitadel/architecture.md

@@ -1,5 +1,5 @@
 ---
-title: ZITADEL Architecture
+title: Architecture
 ---
 
 ## Software Architecture

docs/docs/concepts/zitadel/objects/_granted_project_description.mdx

@@ -0,0 +1,17 @@
+![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 provider’s 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 organization’s 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.

docs/docs/concepts/zitadel/objects/_org_description.mdx

@@ -0,0 +1,17 @@
+ZITADEL is organized around the idea that:
+
+* Multiple organizations share the same system. In this case multiple organizations share the same service, zitadel.ch
+* organizations can grant each other rights to self-manage certain aspects of the IAM (eg, roles for access management)
+* organizations are vessels for users and projects
+
+![Overview ZITADEL Organizations](/img/concepts/objects/organization.png)
+
+Organizations in ZITADEL are therefore comparable to tenants of a system or organizational units of a directory based system.
+
+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 your organization.
+
+ZITADEL allows you to give other organizations permission to manage certain aspects of a project within your organization on their own. This means you could set up a project with roles that should exist within your service/software, but allow another organization to allocate the roles to users within their own organization. As a service provider, you will find this feature useful, as it allows you to establish a self-service culture for your business customers.
+
+![Organization Grant](/img/concepts/objects/organization_grants.png)
+
+Each organization has its own pool of usernames, which includes human and service users, for its domain (`{username}@{domainname}.{zitadeldomain}`). A username is unique within your organization. You can configure ZITADEL to use your own domain, and simplify user experience (`{loginname}@{yourdomain.tld}`).

docs/docs/concepts/zitadel/objects/_project_description.mdx

@@ -0,0 +1,12 @@
+The idea of projects is to have a vessel for all components who are closely related to each other. Multiple projects can exist within an organization.
+
+![Organization grant](/img/concepts/objects/organization_grants.png)
+
+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)

docs/docs/concepts/zitadel/objects/_user_description.mdx

@@ -0,0 +1,5 @@
+## Human vs. Machine
+
+ZITADEL supports human an machine users. We call human users simply "Users" and machine users "Service Users".
+
+With Service Users you would typically secure backend services. For example in ZITADEL you would require an authenticated Service User to access the Management API. The main difference between human and machine users is the type of credentials that can be used for authentication: Human users typically logon via an login prompt, but Machine users require a non-interactive logon process.

docs/docs/concepts/zitadel/objects/applications.md

@@ -0,0 +1,21 @@
+---
+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.
+
+## 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/authorization/oauth-recommended-flows#different-client-profiles).

docs/docs/concepts/zitadel/objects/granted_projects.md

@@ -0,0 +1,9 @@
+---
+title: Granted Projects
+---
+
+# Granted Project
+
+import GrantedProjectDescription from './_granted_project_description.mdx';
+
+<GrantedProjectDescription name="GrantedProjectDescription" />

docs/docs/concepts/zitadel/objects/managers.md

@@ -1,5 +1,5 @@
 ---
-title: ZITADEL Managers
+title: Managers
 ---
 
 ZITADEL Managers are Users who have permission to manage ZITADEL itself. There are some different levels for managers.

docs/docs/concepts/zitadel/objects/organizations.md

@@ -0,0 +1,7 @@
+---
+title: Organizations
+---
+
+import OrgDescription from './_org_description.mdx';
+
+<OrgDescription name="OrgDescription" />

docs/docs/concepts/zitadel/objects/overview.md

@@ -0,0 +1,17 @@
+---
+title: Structure
+---
+
+This overview shows the general structure of ZITADEL.
+
+![Overview](/img/concepts/objects/object_overview.png)
+
+More details on the specific objets:
+
+- [Organizations](./organizations)
+- [Policies](./policies)
+- [Projects](./projects)
+- [Applications](./applications)
+- [Granted Projects](./granted_projects)
+- [Users](./users)
+- [Managers](./managers)

docs/docs/concepts/zitadel/objects/policies.md

@@ -1,5 +1,5 @@
 ---
-title: ZITADEL Policies
+title: Policies
 ---
 
 Policies are configurations of all the different parts of the IAM. For all parts we have a suitable default in the IAM.
@@ -55,7 +55,7 @@ You can configure all kinds of external identity providers for identity brokerin
 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/authentication/identity-brokering)
+[Identity Brokering](../../../guides/authentication/identity-brokering)
 
 ## Lockout Policy
 
@@ -83,3 +83,8 @@ Make sure you click the "Set preview as current configuration" button after you
 | Disable Watermark | If you disable the watermark you will not see the "Powered by ZITADEL" in the login page |
 
 ![Private Labeling](/img/manuals/policies/console_org_private_labeling.png)
+
+## Privacy Policy and TOS
+
+Each organization is able to configure its own privacy policy and terms of service.
+A link to the current policies can be provided. On register each user has to accept these policies.

docs/docs/concepts/zitadel/objects/projects.md

@@ -0,0 +1,54 @@
+---
+title: Projects
+---
+
+# Project
+
+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 (e.g zitadel.ch).
+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 zitadel.ch) |
+| 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. |
+
+## Applications
+
+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.
+
+## Granted Organizations
+
+To enable another organization to use a project, the organization needs a grant to the project.
+Only the selected roles will be available to the granted organization.
+
+The granted organization will be able to manage the authorizations of his users for the granted project by himself in his own organization.
+
+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. 
+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. |

docs/docs/concepts/zitadel/objects/users.md

@@ -0,0 +1,7 @@
+---
+title: Users
+---
+
+import UserDescription from './_user_description.mdx';
+
+<UserDescription name="UserDescription" />

docs/docs/guides/api/access-zitadel-apis.md

@@ -37,7 +37,7 @@ ZITADEL Managers are Users who have permission to manage ZITADEL itself. There a
 - **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.
 
-On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../../concepts/managers)
+On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../../concepts/zitadel/objects/managers.md)
 
 
 ## Exercise: Add ORG_OWNER to Service User

docs/docs/guides/authentication/identity-brokering.md

@@ -41,7 +41,7 @@ If Google is configured as identity provider on your organization, the user will
 ZITADEL will redirect the user to the login screen of Google where he as to authenticated himself (2) and is sent back after he has finished that (3).
 Because Google is registered as trusted identity provider the user will be able to login in with the Google account after he linked an existing ZITADEL Account or just registered a new one with the claims provided by Google (4)(5).
 
-![Identity Brokering](/img/zitadel_identity_brokering.png)
+![Identity Brokering](/img/guides/identity_brokering.png)
 
 ## Exercise: Register an external identity provider
 

docs/docs/guides/authentication/serviceusers.md

@@ -28,11 +28,10 @@ title: Service Users
     </tr>
 </table>
 
-## Human vs. Machine
 
-ZITADEL supports human an machine users. We call human users simply "Users" and machine users "Service Users".
+import UserDescription from '../../concepts/zitadel/objects/_user_description.mdx';
 
-With Service Users you would typically secure backend services. For example in ZITADEL you would require an authenticated Service User to access the Management API. The main difference between human and machine users is the type of credentials that can be used for authentication: Human users typically logon via an login prompt, but Machine users require a non-interactive logon process.
+<UserDescription name="UserDescription" />
 
 ## Exercise: Create a Service User
 

docs/docs/guides/authorization/oauth-recommended-flows.md

@@ -59,7 +59,7 @@ So what do we want to achieve with delegated authentication?
   * Users have to **authorize** applications to access certain [**scopes**](https://docs.zitadel.ch/architecture#Scopes) (eg, email address or custom roles). Applications can request [**claims**](https://docs.zitadel.ch/architecture#Claims) (key:value pairs, eg email address) for the authorized scopes with the access token or ID token from ZITADEL
   * Access tokens are bearer tokens, meaning that possession of the token provides access to a resource. But the tokens expire frequently and the application must request a new access token via **refresh token** or the user must reauthenticate
 
-![Overview federated identities](/img/consulting_federated_identities_basics.png)
+![Overview federated identities](/img/guides/consulting_federated_identities_basics.png)
 
 This is where the so-called “flows” come into play: There are a number of different flows on how to handle the process from authentication, over authorization, getting tokens and requesting additional information about the user.
 

docs/docs/guides/basics/organizations.md

@@ -11,23 +11,9 @@ title: Organizations
 
 ## What is an organization?
 
-ZITADEL is organized around the idea that:
+import OrgDescription from '../../concepts/zitadel/objects/_org_description.mdx';
 
-* Multiple organizations share the same system. In this case multiple organizations share the same service, zitadel.ch
-* organizations can grant each other rights to self-manage certain aspects of the IAM (eg, roles for access management)
-* organizations are vessels for users and projects
-
-![Overview ZITADEL Organizations](/img/zitadel_organizations.png)
-
-Organizations in ZITADEL are therefore comparable to tenants of a system or organizational units of a directory based system.
-
-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 your organization.
-
-ZITADEL allows you to give other organizations permission to manage certain aspects of a project within your organization on their own. This means you could set up a project with roles that should exist within your service/software, but allow another organization to allocate the roles to users within their own organization. As a service provider, you will find this feature useful, as it allows you to establish a self-service culture for your business customers.
-
-![Organization Grant](/img/zitadel_organization_grant.png)
-
-Each organization has its own pool of usernames, which includes human and service users, for its domain (`{username}@{domainname}.{zitadeldomain}`). A username is unique within your organization. You can configure ZITADEL to use your own domain, and simplify user experience (`{loginname}@{yourdomain.tld}`).
+<OrgDescription name="OrgDescription" />
 
 There are several more modules in our documentation to go into more detail regarding organization management, projects, clients, and users. But first let’s create a new organization and verify your domain name.
 

docs/docs/guides/basics/projects.md

@@ -11,18 +11,9 @@ title: Projects
 
 ## What is a project?
 
-The idea of projects is to have a vessel for all components who are closely related to each other. Multiple projects can exist within an organization.
+import ProjectDescription from '../../concepts/zitadel/objects/_project_description.mdx';
 
-![Organization grant](/img/zitadel_organization_grant.png)
-
-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)
+<ProjectDescription name="ProjectDescription" />
 
 The goal of this module is to give you an overview, but not dive too deep into details around managing access rights and delegating management of roles to third parties. So let’s create a straightforward example project first.
 
@@ -66,23 +57,9 @@ Now create another project (eg. “My second project”) and verify that there a
 
 ## What is a granted project?
 
-![Organization Grant](/img/zitadel_organization_grant.png)
+import GrantedProjectDescription from '../../concepts/zitadel/objects/_granted_project_description.mdx';
 
-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 provider’s 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 organization’s 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.
+<GrantedProjectDescription name="GrantedProjectDescription" />
 
 ## Exercise - Grant a project
 

docs/docs/legal/dedicated-instance-annex.md

@@ -74,4 +74,4 @@ Performance SLO | up to [rate limits](https://docs.zitadel.ch/docs/legal/rate-li
 
 ### Backup
 
-ZITADEL Cloud creates hourly backups. We do not guarantee recovery time objective. Recovery point objective is in the context of our [event-sourcing pattern](/docs/concepts/eventstore) not meaningful.
+ZITADEL Cloud creates hourly backups. We do not guarantee recovery time objective. Recovery point objective is in the context of our [event-sourcing pattern](/docs/concepts/general/eventstore) not meaningful.

docs/docusaurus.config.js

@@ -9,6 +9,7 @@ module.exports = {
   organizationName: 'caos',
   projectName: 'zitadel',
   themeConfig: {
+    zoomSelector: '.markdown :not(em) > img',
     navbar: {
       title: 'ZITADEL',
       logo: {
@@ -146,5 +147,6 @@ module.exports = {
         domain: 'docs.zitadel.ch',
       },
     ],
+    require.resolve('plugin-image-zoom'),
   ],
 };

docs/package.json

@@ -21,6 +21,7 @@
     "docusaurus-plugin-plausible": "^0.0.5",
     "mdx-mermaid": "^1.1.0",
     "mermaid": "^8.12.1",
+    "plugin-image-zoom": "ataft/plugin-image-zoom",
     "react": "^17.0.2",
     "react-dom": "^17.0.2"
   },

docs/sidebars.js

@@ -189,11 +189,37 @@ module.exports = {
     ],
     concepts: [
         'concepts/introduction',
-    'concepts/architecture',
-    'concepts/policies',
-    'concepts/managers',
-    'concepts/principles',
-    'concepts/eventstore',
+        {
+            type: 'category',
+            label: 'ZITADEL',
+            collapsed: true,
+            items: [
+                'concepts/zitadel/architecture',
+                {
+                    type: 'category',
+                    label: "Object Overview",
+                    collapsed: false,
+                    items: [
+                        'concepts/zitadel/objects/overview',
+                        'concepts/zitadel/objects/organizations',
+                        'concepts/zitadel/objects/policies',
+                        'concepts/zitadel/objects/projects',
+                        'concepts/zitadel/objects/applications',
+                        'concepts/zitadel/objects/granted_projects',
+                        'concepts/zitadel/objects/users',
+                        'concepts/zitadel/objects/managers',
+                    ],
+                },
+            ],
+        }, {
+            type: 'category',
+            label: 'General',
+            collapsed: true,
+            items: [
+                'concepts/general/principles',
+                'concepts/general/eventstore',
+            ],
+        },
         {
             type: 'category',
             label: 'Use Cases',
@@ -202,6 +228,7 @@ module.exports = {
                 'concepts/usecases/saas'
             ],
         },
+
     ],
     manuals: [
         'manuals/introduction',

docs/yarn.lock

@@ -5804,6 +5804,11 @@ media-typer@0.3.0:
   resolved "https://registry.npmjs.org/media-typer/-/media-typer-0.3.0.tgz"
   integrity sha1-hxDXrwqmJvj/+hzgAWhUUmMlV0g=
 
+medium-zoom@^1.0.4:
+  version "1.0.6"
+  resolved "https://registry.yarnpkg.com/medium-zoom/-/medium-zoom-1.0.6.tgz#9247f21ca9313d8bbe9420aca153a410df08d027"
+  integrity sha512-UdiUWfvz9fZMg1pzf4dcuqA0W079o0mpqbTnOz5ip4VGYX96QjmbM+OgOU/0uOzAytxC0Ny4z+VcYQnhdifimg==
+
 memory-fs@^0.4.1:
   version "0.4.1"
   resolved "https://registry.npmjs.org/memory-fs/-/memory-fs-0.4.1.tgz"
@@ -6543,6 +6548,12 @@ pkg-up@3.1.0:
   dependencies:
     find-up "^3.0.0"
 
+plugin-image-zoom@ataft/plugin-image-zoom:
+  version "0.0.0"
+  resolved "https://codeload.github.com/ataft/plugin-image-zoom/tar.gz/a20c49db137ae2f9aa4128aafced3b74590300aa"
+  dependencies:
+    medium-zoom "^1.0.4"
+
 portfinder@^1.0.26:
   version "1.0.28"
   resolved "https://registry.npmjs.org/portfinder/-/portfinder-1.0.28.tgz"

go.mod

@@ -4,7 +4,7 @@ go 1.16
 
 require (
 	cloud.google.com/go/storage v1.16.1
-	cloud.google.com/go/trace v0.1.0 // indirect
+	cloud.google.com/go/trace v1.0.0 // indirect
 	github.com/BurntSushi/toml v0.4.1
 	github.com/DATA-DOG/go-sqlmock v1.5.0
 	github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace v1.0.0-RC2

go.sum

@@ -49,6 +49,8 @@ cloud.google.com/go/storage v1.16.1 h1:sMEIc4wxvoY3NXG7Rn9iP7jb/2buJgWR1vNXCR/UP
 cloud.google.com/go/storage v1.16.1/go.mod h1:LaNorbty3ehnU3rEjXSNV/NRgQA0O8Y+uh6bPe5UOk4=
 cloud.google.com/go/trace v0.1.0 h1:nUGUK79FOkN0UGUXhBmVBkbu1PYsHe0YyFSPLOD9Npg=
 cloud.google.com/go/trace v0.1.0/go.mod h1:wxEwsoeRVPbeSkt7ZC9nWCgmoKQRAoySN7XHW2AmI7g=
+cloud.google.com/go/trace v1.0.0 h1:laKx2y7IWMjguCe5zZx6n7qLtREk4kyE69SXVC0VSN8=
+cloud.google.com/go/trace v1.0.0/go.mod h1:4iErSByzxkyHWzzlAj63/Gmjz0NH1ASqhJguHpGcr6A=
 dmitri.shuralyov.com/gpu/mtl v0.0.0-20190408044501-666a987793e9/go.mod h1:H6x//7gZCb22OMCxBHrMx7a5I7Hp++hsVxbQ4BYO7hU=
 github.com/AlecAivazis/survey/v2 v2.2.15 h1:6UNMnk+YGegYFiPfdTOyZDIN+m08x2nGnqOn15BWcEQ=
 github.com/AlecAivazis/survey/v2 v2.2.15/go.mod h1:TH2kPCDU3Kqq7pLbnCWwZXDBjnhZtmsCle5EiYDJ2fg=