docs: homepage, concepts cleanup

docs/docs/concepts/general/eventstore.md → docs/docs/concepts/eventstore.md

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

docs/docs/concepts/introduction.mdx

@@ -0,0 +1,39 @@
+---
+title: Introduction
+---
+
+import {ListElement, ListWrapper, ICONTYPE} from '../../src/components/list';
+import Column from '../../src/components/column';
+
+This part of the **ZITADEL** documentation contains ZITADEL specific or general concepts required to understand the system or our guides.
+
+Please be reminded that ZITADEL is open source — and so is the documentation. Should you happen to stumble over an incorrectness, a spelling mistake, a hard-to-understand text passage, please don’t hesitate to leave a comment or propose a corresponding change.
+
+
+<Column>
+  <ListWrapper title="General">
+    <ListElement link="./principles" type={ICONTYPE.TASKS} title="Principles" description="Design and engineering principles" />
+    <ListElement link="./eventstore" type={ICONTYPE.STORAGE} title="Eventstore" description="Learn how ZITADEL stores data" />
+    <ListElement link="./architecture" type={ICONTYPE.ARCHITECTURE} title="Architecture" description="Sotware-, Cluster- and Multi Cluster Architecture" />
+  </ListWrapper>
+  <ListWrapper title="Structure">
+    <Column>
+      <div>
+      <ListElement link="./structure/overview" type={ICONTYPE.FOLDER} title="Overview" description="" />
+      <ListElement link="./structure/organizations" type={ICONTYPE.FILE} title="Organizations" description="" />
+      <ListElement link="./structure/policies" type={ICONTYPE.FILE} title="Policies" description="" />
+      <ListElement link="./structure/projects" type={ICONTYPE.FILE} title="Projects" description="" />
+    </div>
+    <div>
+      <ListElement link="./structure/applications" type={ICONTYPE.FILE} title="Applications" description="" />
+      <ListElement link="./structure/granted_projects" type={ICONTYPE.FILE} title="Granted Projects" description="" />
+      <ListElement link="./structure/users" type={ICONTYPE.FILE} title="Users" description="" />
+      <ListElement link="./structure/managers" type={ICONTYPE.FILE} title="Managers" description="" />
+    </div>
+    </Column>
+  </ListWrapper>
+
+  <ListWrapper title="Use Cases">
+    <ListElement link="./usecases/saas" type={ICONTYPE.START} title="SaaS" description="Product with Authentication and Authorization" />
+  </ListWrapper>
+</Column>

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

@@ -18,4 +18,5 @@ As a fourth option there's the API (OAuth Resource Server), which generally has
 
 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).
+Please read the following guide about the
+[different-client-profiles](../../guides/authorization/oauth-recommended-flows#different-client-profiles).

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

@@ -1,5 +1,5 @@
 ---
-title: Structure
+title: Overview
 ---
 
 This overview shows the general structure of ZITADEL.

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

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

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

@@ -11,7 +11,7 @@ import ProjectDescription from './_project_description.mdx';
 ## 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. 
+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.

docs/docs/concepts/usecases/saas.md

@@ -1,5 +1,5 @@
 ---
-title: Saas Product with Authentication and Authorization
+title: SaaS Product with Authentication and Authorization
 ---
 
 This is an example architecture for a typical SaaS product. 

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/zitadel/objects/managers.md)
+On each level we have some different Roles. Here you can find more about the different roles: [ZITADEL Manager Roles](../../concepts/structure/managers.md)
 
 
 ## Exercise: Add ORG_OWNER to Service User

docs/docs/guides/architecture-scenarios/b2b.mdx

@@ -0,0 +1,86 @@
+---
+title: B2B
+---
+
+import { B2B } from '../../../src/components/b2b';
+
+## Business to Business
+
+B2B describes the situation where an organization interacts with another organization.
+This **multiple organization architecture (Multitenancy)** usually adds some complexity to an Identity and Access Management System.
+In ZITADEL an organization represents a group, business customer or partner who typically has its own branding and has different access settings like an additional federated login for its users.
+
+As a B2B use case you could have a simple scenario where an organization only shares one of its projects with another organization or have a more complex case where an organization is offering a portal application to all its partners with included administration.
+
+
+<!-- This guide describes an application  -->
+## Sample scenario
+
+Octagon is a fictitious company which is used throughout this guide to explain the details and key concepts of such a B2B scenario.
+Octagon tries to solve multiple tasks in the banking field. Its portfolio includes several applications for their employees, customers, and partners. Some of which are web-based, some of which are used by machine users only.
+
+### Portal Application
+
+Octagon has a **Portal application** where its employees can access their account and list all applications they are allowed to use.
+Employees work for a department organization within Octagon or for Octagon itself. 
+Some have enhanced features because they are supervisors of a team. Those can onboard new employees and manage their roles and features.
+Target groups of the application can be split into:
+- **Employes:** users who are using the application as a starting point for their work.
+- **Supervisors:** users who are mainly using the application to manage users and their access of their department.
+- **Administrators:** this users are able to grant additional organizations or departments and elect supervisors.
+
+### Planning considerations
+
+In order to define the need of the **Portal Application** some planning considerations about organizations have to be made:
+
+- **Login and Access:** Does a user have a preset organization to login? Does the application show the default login page or does each organization use its own branding?
+- **Organizations:** Does a user have access in multiple organizations? Is a user required to use a different federated login for those organizations?
+- **Roles** Does the application need users to have specific roles assigned within their organizations? Which roles are needed to enable certan features of the application?
+
+### Login
+
+You can decide whether a organization is preselected for the login or if the user is redirected to the default login screen. You can send the user to a specific organization by defining the organization in a custom scope.
+Settings to the branding or the login options of the organization can be made from the organization section in [Console](https://console.zitadel.ch/org). 
+The behaviour of the login branding can be set in your projects detail page. You can choose the branding of the selected organization, the user resource owner, or the projects resource owner.
+
+### Organizations
+
+A user in general can be isolated to an organization, or be shared across multiple organizations. Anyways, a user should be able to use the same identity to switch between organizations.
+If this feature is not desired, a seperate user for each organization should be created.
+
+Adding a user from a different organization to the audience of a project can be as easy as adding a new user authorization (user grant). A user grant combines a user from any organization with a project and 0-N roles.
+
+In our sample scenario, we assume to have the following users:
+
+- **Dimitri:** a team leader who is employed by Hexagon, an Octagon department. Dimitri uses his Microsoft Account in combination with his one time password to access the portal. Hexagon therefore has set up Microsoft as Identity Provider. Hexagon also requires its users to secure their accounts with additional factor.
+- **Michael:** a trainee of Hexagon only using the portal to access his workspace apps. Michael uses his Google Account in combination with is his laptops fingerprint.
+- **Bill:** is employed at Octagon as Administrator of the Portal Application. Dimitri too uses a Microsoft Account in combination with a Security Key to secure his account.
+
+After having determined the constellation of the organizations and its users, all the necessary data (Portal project with roles and app, users, login requirements, identity providers, branding) should be set up in [Console](https://console.zitadel.ch/org).
+A B2B sample application for NextJS can be found in our [Example Repo](https://github.com/caos/zitadel-examples).
+
+To allow an other organization to use a project, a project grant has to be created. Upon creation, roles for a grant can be limited to a subset of the total projectroles.
+
+In our scenario, Octagon creates a project grant for Hexagon. Hexagon is limited to use `writer` and `reader` role. The `admin` role is reserved for the Octagon organization itself.
+
+<B2B></B2B>
+
+### Roles
+
+In our scenario, Dimitri and Michael share the same organization Hexagon, where as Bill belongs to Octagon. Octagon is owner of the Portal project with its Web App, having Bill configured as user grant with `admin` role. Dimitri ownes the `writer` role, whereas Michael only is `reader`.
+
+> Note: Roles are meant for internal business logic and therefore need to be validated seperately, None of the users described are allowed to create user grants, at least if they do not own a ZITADEL manager role.
+
+If you made a dashboard where some users are able to create user grants, the Management API to do such operations should be triggered with the personal access token of the users, not with a token of a machine user, to create a meaningful audit log. 
+If you had such a usecase, ZITADEL manager roles must be assigned to those users.
+
+### Noteworthy
+
+Due to the fact that ZITADEL is unlimited in users, projects, and applications and comes with all security features in FREE tier, ZITADEL can be considered as better alternative to other SaaS IAM systems such as Auth0 or Keycloack.
+In such a use case with this high potential of scalability where user counts can grow explosively, ZITADEL does not become a bottleneck and therefore is the safer choice. You can learn more on ZITADELs benefits and the pricing [here](https://zitadel.ch/pricing).
+
+### Learn more
+
+- [Creating an organization](../basics/organizations#exercise---create-a-new-organization)
+- [Organization Branding](../customization/branding)
+- [Authorization](../authorization/oauth-recommended-flows)

docs/docs/guides/architecture-scenarios/b2c.mdx

@@ -0,0 +1,115 @@
+---
+title: B2C
+---
+
+import Column from '../../../src/components/column';
+
+## Business to Customer
+
+Users in general come from different domains. You may have customers, employees, or even customers from other parties (B2B). 
+This groups of users usually don't share the same intentions and use applications differently.
+When planning your applications, investing time in reserching your apps architecture is vital for later feature upgrades and enhancements as those changes come in with heftier pricepoints if you have to make bigger changes.
+
+This guide introduces you to the grouping and structuring of ZITADEL projects which forms the base for all projects. This can be used as a quickstart to the [B2B scenario](./b2b), which is merely focused on planning considerations if you are having projects with multiple organizations (Multitenancy).
+
+The journey of this guide starts with creating an Organization, the outermost layer of ZITADEL, as it is, its vessel for projects, roles, applications and users.
+Creation can be done from [ZITADEL Console](https://console.zitadel.ch/org/create). You can choose your current account for the organization owner or create a new one.
+
+Depending on your Software Development Life Cycle (SDLC) you will have to create multiple organizations to keep your data from different environments seperate.
+
+| Environment | Organization Name     | Description             |
+| :---------- | :-------------------- | ----------------------- |
+| Development | **acme-dev**          | The development environment and organization |
+| Testing     | **acme-test**         | An environment for testing and production preview |
+| Production  | **acme-prod**         | The production environment and organization |
+
+### Custom domain
+
+Right after org creation you'll be greeted which the domain section of your organization. ZITADEL automatically creates a custom domain of the form `[orgname].zitadel.ch`, but you can set your own by saving a verification file on the specified location.  
+We recommend that you create your domains early as they create a sense of confidence and trust for your application.
+You can read more about how ZITADEL handles usernames [here](../basics/organizations#how-zitadel-handles-usernames).
+
+### Data Provisioning
+
+Independent to the fact if you are migrating an existing dataset of users into ZITADEL or if your starting a project from scratch, you should define how users get signed up into your application.
+ZITADEL supports signup with OIDC Identity providers as well as JWT Identity Providers. On signup, ZITADEL imports user information to the own profile.
+ZITADEL gives you a basic storage of the user and manages phone and email addresses, but also gives you the option to store your own application data such as preferences or external identifiers to the metadata of a user.
+
+If you are migrating an existing project and you already have an external identity store you can consider bulkimporting your user datasets.
+Read our [Management API definitions](../../apis/proto/management#importhumanuser) for more info. If the users email is not verified or no password is set, a initialization mail will be send. 
+
+:::info
+Requests to the management API are rate limited. Read our [Ratelimit Policy](../../legal/rate-limit-policy) for more info.
+:::
+
+### User Authentication
+
+The process of verifying a users identity is called User Authentication and is required in order for your users to access applications.
+User Authentication can be performed in multiple ways. Default method in ZITADEL is username and password.
+ZITADEL allows you to configure Multifactor Authentication and Passwordless in order to enhance security for your users. All methods including Identity Providers and Passwordless Authentication are starting from FREE Tier.
+To setup your personal login policy, go to your organizations detail in [Console](https://console.zitadel.ch/org).
+
+When planning your application consider the following questions about User Authentication:
+
+- What are the methods to authenticate your users?
+- Where will your users enter their credentials?
+- Do you offer password authentication?
+- What do you do to keep your users credentials safe?
+- Do you offer Multifactor Authentication?
+- Do you offer Login via Identity Provider?
+- Which languages do you have to provide?
+
+When looking at this questions, you may have to admit that building an Identity Management System is much more complex and complicated than you thought initially and implementing if yourself may be too much work. 
+Particularly because you should focus on your own applications business.
+
+### Hosted Login
+
+ZITADEL offers a secure by default approach and comes with a Hosted Login which is a fixed endpoint for your users to authenticate. 
+It's safe and secure and comes with Multifactor, Federated Login and Passwordless.
+OIDC (OpenID Connect) opens the doors Single Sign On (SSO). Especially if you have more than one application, you may want a central and familiar authentication experience. 
+With SSO, ZITADEL provides a seamless experience across all your apps.
+
+### Branding
+
+<Column>
+<div>
+
+Branding and customization is a very important part of your application. 
+With ZITADEL you can modify colors, logos, icons as well as configure your typography styles, such that you can provide a consitent design thoughout your applications.
+In addition to visual modifications, you can edit notification texts for your users. 
+ZITADEL gives you handlebar similar templating for variables. Of course you can define texts for any language.
+We'd appreciate if you could contribute to our repo with translations of your language. Read on how to contribute [here](../../guides/customization/texts).
+
+> Note that your console design changes to your design too
+
+</div>
+<img src="/img/guides/branding.jpeg" alt="branding in console"/>
+</Column>
+
+### Projects and applications
+
+As our Hosted Login is a seperate authentication screen, you have to determine how you are directing your users from your applications.
+ZITADELs Applications live under ZITADELs Projects. You may add multiple Applications for your different apps (Native, Web, User Agent, or API). When setting up you applications consider reading our guide about [Authentication Flows](../authentication/login-users).
+
+### Access Control
+
+By having authenticated a user you need to ensure users and services have access to your application and APIs. This process is called Access Control and comprises User Authentication, Authorization and Policy Enforcement.
+Take the following considerations:
+
+- Does your application call your own APIs?
+- Does your application need to call third-party APIs?
+- Do **you** offer an API for third-party applications?
+
+The data required to check if a user has access to a certain API is stored within a user grant. This information typically is stored within roles or custom claims and can be accessed with an `access` or OIDC `id` token.
+
+...
+
+### Attack prevention?
+
+...
+
+## Learn more
+
+- [Creating an organization](../basics/organizations#exercise---create-a-new-organization)
+- [Organization Branding](../customization/branding)
+- [Authorization](../authorization/oauth-recommended-flows)