chore(documentation): documentation and manuals for ZITADEL (#710)

* chore: cleanup old docs folder

* remove docs path trigger

* wip docs structure

* chore: ignore site changes in ci

* add manuals route

* new structure

* structure

* Use correct title

* remove trigger for code scan for static site generator

* change names

* add lorem ipsum to test styling

* use h3 to deeplink

* add site to dependabot

* lint readme.md

* remove not needed file

* ignore site on pull request code scan

* add initial contrib

* Minor correction

* Added section Developer & Integration

* Changed link list layout, added labels, added translations

* Added missing <li> tags

* Added correct link to section Developer & Integration

* Fixing list style

* Overhauling description texts and translations

* outline

* teaser go

* outline

* wip

* rework

* wip

* wip

* wip

* hop

* wip

* first draft for "administrate" done

* init outline

* fix deploy step

* lint

* commit wip

* commit wip

* md lint

* Link

* fix: path to edit (#711)

* wip

* wip

* wip

* what are...

* use only features

* wip docs

* Update 00-user.en.md

* project

* uppercase en

* wip

* wip

* wip

* policies rework

* improve text

* correct typo

* update readme

* correct styling

* add link to docs guides

* make the linter happy

* rename

* wip

* move api to own file

* correct links and lint

* wip roles and integration

* add pkce

* reduce padding and margin

* wip scope and claims

* wip claim & scopes

* make the linter happy

* insert links where possible

* wip

* wip roles & providers

* Update README.md

* Update 00-user.en.md

* minor text improvements

* use master branch to deploy

* use proper ci file

* Apply suggestions from code review

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

Co-authored-by: Matthias M. Schneider <mati@matimax.info>
Co-authored-by: Max Peintner <max@caos.ch>
Co-authored-by: Fabi <38692350+fgerschwiler@users.noreply.github.com>

site/docs/administrate/00-overview.de.md

@@ -0,0 +1,5 @@
+---
+title: Übersicht
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/00-overview.en.md

@@ -0,0 +1,40 @@
+---
+title: Overview
+---
+
+> All documentations are under active work and subject to change soon!
+
+### Features
+
+- Single-Sign On (SSO) and Single-Log Out (SLO) for
+  - Web applications
+    - Server Renderer
+    - Single Page
+  - Native Clients
+    - Windows
+    - MacOS
+    - Linux
+  - Mobile Clients
+    - Android
+    - iOS / iPadOS
+- Bearer Tokens to use with APIs
+  - REST
+  - GRPC
+  - GraphQL
+- Role Based Access Control
+- OpenID Connect 1.0 (OIDC) support
+- OAuth 2.0 support
+- Identity Brokering
+  - Federation with OIDC and OAuth 2.0 Identity Providers
+  - Social Login
+- Management Console for central management of your data
+- Multi-factor Authentication
+  - Support for TOTP/HOTP with any app, like authy, google authenticator, ...
+- User self-registration, recover password, email and phone verification, etc.
+- Organisation self-registration, domain verification, policy management
+- API's for easy integration in your application
+
+### Concepts
+
+With ZITADEL there are some key concepts some should be aware of before using it to secure your applications and services.
+You find these definitions in the "What is..." heading of each resource.

site/docs/administrate/01-console.de.md

@@ -0,0 +1,5 @@
+---
+title: Console
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/01-console.en.md

@@ -0,0 +1,30 @@
+---
+title: Console
+---
+
+### What is Console
+
+Console is the ZITADEL Graphical User Interface.
+
+**Users** can manage some information by their own.
+
+- profile information
+- credentials
+- external logins
+
+Users (**org owners**) who manage organisations do this also with Console.
+
+- Organisation settings (policies, domains, idp's)
+- Manage users
+- Manage projects, clients and roles
+- Give access to users
+
+For the **IAM Administrators** there is also a section in Console solely intended to manage the system.
+
+- Check failed events
+- Reset read models
+- Define system policies
+
+### Technologies
+
+Console is built with Angular and interfaces with ZITADEL by utilizing the GRPC APIs over GRPC-web.

site/docs/administrate/02-organisations.de.md

@@ -0,0 +1,5 @@
+---
+title: Organisationen
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/02-organisations.en.md

@@ -0,0 +1,43 @@
+---
+title: Organisations
+---
+
+### What are organisations
+
+Organisations are comparable to tenants of a system or OU's (organisational units) if we speak of a directory based system.
+ZITADEL is organised around the idea that multiple organisations share the same [System](administrate#What_is_meant_by_system) and that they can grant each other rights so self manage certain things.
+
+#### Global organisation
+
+ZITADEL provides a global organisation for users who manage their accounts on their own. Think of this like the difference between a "Microsoft Live Login" vs. "AzureAD User"
+or if you think of Google "Gmail" vs "Gsuite".
+
+### Create an organisation without existing login
+
+ZITADEL allows you to create a new organisation without a pre-existing user. For [ZITADEL.ch](https://zitadel.ch) you can create a org by visiting the [Register organisation](https://accounts.zitadel.ch/register/org)
+
+> Screenshot here
+
+For dedicated ZITADEL instances this URL might be different, but in most cases should be something like https://accounts.YOURDOMAIN.TLD/register/org
+
+### Create an organisation with existing login
+
+You can simply create a new organisation by visiting the [ZITADEL Console](https://console.zitadel.ch) and clicking "new organisation" in the upper left corner.
+
+> Screenshot here
+
+For dedicated ZITADEL instances this URL might be different, but in most cases should be something like `https://console.YOURDOMAIN.TLD`
+
+### Verify a domain name
+
+Once you created your organisation you will receive a generated domain name from ZITADEL for your organisation. For example if you call your organisation `ACME` you will receive `acme.zitadel.ch` as name. Furthermore the users you create will be suffixed with this domain name. To improve the user experience you can verify a domain name which you control. If you control acme.ch you can verify the ownership by DNS or HTTP challenge.
+After the domain is verified your users can use both domain names to log-in. The user "coyote" can now use "coyote@acme.zitadel.ch" and "coyote@acme.ch".
+An organisation can have multiple domain names, but only one of it can be primary. The primary domain defines which login name ZITADEL displays to the user, and also what information gets asserted in access_tokens (preferred_username).
+
+> Screenshot here
+
+### Audit organisation changes
+
+All changes to the organisation are displayed on the organisation menu within [ZITADEL Console](https://console.zitadel.ch/org) organisation menu. Located on the right hand side under "activity".
+
+> Screenshot here

site/docs/administrate/03-projects.de.md

@@ -0,0 +1,5 @@
+---
+title: Projekte
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/03-projects.en.md

@@ -0,0 +1,58 @@
+---
+title: Projects
+---
+
+### What are projects
+
+The idea of projects is to have a vessel for all components who are closely related to each other.
+In ZITADEL all clients located in the same project share their roles, grants and authorizations.
+From a access management perspective you manage who has what role in the project and your application consume this information.
+A project belongs to exactly one organisation.
+The attribute project role assertion defines, if the roles should be integrated in the tokens without sending corresponding scope (urn:zitadel:iam:org:project:role:{rolename})
+With the project role check you can define if a user should have a requested role to be able to logon.
+
+**Clients**
+
+Clients are described here [What are clients](administrate#What_are_clients)
+Basically these are you applications who initiate the authorization flow.
+
+**Roles**
+
+[Roles (or Project Roles)](administrate#Roles) is a mean of managing users access rights for a certain project.
+These [roles](administrate#Roles)  are opaque for ZITADEL and have no weight in relation to each other.
+So if a [user](administrate#Users) has two roles, admin and user in a certain project, the information will be treated additive.
+
+**Grants**
+
+With ZITADEL it is possible to give third parties (other organisations) the possibility to manage certain roles on their own.
+To achieve this the owner of a project can grant (some could say delegate) certain roles or all roles to a organisation.
+After granting that organisation it can manage on its own which user has what roles.
+This feature is especially useful for service providers, because they are able to establish a great self-service culture for their business customers.
+
+**Authorizations** 
+
+#### Project vs. granted Project
+
+The simple difference of a project vs a granted project is that a project belongs to your organisation and the granted project belongs to a third party who did grant you some rights to manage certain roles of their project.
+To make it more easily to differentiate ZITADEL Console displays these both as separate menu in the project section.
+
+### Manage a project
+
+> Screenshot here
+
+#### RBAC Settings
+
+- Authorisation Check option (Check if the user at least has one role granted)
+- Enable Project_Role Assertion (if this is enabled assert project_roles, with the config of the corresponding client)
+
+#### Define project specific roles
+
+> Screenshot here
+
+### Grant project to a third party
+
+> Screenshot here
+
+### Audit project changes
+
+> Screenshot here

site/docs/administrate/04-clients.de.md

@@ -0,0 +1,5 @@
+---
+title: Clients
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/04-clients.en.md

@@ -0,0 +1,22 @@
+---
+title: Clients
+---
+
+### What are clients
+
+Clients are applications who share the same security context and interface with an "authorization server".
+For example you could have a software project existing out of a web app and a mobile app, both of these application might consume the same roles because the end user might use both of them.
+
+### Manage clients
+
+Clients might use different protocols for integrating with an IAM. With ZITADEL it is possible to use OpenID Connect 1.0 / OAuth 2.0. In the future SAML 2.0 support is planned as well.
+
+> Screenshot here
+
+### Configure OpenID Connect 1.0 Client
+
+To make configuration of a client easy we provide a wizard which generates a specification conferment setup.
+The wizard can be skipped for people who are needing special settings.
+For use cases where your configuration is not compliant we provide you a "dev mode" which disables conformance checks.
+
+> Screenshot here

site/docs/administrate/05-roles.de.md

@@ -0,0 +1,5 @@
+---
+title: Rollen
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/05-roles.en.md

@@ -0,0 +1,41 @@
+---
+title: Roles
+---
+
+### What are Roles
+
+With **roles** **ZITADEL** lets [projects](administrate#projects) define there **role based access controle**.
+
+**Roles** can be consumed by the [clients](administrate#clients) which exist witing a specific [project](administrate#projects).
+
+For more information about how **roles** can be consumed have a look the the protocol specific information.
+
+- [OpenID Connect / OAuth](integrate#How_to_consume_authorizations_in_your_application_or_service)
+
+### Manage Roles
+
+Each **role** consist of three fields.
+
+| Field        | Description                                                                  | Example                                          |
+|:-------------|:-----------------------------------------------------------------------------|--------------------------------------------------|
+| Key          | This is the **Roles** actual name which can be used to verify the users roles.                                            | User                                             |
+| Display Name | A descriptive text for the purpose of the **Role**                           | User is the default role provided to each person |
+| Group        | The group field allows to group certain roles who belong in the same context | User and Admin in the group **default**          |
+
+### Grantig Roles
+
+To give someone (or somewhat) access to a [projects](administrate#projects) resources and services **ZITADEL** provides to processes. **Roles** can be either granted to [users](administrate#Users) org to [organisations](administrate#Organisations).
+
+#### Grant Roles to Organisations
+
+The possibility to grant **roles** to an [organisation](administrate#Organisations) is intented as "delegation" so that a [org](administrate#Organisations) can on their own grant access to [users](administrate#Users).
+
+For example a **service provider** could grant the **roles** user, and manager to an [org](administrate#Organisations) as soon as they purchases his service. This can be automated by utilising a [service user](administrate#Manage_Service_Users) in the **service providers** business process.
+
+> Screenshot here
+
+#### Grant Roles to Users
+
+By granting **roles** to [users](administrate#Users), be it [humanes or machines](administrate#Human_vs_Service_Users), this [user](administrate#Users) recieves the authorization to access resources from a service.
+
+> Screenshot here

site/docs/administrate/06-users.de.md

@@ -0,0 +1,5 @@
+---
+title: Benutzer
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/06-users.en.md

@@ -0,0 +1,48 @@
+---
+title: Users
+---
+
+### What are users
+
+In ZITADEL there are different users. Some belong to dedicated organisations other belong to the global org. Some of them are human users others are machines.
+Nonetheless we treat them all the same in regard to roles management and audit trail.
+
+#### Human vs. Service Users
+
+The major difference between humane vs. machine users is the type of credentials who can be used.
+With machine users there is only a non interactive login process possible. As such we utilize “JWT as Authorization Grant”.
+
+> TODO Link to “JWT as Authorization Grant” explanation.
+
+### How ZITADEL handles usernames
+
+ZITADEL is built around the concept of organisations. Each organisation has it's own pool of usernames which include human and service users.
+For example a user with the username `alice` can only exist once the org. `ACME`. ZITADEL will automatically generate a "logonname" for each user consisting of `{username}@{domainname}.{zitadeldomain}`. Without verifying the domain name this would result in the logonname `alice@acme.zitadel.ch`. If you use a dedicated ZITADEL replace `zitadel.ch` with your domain name.
+
+If someone verifies a domain name within the org. ZITADEL will generate additional logonames for each user with that domain. For example if the domain is `acme.ch` the resulting logonname would be `alice@acme.ch` and as well the generated one `alice@acme.zitadel.ch`.
+
+> Domain verification also removes the logonname from all users who might have used this combination in the global org.
+> Relating to example with `acme.ch` if a user in the global org, let's call him `bob` used `bob@acme.ch` this logonname will be replaced with `bob@randomvalue.tld`
+> ZITADEL notifies the user about this change
+
+### Manage Users
+
+#### Create User
+
+> Screenshot here
+
+#### Set Password
+
+> Screenshot here
+
+### Manage Service Users
+
+> Screenshot here
+
+### Authorizations
+
+> Screenshot here
+
+### Audit user changes
+
+> Screenshot here

site/docs/administrate/07-policies.de.md

@@ -0,0 +1,5 @@
+---
+title: Richtlinien
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/07-policies.en.md

@@ -0,0 +1,50 @@
+---
+title: Policies
+---
+
+### What are policies
+
+Polices are a means of enforcing certain behavior of ZITADEL.
+ZITADEL defines a default policy on the system level. However a org. owner can change these aspects within his own org.
+
+Below is a list of available policies
+
+### Password complexity
+
+This policy enforces passwords of users within the org. to be compliant.
+
+- min length
+- has number
+- has symbol
+- has lower case
+- has upper case
+
+> Screenshot here
+
+### IAM Access Preference
+
+This policy enforces, when set to true, that usernames are suffixed with the organisations domain.
+Under normal operation this policy is only false on the `global` org. so that users can choose there email as username.
+Only available for the `IAM Administrator`
+
+> Screenshot here
+
+### Login Options
+
+With this policy it is possible to define what options a user sees in the login process.
+
+- Username Password allowed
+- Self Register allowed
+- External IDP allowed
+- List of allowed external IDPs
+
+> Screenshot here
+
+### Audit policy changes
+
+> Screenshot here
+
+### Upcoming Policies
+
+- Password age
+- Password failure count

site/docs/administrate/08-providers.de.md

@@ -0,0 +1,5 @@
+---
+title: Identitäts Provider
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/08-providers.en.md

@@ -0,0 +1,72 @@
+---
+title: Identity Providers
+---
+
+### What are Identity Providers
+
+Identity providers or in short idp's are external systems to which **ZITADEL** can create a **federation** or use their **directory service**.
+Normally federation uses protocols like [OpenID Connect 1.0](https://openid.net/connect/), [OAuth 2.0](https://oauth.net/2/) and [SAML 2.0](http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-tech-overview-2.0.html).
+
+Some examples include:
+
+#### Social Providers
+
+- Google Account
+- Microsoft Live Account
+- Apple ID
+- GitHub
+- GitLab
+- ...
+
+#### Enterprise Providers**
+
+- Azure AD Tenant
+- Gsuite hosted domain
+- ...
+
+### Generic
+
+- ADFS
+- ADDS
+- Keycloak
+- LDAP
+
+### What is Identity Brokering
+
+ZITADEL supports the usage as identity broker, by linking multiple external idp's into one user.
+With identity brokering the client which relies on ZITADEL does not need to care about the linking of identity.
+
+### Manage Identity Providers
+
+> Screenshot here
+
+### Federation Protocols
+
+Currently supported are the following protocols.
+
+- OpenID Connect 1.0
+- OAuth 2.0
+
+SAML 2.0 will follow later on.
+
+### Storage Federation
+
+> This is a work in progress.
+
+Storage federation is a means of integrating existing identity storage like [LDAP](https://tools.ietf.org/html/rfc4511) and [ADDS](https://docs.microsoft.com/en-us/windows-server/identity/ad-ds/get-started/virtual-dc/active-directory-domain-services-overview).
+With this process **ZITADEL** can authenticate users with LDAP Binding and SPNNEGO for ADDS. It is also possible to synchronize the users just-in-time or scheduled.
+
+#### Sync Settings
+
+Here we will document all the different sync options
+
+- Readonly
+- Writeback
+- just-in-time sync
+- scheduled sync
+
+> TBD
+
+### Audit identity provider changes
+
+> Screenshot here

site/docs/administrate/80-audit.de.md

@@ -0,0 +1,5 @@
+---
+title: Audit
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/80-audit.en.md

@@ -0,0 +1,13 @@
+---
+title: Audit
+---
+
+### What about Audit
+
+ZITADEL is built upon the concept of Event sourcing. With this ZITADEL can track each operation of all objects it maintains over an infinite amount of time. The only limit is the storage system.
+
+With these events ZITADEL can provide you with a super detailed audit trail where you can see who changed what and when.
+
+Over the next few releases we will steadily enhance and build features tailored to reporting and audit.
+
+> It is important to mention that even if ZITADEL does not yet supply the Graphical User Interface for certain audit aspects it still has all the data to generate these reports later on!

site/docs/administrate/90-system.de.md

@@ -0,0 +1,5 @@
+---
+title: System Administration
+---
+
+> This Language is not yet translated. Please consult the English version.

site/docs/administrate/90-system.en.md

@@ -0,0 +1,58 @@
+---
+title: System Administration
+---
+
+### What is meant by system
+
+System describes the root of ZITADEL and includes all other elements like organisations, users and so on. Most of the time this part is managed by an user with the role IAM_OWNER.
+
+### Default Policies
+
+When ZITADEL is setup for the first time we establish certain default polices for the whole system.
+
+> TODO Document default policy settings
+
+### Manage Read Models
+
+Read Models are a way to normalize data out of the event stream for certain aspects. For example there is a model which consist of logonname and the password hash so that the login process can query that data.
+
+All read models are eventual consistent by nature and sometimes an administrator would like to verify they are still up-to date.
+In the ZITADEL Console is a section called administration available where the admin can check all read models and there current state.
+There is even a possibility to regenerate a read model.
+
+> When a read model is regenerated it might take up some time to be fully operational again
+> Depending on the model which is regenerated this might have a operational impact for the end-users
+
+> Screenshot here
+
+### Secret Handling
+
+ZITADEL store secrets always encrypted or hashed in it's storage.
+Whenever feasible we try to utilize public / private key mechanics to handle secrets.
+
+**Encryption**
+We use `AES256` as default mechanic for storing secrets.
+
+**Password Hashing**
+By default `bcrypt` is used with a salt of `14`.
+
+> This mechanic is used for user passwords and client secrets
+
+**Signing Keys**
+These keys are randomly generated within ZITADEL and are rotated on a regular basis (e.g all 6h).
+
+> Signing keys are stored with AES256 encryption
+
+**TLS**
+Under normal operations ZITADEL's API nodes are located behind a reverse proxy. So the TLS Key handlings is out of context in this regard.
+However ZITADEL can use TLS keys at runtime level.
+
+> TODO Document TLS config
+
+### IAM Configuration
+
+> TODO Document ZITADEL config
+
+### Audit system changes
+
+> Screenshot here