docs(integrate): Update login users docs (#7414)

* wip

* update intro of device auth

* add custom domain concept

* wip sidebar

* wip introduction

* add passkeys

* replace azure ad with entra id

* wip

* wip

* login methods

* expand sections automatically

* update selfservice docs

* wip - hosted done

* move onboarding

* clean up

* wip

* unbreak my hrefs

* finish login users

* update managers

* add console as feature

* update b2b with multi-tenancy

* update saml

* update console concept

* add opaque tokens as knowledge

* redirects

* intro b2b

* remove login/saml

* unbreak link

* Apply suggestions from code review

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

* passkeys: add custom domain first

* update passkeys

* Apply suggestions from code review

Co-authored-by: Florian Forster <florian@zitadel.com>

* Update docs/docs/guides/integrate/login/login-users.mdx

Co-authored-by: Florian Forster <florian@zitadel.com>

---------

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

docs/docs/concepts/features/console.md

@@ -0,0 +1,33 @@
+---
+title: "ZITADEL Console: Resource management and customization"
+sidebar_label: Console
+---
+
+The ZITADEL console is a web-based interface designed to facilitate the management and administration of ZITADEL resources and configurations.
+It serves as a central hub where administrators can perform various tasks related to identity and access management within their organization's infrastructure.
+
+The console is available by navigating to the [custom domain](/docs/concepts/features/custom-domain) of your instance and appending the path `/ui/console`.
+Administrators can [restrict end-users from accessing the console](/docs/guides/solution-scenarios/restrict-console).
+
+Here's an overview of what the console enables users to do:
+
+1. **Default Settings:** [Managers](/docs/concepts/structure/managers) can access and manage the default settings of the ZITADEL system. This includes configuring authentication methods, security policies, and other system-wide parameters to meet the organization's requirements.
+
+2. **Resource Management:** The console allows for the creation, updating, and deletion of essential resources such as organizations, users, projects, and applications. Administrators can efficiently manage these entities to ensure proper access control and governance.
+
+3. **User Management:** Administrators can manage user accounts, including creating new user accounts, updating user profiles, resetting passwords, and deactivating or deleting user accounts as needed.
+
+4. **Access Control:** The console provides tools for defining and managing access control policies. This includes assigning roles and permissions to users, configuring fine-grained access controls, and managing access to specific resources.
+
+5. **Audit Logging:** The console offers access to [audit logs](/docs/concepts/features/audit-trail) that track user activity and changes made to resources and system settings. Administrators can review these logs to monitor security-related events, track changes, and maintain compliance with regulatory requirements.
+
+6. **Customization and Branding:** The console allows organizations to customize the branding and appearance of their ZITADEL instance. This includes uploading custom logos, selecting color schemes, and applying other visual customizations to align the interface with the organization's branding guidelines.
+
+7. **Manager Assignment:** Administrators can assign ZITADEL [managers](/docs/concepts/structure/managers) who have elevated privileges for managing resources within the organization. This allows for the delegation of administrative tasks while maintaining proper oversight and control.
+
+Overall, the ZITADEL console serves as a comprehensive tool for administrators to configure, manage, and monitor identity and access management within their organization, providing the necessary controls to ensure security, compliance, and efficient administration of resources.
+
+Notes:
+
+- Detailed guide on [using the console](/docs/guides/manage/console/overview)
+- [Restrict access](/docs/guides/solution-scenarios/restrict-console) to the console

docs/docs/concepts/features/custom-domain.md

@@ -0,0 +1,13 @@
+---
+title: Custom domain
+sidebar_label: Custom domain
+---
+
+A ZITADEL custom domain refers to the ability for organizations to personalize the authentication experience by using their own domain name rather than the default ZITADEL domain.
+
+This feature allows organizations to maintain their brand identity throughout the authentication process, providing a seamless and consistent user experience.
+By configuring a custom domain within ZITADEL, organizations can replace the default authentication URLs with their own domain, such as "login.example.com" or "auth.companyname.com".
+
+This not only enhances the overall user experience but also reinforces the organization's brand presence. Additionally, custom domains can contribute to trust and credibility, as users are more likely to recognize and trust URLs associated with the organization rather than generic domains. Overall, ZITADEL's custom domain feature empowers organizations to tailor the authentication process to align with their brand identity and user expectations.
+
+Learn how to [configure a custom domain in ZITADEL Cloud](http://localhost:3000/docs/guides/manage/cloud/instances#add-custom-domain) or how to configure [custom domain when self-hosting](http://localhost:3000/docs/self-hosting/manage/custom-domain).

docs/docs/concepts/features/passkeys.md

@@ -0,0 +1,37 @@
+---
+title: "Passkeys in ZITADEL: Passwordless phishing-resistant authentication"
+sidebar_label: Passkeys
+---
+
+ZITADEL's passkeys feature enables passwordless authentication, offering a **smoother and more secure** login experience for your users. This document explains the essential details for developers.
+
+### What are Passkeys?
+
+Imagine signing in without passwords! Passkeys, replacing traditional passwords, leverage **public-key cryptography** similar to FIDO2 and WebAuthn. Users rely on their devices' **biometrics or PINs** for authentication, eliminating password burdens.
+
+### Benefits for Developers
+
+* **Enhanced Security:** Phishing-resistant passkeys minimize credential theft risks.
+* **Streamlined User Experience:** Faster, easier logins free users from managing passwords.
+* **Platform Agnostic:** Works across devices and platforms supporting passkeys.
+* **Modern Standard:** Complies with the FIDO2 and WebAuthn standards.
+
+### Features
+
+* **Seamless Registration:** Create unique passkeys for users on various devices. Optionally pair them with specific users and choose cross-platform or platform-specific options.
+* **User Control:** Users manage their passkeys directly through ZITADEL's self-service portal, allowing registration, viewing, and deletion.
+* **Intuitive Login:** Users initiate passwordless login by selecting the passkey option and verifying themselves with the device's biometrics (fingerprint, face ID, etc.).
+* **Robust Fallback:** Traditional password login remains available for users without passkeys.
+
+### Developer Resources
+
+* **Documentation:** Passkeys Guide: [https://zitadel.com/docs/guides/integrate/login-ui/passkey](/docs/guides/integrate/login-ui/passkey)
+* **Create Passkey Registration Link API:** [https://zitadel.com/docs/guides/manage/user/reg-create-user](/docs/guides/manage/user/reg-create-user)
+
+### Notes
+
+* Passkey support is still evolving in browsers and platforms. Check compatibility for your target audience.
+* ZITADEL actively develops its passkey features. Stay updated with documentation and releases.
+* Passkeys are bound to your domain, thus we recommend configuring a [custom domain](/docs/concepts/features/custom-domain.md) before setting up passkeys.
+
+Don't hesitate to ask if you have further questions about integrating passkeys in your ZITADEL application!

docs/docs/concepts/features/selfservice.md

@@ -57,43 +57,6 @@ When you login with an external identity provider, and the user does not exist i
 
 ## Login
 
-:::info Customization and Branding
-The login page can be changed by customizing different branding aspects and you can define a custom domain for the login (eg, login.acme.com).
-
-By default, the displayed branding is defined based on the user's domain. In case you want to show the branding of a specific organization by default, you need to either pass a primary domain scope (`urn:zitadel:iam:org:domain:primary:{domainname}`) with the authorization request, or define the behavior on your Project's settings.
-:::
-
-### Web, Mobile, and Single-Page Applications
-
-[This guide](/guides/integrate/login-users) explains in more detail the login-flows for different application types.
-Human users are redirected to ZITADEL's login page and complete sign-in with the interactive login flow.
-It is important to understand that ZITADEL provides a hosted login page and the device of the users opens this login page in a browser, even on Native/Mobile apps.
-
-#### MFA / 2FA
-
-Users are automatically prompted to provide a second factor, when
-
-- Instance or organization [login policy](/concepts/structure/policies#login-policy) is set
-- Requested by the client
-- A multi-factor is setup for the user
-
-When a multi-factor is required, but not set-up, then the user is requested to set-up an additional factor.
-
-#### FIDO Passkeys
-
-Users can select a button to initiate passwordless login or use a fall-back method (ie. login with username/password), if available.
-
-The passwordless login flow follows the FIDO2 / WebAuthN standard.
-Briefly explained the following happens:
-
-- User selects button
-- User's device will ask the user to provide a gesture (e.g., FaceID, Windows Hello, Fingerprint, PIN)
-- The user is being redirected to the application
-
-With the introduction of passkeys the gesture can be provided on ANY of the user's devices.
-This is not strictly the device where the login flow is being executed (e.g., on a mobile device).
-The user experience depends mainly on the used operating system and browser.
-
 ### SSO / Social Logins
 
 Given an external identity provider is configured on the instance or on the organization, then:
@@ -105,31 +68,7 @@ Given an external identity provider is configured on the instance or on the orga
 ### Machines
 
 Machine accounts can't use an interactive login but require other means of authentication, such as privately-signed JWT or personal access tokens.
-Read more about [Service Users](/guides/integrate/serviceusers) and recommended [OpenID Connect Flows](/guides/integrate/oauth-recommended-flows#different-client-profiles).
-
-### Other Clients
-
-We currently do not expose the Login API.
-Whereas you can register users via the management API, you can't login users with our APIs.
-This might be important in cases where you can't use a website (eg, Games, VR, ...).
-
-### Account picker
-
-A list of accounts that were used to log-in are shown to the user.
-The user can click the account in the list and does not need to type the username.
-Users can still login with a different user that is not in the list.
-
-:::info
-This behavior can be changed with the authorization request. Please refer to our [guide](/guides/integrate/login-users).
-:::
-
-### Password reset
-
-Unauthenticated users can request a password reset after providing the loginname during the login flow.
-
-- User selects reset password
-- An email will be sent to the verified email address
-- User opens a link and has to provide a new password
+Read more about [Service Users](/guides/integrate/serviceusers) and recommended [OpenID Connect Flows](/guides/integrate/login/oidc/oauth-recommended-flows#different-client-profiles).
 
 ## Logout
 

docs/docs/concepts/knowledge/opaque-tokens.md

@@ -0,0 +1,70 @@
+---
+title: "Opaque Tokens in Zitadel: Enhancing Application Security"
+sidebar_label: Opaque tokens
+---
+
+In the context of application security, robust authentication mechanisms are essential for safeguarding sensitive data and ensuring user trust.
+Opaque tokens, the default token type within the ZITADEL platform, play a crucial role in bolstering security measures.
+This documentation elucidates the principles behind opaque tokens, their implementation within ZITADEL, and their advantages over alternative token types.
+
+## What are Opaque Tokens?
+
+Opaque tokens are a type of access token utilized in authentication processes, particularly within OAuth 2.0 and OpenID Connect (OIDC) frameworks. Unlike self-contained tokens like [JSON Web Tokens (JWT)](https://datatracker.ietf.org/doc/html/rfc7519), opaque tokens do not divulge user information directly.
+Instead, they serve as opaque references to session data stored securely on the authorization server.
+
+## Authentication Workflow with Opaque Tokens
+
+1. **Token Generation**: When a user initiates an authentication process within an application integrated with ZITADEL, the authentication server generates a unique opaque token associated with the user's session.
+
+2. **Token Presentation**: The generated opaque token is provided to the client, which subsequently presents it during requests to access protected resources within the application.
+
+3. **Token Verification**: Upon receiving the opaque token, the application server interacts with the authorization server to validate its authenticity and retrieve detailed information about the user's session. This process ensures the integrity of the authentication flow and verifies the user's permissions to access requested resources.
+
+## Benefits of Opaque Tokens in ZITADEL
+
+1. **Reduced Token Exposure**: Opaque tokens mitigate the risk of token exposure since they do not contain sensitive user information directly. This reduces the likelihood of token-based attacks and enhances overall security posture.
+
+2. **Enhanced Server-side Control**: With opaque tokens, validation occurs server-side, granting administrators greater control over authentication flows and access policies. This centralized approach facilitates comprehensive monitoring and enforcement of security measures, including server-side single-logout across all applications.
+
+3. **Protection Against Token Tampering**: Opaque tokens prevent unauthorized manipulation of token contents, thereby ensuring the integrity and authenticity of authentication processes. This protection against token tampering further strengthens the security of applications integrated with ZITADEL.
+
+## Opaque Tokens vs. JWT Tokens
+
+When it comes to implementing authentication and authorization mechanisms within applications, developers often face the choice between different types of tokens, each with its own set of characteristics and advantages.
+Two common types of tokens used in authentication protocols are opaque tokens and JSON Web Tokens (JWT).
+
+### Structure
+
+- **Opaque Tokens**: Opaque tokens are essentially references or pointers to information stored on the authorization server. They do not contain any meaningful user data within the token itself. Instead, they typically consist of a unique identifier (e.g., a session ID or database key) that allows the server to look up the associated session information.
+
+- **JWT Tokens**: JSON Web Tokens, on the other hand, are self-contained tokens that contain user information in a JSON format. JWTs consist of three base64-encoded sections: header, payload, and signature. The payload contains claims or assertions about the user (e.g., user ID, roles, expiration time) that are digitally signed to ensure integrity.
+
+### Token verification
+
+- **Opaque Tokens**: Verifying opaque tokens requires interaction with the authorization server. When a client presents an opaque token to a resource server, the resource server sends the token to the authorization server for validation. The authorization server then checks the token's validity and returns the associated user information if the token is valid.
+
+- **JWT Tokens**: JWT tokens can be verified locally by clients without needing to communicate with the authorization server. Clients can validate JWT signatures using public keys or shared secrets obtained during the token issuance process. This decentralized verification process can be faster and more scalable but requires securely distributing and managing keys.
+
+### Token security and size
+
+- **Opaque Tokens**: Since opaque tokens do not contain user information, they are inherently more secure in terms of protecting sensitive data. However, the reliance on server-side validation means there is an overhead associated with each token verification request, which can impact performance in high-throughput scenarios.
+
+- **JWT Tokens**: JWT tokens contain user information within the token itself, which can be convenient for clients as it eliminates the need for frequent interactions with the authorization server. However, this also means that JWT tokens can potentially expose sensitive information if not handled and secured properly. Additionally, JWT tokens tend to be larger compared to opaque tokens due to the encoded payload.
+
+### Use cases and trade-offs
+
+- **Opaque Tokens**: Opaque tokens are well-suited for scenarios where security and confidentiality are top priorities, such as handling highly sensitive user data or complying with strict privacy regulations. They are particularly advantageous in distributed systems where centralized control over authentication and access policies is desired.
+
+- **JWT Tokens**: JWT tokens are often preferred in scenarios where performance and scalability are critical, such as microservices architectures or API-based applications. The ability to verify tokens locally can reduce latency and minimize dependencies on external services. However, developers must carefully consider the implications of including sensitive information in JWT payloads and implement appropriate security measures.
+
+## Conclusion
+
+In conclusion, opaque tokens represent a foundational component in fortifying application security within ZITADEL.
+By leveraging opaque tokens, organizations can establish robust authentication mechanisms, mitigate security risks, and maintain stringent control over access policies.
+As organizations navigate the complex landscape of application security, integrating technologies such as opaque tokens becomes imperative for safeguarding sensitive data and fostering user trust.
+
+Notes: 
+
+- Read more about the differences in our [blog on JWT vs. Opaque tokens](https://zitadel.com/blog/jwt-vs-opaque-tokens)
+- Learn how to use [token introspection](/docs/guides/integrate/token-introspection) to validate access tokens
+- Decode, verify and generate valid JWT tokens with [jwt.io](https://jwt.io/)

docs/docs/concepts/structure/_manager_description.mdx

@@ -1,7 +1,12 @@
-ZITADEL Managers are Users who have permission to manage ZITADEL itself. This means that those users are allowed to login into your instance console and edit certain parts of the configuration.
-There are some different levels for managers.
+Managers are [human users or service users](/docs/concepts/structure/users) who have permission to manage resources within ZITADEL.
 
-- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole Instance.
-- **Org Managers**: Managers in the Organization Level are able to manage everything within the granted Organization.
-- **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.
+Manager permissions can be assigned to different levels in ZITADEL:
+
+- **IAM Managers**: This is the highest level. Users with IAM Manager roles are able to manage the whole [Instance](/docs/concepts/structure/instance).
+- **Org Managers**: Managers in the Organization Level are able to view or manage everything, according to their permissions, within the granted [Organization](/docs/concepts/structure/organizations).
+- **Project Mangers**: In this level the user is able to manage a [project](/docs/concepts/structure/projects).
+- **Project Grant Manager**: The project grant manager is for [granted projects](/docs/concepts/structure/granted_projects) by another organization.
+
+Scope of the managers is restricted based on their level.
+That means a Manager, assigned to one organization, will only get access to resources and configurations of that organization.
+Only Managers on the instance level can view resources, such as users, across all organizations.

docs/docs/concepts/structure/managers.mdx

@@ -7,4 +7,7 @@ import ManagerDescription from "./_manager_description.mdx";
 
 <ManagerDescription name="ManagerDescription" />
 
-To read more on how managers are created and which roles exist read the console guide [here](../../guides/manage/console/managers).
+Notes:
+
+- Read our [guide on Managers](../../guides/manage/console/managers) to learn more about the role concept and how to use Manager roles in ZITADEL.
+- [API reference](/docs/apis/resources/mgmt/management-service-list-org-member-roles) for Managers on organization level