docs(concepts): Update resources and features, add account linking (#7934)

* account linking

* updates to concepts and features

* Apply suggestions from code review

* Apply suggestions from code review

Co-authored-by: Fabi <fabienne@zitadel.com>

---------

Co-authored-by: Fabi <fabienne@zitadel.com>

docs/docs/concepts/features/account-linking.md

@@ -0,0 +1,36 @@
+---
+title: Account linking
+---
+
+ZITADEL supports linking of user accounts from different external identity providers such as social logins or enterprise IdPs.
+A user can authenticate from any of their accounts and still be recognized by your app and associated with the same user profile.
+
+In ZITADEL, users have one user account to simplify access management and provide a consistent audit trail.
+A user account can have a link to multiple external identities.
+
+### Advantages
+
+- Users can login with multiple identity providers without managing separate profiles
+- Already registered users can link existing profiles
+- Provide backup authentication methods in case an IdP is unavailable
+- Unified audit trail across multiple identities
+
+### How it works
+
+ZITADEL gives you great flexibility to configure account linking for an organization and based on the external identity provider.
+
+When using external identity providers (ie. social login, enterprise SSO), a user account will be created in ZITADEL.
+The [external identity](../structure/users#federated-users) will be linked to the ZITADEL account.
+
+If login with "Username / Password" (ie. local account) is enabled and you have configured external IDPs, the user can decide if they want 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.
+
+In cases when a local account already exists and a user logs in with an external identity provider, you can instruct ZITADEL to link the external identity to the local account based on the username or email address.
+
+### Automatic account linking
+
+You can link accounts with the same email or username and prompt users to link them.
+On an [identity provider template settings](/docs/guides/integrate/identity-providers/introduction#key-settings-on-the-templates), you must enable "Account linking allowed".
+
+Automatic account linking is beneficial for users who wish to associate multiple login methods with their ZITADEL account, providing flexibility and convenience in how they access your application.

docs/docs/concepts/structure/applications.md

@@ -1,10 +1,28 @@
 ---
-title: ZITADEL Applications
+title: Configure applications for your frontend and backend services and clients
 sidebar_label: Applications
+sidebar_position: 5
 ---
+import AppType from "../../guides/manage/console/_application-types.mdx";
 
-# Applications
+Applications are the entry point to your project.
+[Users](users.md) 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](projects.md).
 
-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.
+## Supported application types
 
-To read more about available authentication types and how to setup applications, read this guide [here](../../guides/manage/console/applications)
+ZITADEL supports the following client types:
+
+<AppType />
+
+## Security considerations
+
+Ensure the configuration of application settings is limited to authorized users only.
+
+- Use [Manager roles](managers.mdx) to limit permissions for your users to make changes to your applications
+- When [granting projects](granted_projects.md) to other organizations, the receiving organization can't see or change application configuration
+
+## References
+
+- [Configure Applications in the Console](../../guides/manage/console/applications)
+- [ZITADEL API: Applications](/docs/category/apis/resources/mgmt/applications)

docs/docs/concepts/structure/instance.mdx

@@ -1,6 +1,7 @@
 ---
 title: ZITADEL Instances
 sidebar_label: Instances
+sidebar_position: 1
 ---
 
 ## Instance Structure

docs/docs/concepts/structure/organizations.md

@@ -1,6 +1,7 @@
 ---
 title: ZITADEL Organizations
 sidebar_label: Organizations
+sidebar_position: 2
 ---
 
 import OrgDescription from './_org_description.mdx';

docs/docs/concepts/structure/projects.md

@@ -1,10 +1,9 @@
 ---
-title: ZITADEL Projects
+title: Organize applications, services, and roles with projects
 sidebar_label: Projects
+sidebar_position: 4
 ---
 
-# Project
-
 import ProjectDescription from './\_project_description.mdx';
 
 <ProjectDescription name="ProjectDescription" />

docs/docs/concepts/structure/users.md

@@ -1,6 +1,7 @@
 ---
 title: ZITADEL Users
 sidebar_label: Users
+sidebar_position: 3
 ---
 
 ## Types of users
@@ -15,18 +16,36 @@ 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.
 
+Read more on how to [login users with ZITADEL](/docs/guides/integrate/login/login-users).
+
 ### 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.
 
+Learn how to [use service users](/docs/guides/integrate/service-users/authenticate-service-users) with ZITADEL.
+
 ### Managers
 
 Any user, human or service user, can be given a [Manager](/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
+### Federated users
+
+Federated users are identities that are managed by a third-party identity provider.
+Users can login via an external identity provider, using [identity brokering](../features/identity-brokering) ("Single-sign-on").
+Federated user [accounts are linked](../features/account-linking) to internal users to be able to assign roles and keep an audit trail.
+
+### External users
+
+In a multi-tenancy architecture, you might use [organizations](organizations) to separate user groups.
+By using [external user grants](../features/external-user-grant) an organization is able to invite users from another organization.
+These invited users are called external users.
+
+## Considerations
+
+### Uniqueness of users
 
 Users can only exist within one [organization](/concepts/structure/organizations).
 It is currently not possible to move users between organizations.
@@ -34,20 +53,30 @@ 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
+### How to structure user pools
 
-Depending on your [scenario](/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.
+Consider this general recommendation as a starting point:
 
-## Identity linking
+- Create one organization ("default organization") for your own company
+- Configure projects and applications in the default organization
+- Structure users in organizations based on common domains that are self-managed (eg, company)
+- Grant your projects to the organizations, allow Managers to give granted roles to their users
 
-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 might want to adjust this general setup based on your [scenario](/guides/solution-scenarios/introduction). 
 
-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.
+One important consideration in the setup is that you can only have a domain once for an organization. If you have multiple teams working with the same email address, you might need to add them to one single organization that has the domain verified for the teams' domain.
 
-More about how to manage your users read our [users guide](../../guides/manage/console/users).
+For a CIAM / B2C setup, you might want to store all users in one organization and allow that organization to use a specific set of social logins.
+In a multitenancy / B2B scenario, you might have thousands of smaller teams.
+
+#### Hierarchy
+
+There is no concept of hierarchies and inheritance based on users or organizations.
+This is why we recommend to structure users along the smallest unit of groups.
+You can use organization metadata or your own business logic to describe a hierarchy of organizations or user groups.
+
+## References
+
+- [Manage users in the Console](../../guides/manage/console/users)
+- [ZITADEL APIs: Users](/docs/category/apis/resources/mgmt/users)
+- [User onboarding and registration](/docs/guides/integrate/onboarding)

docs/docs/guides/manage/console/_application-types.mdx

@@ -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)

docs/docs/guides/manage/console/applications.mdx

@@ -7,6 +7,7 @@ import ThemedImage from "@theme/ThemedImage";
 
 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?
 
@@ -36,13 +37,9 @@ To add an application to your project, click on the add button and select your a
 
 ## Application Types
 
-At the moment ZITADEL offers four client types:
+At the moment ZITADEL offers five client types:
 
-- [**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)
+<AppType />
 
 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.

docs/sidebars.js

@@ -474,17 +474,29 @@ module.exports = {
           "This part of our documentation contains ZITADEL specific or general concepts required to understand the system or our guides.",
       },
       items: [
-        "concepts/structure/instance",
-        "concepts/structure/organizations",
-        "concepts/structure/projects",
-        "concepts/structure/applications",
-        "concepts/structure/granted_projects",
-        "concepts/structure/users",
-        "concepts/structure/managers",
-        "concepts/structure/policies",
         {
-          type: "autogenerated",
-          dirName: "concepts/features",
+          type: "category",
+          label: "Resources",
+          collapsed: false,
+          items: [
+            {
+              type: "autogenerated",
+              dirName: "concepts/structure",
+            }
+          ]
+          
+        },
+        {
+          type: "category",
+          label: "Features",
+          collapsed: false,
+          items: [
+            {
+              type: "autogenerated",
+              dirName: "concepts/features",
+            }
+          ]
+          
         },
         {
           type: "autogenerated",