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/authentication/authmethods.mdx

@@ -5,6 +5,7 @@ import PKCE from "./authmethods/pkce.mdx";
 import Basic from "./authmethods/basic.mdx";
 import Implicit from "./authmethods/implicit.mdx";
 import PKCENative from "./authmethods/pkcenative.mdx";
+import JWTPrivateKey from "./authmethods/jwtpk.mdx";
 
 export default function AuthMethods(props) {
   return props.selected == "web" ? (
@@ -15,7 +16,7 @@ export default function AuthMethods(props) {
         values={[
           { label: "PKCE", value: "pkce" },
           { label: "Basic Auth", value: "basic" },
-          { label: "JWT with Private Key", value: "jwt" },
+          { label: "JWT with Private Key", value: "jwtpk" },
         ]}
       >
         <TabItem value="pkce">
@@ -24,8 +25,8 @@ export default function AuthMethods(props) {
         <TabItem value="basic">
           <Basic />
         </TabItem>
-        <TabItem value="implicit">
-          <Implicit />
+        <TabItem value="jwtpk">
+          <JWTPrivateKey />
         </TabItem>
       </Tabs>
     </div>

docs/docs/guides/authentication/authmethods/basic.mdx

@@ -0,0 +1,78 @@
+#### redirect_uri
+
+After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
+The redirect_uri will be called after user authentication for code exchange.
+
+You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
+or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
+
+## Auth Request
+
+To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
+on /authorize with at least the following parameters:
+
+- `client_id`: this tells the authorization server which application it is, copy from Console
+- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
+- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
+- `scope`: what scope you want to grant to the access_token / id_token, minimum is `openid`, if you're unsure what you need you might start with `openid profile email`
+
+We recommend always using two additional parameters `state` and `nonce`. The former enables you to transfer a state through
+the authentication process. The latter is used to bind the client session with the id_token and to mitigate replay attacks.
+
+You don't need any additional parameter for this request. We're identifying the app by the `client_id` parameter.
+
+So your request might look like this (linebreaks and whitespace for display reasons):
+
+```curl
+curl --request GET \
+  --url 'https://accounts.zitadel.ch/oauth/v2/authorize
+    ?client_id=${client_id}
+    &redirect_uri=${redirect_uri}
+    &response_type=code
+    &scope=openid%20email%20profile'
+```
+
+### Additional parameters and customization
+
+There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
+Please check the [authorization_endpoint reference](../../apis/openidoauth/endpoints#authorization_endpoint) in the OAuth / OIDC documentation.
+
+## Callback
+
+Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your
+callback endpoint you provided by the `redirect_uri`.
+
+:::note
+If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client,
+the error will be display directly to the user on the auth server.
+:::
+
+Upon successful authentication you'll be given a `code` and if provided the unmodified `state` parameter.
+You will need this `code` in the token request.
+
+If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
+possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
+Check the [error response section](../../apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.
+
+## Token request
+
+Next you will have to exchange the given `code` for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:
+
+- code: the code that was issued from the authorization request
+- grant_type: must be `authorization_code`
+- redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request
+
+Depending on your authentication method you'll need additional headers and parameters:
+
+Send your `client_id` and `client_secret` as Basic Auth Header. Note that OAuth2 requires client_id and client_secret to be form url encoded.
+So check [Client Secret Basic Auth Method](../../apis/openidoauth/authn-methods#client-secret-basic) on how to build it correctly.
+
+```curl
+curl --request POST \
+--url https://api.zitadel.ch/oauth/v2/token \
+--header 'Authorization: Basic ${basic}' \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data grant_type=authorization_code \
+--data code=${code} \
+--data redirect_uri=${redirect_uri}
+```

docs/docs/guides/authentication/authmethods/implicit.mdx

@@ -8,3 +8,42 @@ We therefore discourage the use of Implicit Flow and do not cover the flow in th
 
 If you still need to rely on the implicit flow, simply keep in mind that the response on the authorization_endpoint is
 the same you would be given on the token_endpoint and check the [OAuth / OIDC endpoint documentation](../../../apis/openidoauth/endpoints.md) for more information.
+
+#### redirect_uri
+
+After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
+The redirect_uri will be called after user authentication for code exchange.
+
+You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
+or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
+
+## Auth Request
+
+To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
+on /authorize with at least the following parameters:
+
+- `client_id`: this tells the authorization server which application it is, copy from Console
+- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
+- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
+- `scope`: what scope you want to grant to the access_token / id_token, minimum is `openid`, if you're unsure what you need you might start with `openid profile email`
+
+When using the Implicit Flow you will also have to provide a `nonce` parameter to bind the client session to the id_token and to mitigate replay attacks. Furthermore, we recommend using a `state` parameter, which enables you to transfer a state through the authentication process.
+
+### Additional parameters and customization
+
+There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
+Please check the [authorization_endpoint reference](../../apis/openidoauth/endpoints#authorization_endpoint) in the OAuth / OIDC documentation.
+
+## Callback
+
+Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your callback endpoint you provided by the `redirect_uri`.
+
+:::note
+If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client, the error will be display directly to the user on the auth server.
+:::
+
+Upon successful authentication you'll be given the `access_token`, `id_token`, `expires_in` and if provided the unmodified `state` parameter, as you would be given from the token_endpoint when using Authorization Code Flow.
+
+If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
+possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
+Check the [error response section](../../apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.

docs/docs/guides/authentication/authmethods/jwtpk.mdx

@@ -0,0 +1,79 @@
+#### redirect_uri
+
+After selecting the authentication method, you can register a redirect_uri and post_logout_redirect_uri.
+The redirect_uri will be called after user authentication for code exchange.
+
+You can even register multiple, but typically one will be enough. If you need to distinguish between different scenarios
+or environments we recommend using the `state` parameter for the former and multiple projects for the latter.
+
+## Auth Request
+
+To initialize the user authentication, you will have to create an authorization request using HTTP GET in the user agent (browser)
+on /authorize with at least the following parameters:
+
+- `client_id`: this tells the authorization server which application it is, copy from Console
+- `redirect_uri`: where the authorization code is sent to after the user authentication, must be one of the registered in the previous step
+- `response_type`: if you want to have a code (authorization code flow) or directly a token (implicit flow), so when ever possible use `code`
+- `scope`: what scope you want to grant to the access_token / id_token, minimum is `openid`, if you're unsure what you need you might start with `openid profile email`
+
+We recommend always using two additional parameters `state` and `nonce`. The former enables you to transfer a state through
+the authentication process. The latter is used to bind the client session with the id_token and to mitigate replay attacks.
+
+You don't need any additional parameter for this request. We're identifying the app by the `client_id` parameter.
+
+So your request might look like this (linebreaks and whitespace for display reasons):
+
+```curl
+curl --request GET \
+  --url 'https://accounts.zitadel.ch/oauth/v2/authorize
+    ?client_id=${client_id}
+    &redirect_uri=${redirect_uri}
+    &response_type=code
+    &scope=openid%20email%20profile'
+```
+
+### Additional parameters and customization
+
+There are additional parameters and values you can provide to satisfy your use case and to customize the user's authentication flow.
+Please check the [authorization_endpoint reference](../../apis/openidoauth/endpoints#authorization_endpoint) in the OAuth / OIDC documentation.
+
+## Callback
+
+Regardless of a successful or error response from the authorization_endpoint, the authorization server will call your
+callback endpoint you provided by the `redirect_uri`.
+
+:::note
+If the redirect_uri is not provided, was not registered or anything other prevents the auth server form returning the response to the client,
+the error will be display directly to the user on the auth server.
+:::
+
+Upon successful authentication you'll be given a `code` and if provided the unmodified `state` parameter.
+You will need this `code` in the token request.
+
+If a parameter was missing, malformed or any other error occurred, your answer will contain an `error` stating the error type,
+possibly an `error_description` providing some information about the error and its reason and the `state` parameter.
+Check the [error response section](../../apis/openidoauth/endpoints#error-response) in the authorization_endpoint reference.
+
+## Token request
+
+Next you will have to exchange the given `code` for the tokens. For this HTTP POST request (form-urlencoded) you will need to provide the following:
+
+- code: the code that was issued from the authorization request
+- grant_type: must be `authorization_code`
+- redirect_uri: callback uri where the code was sent to. Must match exactly the redirect_uri of the authorization request
+
+Depending on your authentication method you'll need additional headers and parameters:
+
+Send a JWT in the `client_assertion` and set the `client_assertion_type` to `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`
+for us to validate the signature against the registered public key:
+
+```curl
+curl --request POST \
+--url https://api.zitadel.ch/oauth/v2/token \
+--header 'Content-Type: application/x-www-form-urlencoded' \
+--data grant_type=authorization_code \
+--data code=${code} \
+--data redirect_uri=${redirect_uri} \
+--data client_assertion=${client_assertion} \
+--data client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
+```