docs(concepts): update user concept (#4541)

* docs(azuread): update azuread integration guide

* docs(users): update concept users

* link instead of embed in service user guide

* remove referenced user description

* saml grant type

* typos

* update users

docs/docs/apis/openidoauth/grant-types.md

@@ -14,7 +14,7 @@ For a list of supported or unsupported `Grant Types` please have a look at the t
 | JSON Web Token (JWT) Profile                          | yes                 |
 | Refresh Token                                         | yes                 |
 | Resource Owner Password Credentials                   | no                  |
-| Security Assertion Markup Language (SAML) 2.0 Profile | no                  |
+| Security Assertion Markup Language (SAML) 2.0 Profile | no                 |
 | Token Exchange                                        | no    |
 
 ## Authorization Code
@@ -120,14 +120,15 @@ Find out how to use it on the [token endpoint](endpoints#token_endpoint) or the
 
 **Link to spec.** [OAuth 2.0 Device Authorization Grant](https://tools.ietf.org/html/rfc8628)
 
+## Security Assertion Markup Language (SAML) 2.0 Profile
+
+**Link to spec.** [Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://tools.ietf.org/html/rfc7522)
+
+
 ## Not Supported Grant Types
 
 ### Resource Owner Password Credentials
 
 > Due to growing security concerns we do not support this grant type. With OAuth 2.1 it looks like this grant will be removed.
 
-**Link to spec.** [OThe OAuth 2.0 Authorization Framework Section 1.3.3](https://tools.ietf.org/html/rfc6749#section-1.3.3)
-
-### Security Assertion Markup Language (SAML) 2.0 Profile
-
-**Link to spec.** [Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants](https://tools.ietf.org/html/rfc7522)
+**Link to spec.** [OThe OAuth 2.0 Authorization Framework Section 1.3.3](https://tools.ietf.org/html/rfc6749#section-1.3.3)

docs/docs/concepts/features/selfservice.md

@@ -13,7 +13,7 @@ It is important to understand that, depending on your use case, there will exist
 All self-service interfaces are available in different [languages](/docs/guides/manage/customize/texts#internationalization).
 
 :::info
-ZTIADEL covers the typical "CIAM" self-service capabilities as well as delegated access management for multi-tenancy scenarios. Please refer to the section [Managers](#managers).
+ZITADEL covers the typical "CIAM" self-service capabilities as well as delegated access management for multi-tenancy scenarios. Please refer to the section [Managers](#managers).
 :::
 
 ## Registration
@@ -31,7 +31,7 @@ Allows anonymous users and authenticated users, who are not yet in the given org
 - Mandatory profile fields
 - Set password
 - Accept terms of service and privacy policy
-- User receives an email with an one-time code for verfication purpose
+- User receives an email with an one-time code for verification purpose
 - User has to enter the one-time code to finish registration
 - User can re-request a new one-time code
 
@@ -40,7 +40,7 @@ This step can be made mandatory if MFA is enforced in the login policy.
 
 ### Existing Identity / SSO / Social Login
 
-anonymous users and authenticated users, who are not yet in the given organization, to register with an external identity provider.
+Anonymous users and authenticated users, who are not yet in the given organization, to register with an external identity provider.
 An external identity provider can be a Social Login Provider or a pre-configured identity provider.
 
 - Information from the external identity provider is used to pre-fill the profile information

docs/docs/concepts/structure/_user_description.mdx

@@ -1,5 +0,0 @@
-## Human vs. Machine
-
-ZITADEL supports human and 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/structure/users.md

@@ -2,9 +2,51 @@
 title: Users
 ---
 
-import UserDescription from './_user_description.mdx';
+## Types of users
 
-<UserDescription name="UserDescription" />
+ZITADEL supports authentication and authorization for different user types.
+We can mainly differentiate between Human Users and Machine Users.
+We typically call human users simply "Users" and machine users "Service Users".
 
+### Human users
+
+Human users typically logon with an interactive login.
+This means that an application redirects a user to a website ("login page") where the user can provide the credentials.
+ZITADEL handles the authentication and provides the application with a token that verifies the authentication process.
+
+### Service users
+
+Service users are for machine-to-machine communication and you would use those typically to access 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.
+
+### Managers
+
+Any user, human or service user, can be given a [Manager](/docs/concepts/structure/managers) role.
+Given a manager role, a user is not only an end-user of ZITADEL but can also manage certain aspects of ZITADEL itself.
+
+## Constraints
+
+Users can only exist within one [organization](/docs/concepts/structure/organizations).
+It is currently not possible to move users between organizations.
+
+User accounts are uniquely identified by their `id` or `loginname` in combination of the `organization domain` (eg, `road.runner@acme.zitadel.local`).
+You can use the same email address for different user accounts.
+
+## Where to store users
+
+Depending on your [scenario](/docs/guides/solution-scenarios/introduction), you might want to store all users in one organization (CIAM / B2C) or create a new organization for each logical group of users, e.g. each business customer (B2B).
+With a project grant, you can delegate the access management of an organization's project to another organization.
+You can also create a user grant to allow single users to access projects from another organization.
+This is also an alternative to cases where you might want to move users between organizations.
+
+## Identity linking
+
+When using external identity providers (ie. social login, enterprise SSO), a user account will be created in ZITADEL.
+The external identity will be linked to the ZITADEL account.
+
+You can link multiple external accounts to a ZITADEl account.
+If login with "Username / Password" (ie. local account) is enabled and you have configured external IDPs, the user can decide if she wants to login with an external IDP or the local account.
+When only one external identity provider is configured and login with "Username / Password" is disabled, then the user is immediately redirected to the external identity provider.
 
 More about how to manage your users read our [users guide](../../guides/manage/console/users).

docs/docs/guides/integrate/serviceusers.md

@@ -2,10 +2,7 @@
 title: Service Users
 ---
 
-import UserDescription from '../../concepts/structure/_user_description.mdx';
-
-<UserDescription name="UserDescription" />
-
+This is a guide on how to create service users in ZITADEL. You can read more about users [here](/docs/concepts/structure/users.md).
 ## Create a Service User
 
 1. Navigate to Service Users