docs(scenarios): domain discovery (#5688)

* formatting title configuration

* color generated boxes

* structure

* move saas

* overview

* add integration overview (fixes broken  link on main page)

* instance settings

* user journeys

* fix broken link to saas

* instance considerations

* orgs

* organizations update

* instance settings: domain settings

* heading

* verification and conclusion

* fix diagram

* default org behavior from review

docs/docs/apis/actions/objects.md

@@ -194,7 +194,7 @@ This object represents a list of user grant stored in ZITADEL.
 - `grants` Array of
   - `id` *string*
   - `projectGrantId` *string*  
-    The id of the [project grant](../../concepts/usecases/saas#project-grant)
+    The id of the [project grant](/docs/guides/solution-scenarios/saas#project-grant)
   - `state` *Number*  
     <ul><li>0: unspecified</li><li>1: active</li><li>2: inactive</li><li>3: removed</li></ul>
   - `creationDate` *Date*

docs/docs/guides/manage/console/instance-settings.mdx

@@ -175,13 +175,22 @@ If an account is locked, the administrator has to unlock it in the ZITADEL conso
 
 ## Domain settings
 
-In the domain policy you have two different settings.
-One is the "user_login_must_be_domain", by setting this all the users within an organisation will be suffixed with the domain of the organisation.
+### Add organization domain as suffix to loginnames
+
+If you enable this setting, all loginnames will be suffixed with the organization domain. If this settings is disabled, you have to ensure that usernames are unique over all organizations.
+
+### Validate Org domains
+
+If this is enabled all created domains on an organization must be verified per dns/acme challenge.
 
-The second is "validate_org_domains" if this is set to true all created domains on an organisation must be verified per acme challenge.
 More about how to verify a domain [here](/guides/manage/console/organizations#domain-verification-and-primary-domain).
 If it is set to false, all registered domain will automatically be created as verified and the users will be able to use the domain for login.
 
+### SMTP Sender Address matches Instance Domain
+
+If enabled, the SMTP server address must match the instance's primary domain.
+With that you can ensure that users receive notifications from the same domain that is used for login.
+
 ### Use email as username
 
 To be able to use the email as username you have to disable the attribute "User Loginname must contain orgdomain" on your domain settings.
@@ -190,6 +199,8 @@ All usernames will then be globally unique within your instance.
 
 You can either set this attribute on your whole ZITADEL instance or just on some specific organizations.
 
+Please refer to the [configuration guide](/docs/guides/solution-scenarios/configurations#use-email-to-login) for more information.
+
 ## Privacy Policy and TOS
 
 With this setting you are able to configure your privacy policy, terms of service, help links and help/support email address.

docs/docs/guides/manage/console/organizations.mdx

@@ -67,6 +67,10 @@ Please note that domain verification also removes the logonname from all users,
 
 ## Verify your domain name
 
+:::info
+You can also disable domain verification with DNS challenge in the [instance settings](/docs/guides/manage/console/instance-settings#domain-settings).
+:::
+
 1. Browse to your organization
 2. Click **Add Domain**
 3. To start the domain verification click the domain name and a dialog will appear, where you can choose between DNS or HTTP challenge methods.
@@ -75,7 +79,9 @@ Please note that domain verification also removes the logonname from all users,
 
 ![Verify Domain](/img/console_verify_domain.gif)
 
-> **_Please note:_** Do not delete the verification code, as ZITADEL will re-check the ownership of your domain from time to time
+:::caution
+Do not delete the verification code, as ZITADEL will re-check the ownership of your domain from time to time
+:::
 
 ## Organization Settings
 
@@ -97,3 +103,12 @@ Those settings are the same as on your instance.
 If you need custom branding on a organization (for example in a B2B scenario, where organizations are allowed to use their custom design), navigate back to the home page, choose your organization in the header above, navigate to the organization settings and set the custom design here.
 
 The behaviour of the login page, applyling custom design, is then defined on your projects detail page. Read more about it [here](./projects#branding)
+
+## Default organization
+
+On the instance settings page ($YOUR_DOMAIN//ui/console/orgs) you can set an organization as default organization.
+Click the "..." on the right hand side of the table and select "Set as default organization".
+
+The current default organization is marked by a label "Default".
+
+When no organization was selected (eg, with the auth request or through [Domain Discovery](/docs/guides/solution-scenarios/domain-discovery)), then all users are allowed to login and users can self-register to this default organization.

docs/docs/guides/solution-scenarios/configurations.mdx

@@ -1,6 +1,6 @@
 ---
 title: How to configure ZITADEL for your scenario
-sidebar_label: FAQ Configurations
+sidebar_label: Common configurations
 ---
 
 Each customer does have different needs and use-cases. In ZITADEL you are able to configure your settings depending on your needs.

docs/docs/guides/solution-scenarios/domain-discovery.mdx

@@ -0,0 +1,127 @@
+---
+title: Domain Discovery
+---
+
+This guide should explain how domain discovery works and how to configure it in ZITADEL.
+
+## Overview
+
+Domain discovery is typically used in [B2B](./b2b) or [SaaS](./saas) scenarios where you have users from different organizations and you want to route them according to their login methods, which could be a user name or, depending on your configuration, also an [email / phone number](configurations#use-email-to-login).
+
+![Overview Domain Discovery](/img/guides/solution-scenarios/domain-discovery.png)
+
+In the example there is a service provider with a ZITADEL instance running on a [custom domain](/docs/guides/manage/cloud/instances#add-custom-domain) on `login.mycompany.com`.
+By default all users login on the organization **CIAM** with their preferred social login provider.
+
+Users of the two business customers **Alpha** and **Beta** should login according to their organization login and access policy settings.
+In case of Alpha users will login via an external identity provider (eg, [AzureAD](/docs/guides/integrate/identity-providers/azure-ad)).
+Beta users must only login with username/password and MFA instead.
+
+For this scenario you need to route the user `alice@alpha.com` to the **Alpha Organization** and `bob@beta.com` to the **Beta Organization** respectively.
+
+Follow this guide to configure your ZITADEL instance for this scenario.
+
+## Instance
+
+### Default Login Page
+
+You will use the instance default settings for the login for the organization **CIAM**.
+When opening `login.mycompany.com` then the login policy of the instance will be applied.
+This means that you have to configure the [Login and Access](/docs/guides/manage/console/instance-settings#login-behaviour-and-access) Policy and [Identity Providers](/docs/guides/manage/console/instance-settings#identity-providers) for the **CIAM** users on the instance itself.
+
+:::info
+You can also configure these settings on the default organization (see below) and send the scope `urn:zitadel:iam:org:id:{id}` with every [auth request](/docs/apis/openidoauth/authrequest#organization-policies-and-branding).
+:::
+
+### Default Organization
+
+Set **CIAM** as [default organization](/docs/guides/manage/console/organizations#default-organization).
+You will find the overview of all organizations under the "Organizations" tab on the Instance Settings.
+
+The default organization will hold all unmatched users, ie. all users that are not specifically in the organizations **Alpha** or **Beta** in the example.
+
+### Enable Domain Discovery
+
+In the [Login Behavior and Security Settings](/docs/guides/manage/console/instance-settings#login-behaviour-and-access) enable "Domain discovery allowed"
+
+### Configure login with email
+
+Follow this [configuration guide](/docs/guides/solution-scenarios/configurations#use-email-to-login) to allow users to login with their email address.
+
+### Other considerations
+
+You can also have multiple custom domains pointing to the same instance as described in this [configuration guide](/docs/guides/solution-scenarios/configurations#custom-application-domain-per-organization). In our example you could also use `alpha.mycompany.com` to show the login page of your instance.
+
+The domain of your email notification can be changed by [setting up your SMTP](/docs/guides/manage/console/instance-settings#smtp).
+
+## Organization
+
+### Alpha organization
+
+Users of **Alpha** should only be allowed to authenticate with their company's identity provider.
+
+In the organization settings under Login Behavior and Access make sure the following settings are applied:
+
+- **Username Password allowed**: Disabled
+- **Register allowed**: Disabled - we will configure this on the external identity provider
+- **External IDP allowed**: Enabled
+
+Now you can configure an [external identity provider](/docs/guides/manage/console/instance-settings#identity-providers).
+
+:::info
+Given you have only one external identity provider configured, when a user tries to login on that organization, then the user will be automatically redirected to the external identity provider.  
+In case multiple providers are configured, then the user will be prompted to select an identity provider.
+:::
+
+### Beta organization
+
+Users of **Beta** must create an account and login with password and 2FA.
+
+In the organization settings under Login Behavior and Access make sure the following settings are applied:
+
+- **Username Password allowed**: Enabled
+- **Register allowed**: Disabled - you may want [Managers](/docs/concepts/structure/managers) to setup accounts.
+- **External IDP allowed**: Disabled
+
+Make sure to [Force MFA](/docs/guides/manage/console/instance-settings#multifactor-mfa) so that users must setup a second factor for authentication.
+
+### Verify domains
+
+Switch to the organization **Alpha** and select the tab "Domains". 
+Verify the domain alpha.com following the [organization guide](/docs/guides/manage/console/organizations#domain-verification-and-primary-domain).
+
+Do the same for the **Beta** organization.
+
+:::info
+You can also disable domain verification with acme challenge in the [instance settings](/docs/guides/manage/console/instance-settings#domain-settings).
+:::
+
+## Conclusion
+
+You should be all setup to try out domain discovery.
+
+The user journeys for the different users would look as follows: 
+
+- User (Alice, Bob, Chuck) clicks a login button in your application
+- Redirected to `login.mycompany.com` (ZITADEL running under a custom domain)
+
+Chuck
+
+1. Select Google button
+1. Redirect to Google IDP
+1. Chuck logs in with Google credentials
+1. Redirected back to your application
+
+Alice
+
+1. Alice enters alice@alpha.com and clicks next
+1. Redirect to AzureAD Tenant (or any other IDP)
+1. Alice logs in with her company credentials
+1. Redirected back to your application
+
+Bob
+
+1. Bob enters bob@beta.com and clicks next
+1. Bob will be redirected to a login with the branding of beta.com
+1. Bob enters his password and MFA on the login screen
+1. Redirected back to your application

docs/sidebars.js

@@ -126,8 +126,14 @@ module.exports = {
     {
       type: "category",
       label: "Integrate",
+      link: {
+        type: "generated-index",
+        title: "Integrate",
+        slug: "guides/integrate",
+        description:
+          "Integrate your users and application with ZITADEL. In this section you will find resource on how to authenticate your users, configure external identity providers, access the ZITADEL APIs to manage resources, and integrate with third party services and tools.",
+      },
       items: [
-
         {
           type: "category",
           label: "Authenticate Users",
@@ -234,12 +240,19 @@ module.exports = {
     {
       type: "category",
       label: "Solution Scenarios",
+      link: {
+        type: "generated-index",
+        title: "Solution Scenarios",
+        slug: "guides/solution-scenarios/introduction",
+        description:
+          "Customers of an SaaS Identity and Access Management System usually have all distinct use cases and requirements. This guide attempts to explain real-world implementations and break them down into Solution Scenarios which aim to help you getting started with ZITADEL.",
+      },
       collapsed: true,
       items: [
-        "guides/solution-scenarios/introduction",
         "guides/solution-scenarios/b2c",
         "guides/solution-scenarios/b2b",
-        "concepts/usecases/saas",
+        "guides/solution-scenarios/saas",
+        "guides/solution-scenarios/domain-discovery",
         "guides/solution-scenarios/configurations",
       ],
     },

docs/src/css/custom.css

@@ -291,6 +291,7 @@ h2 {
   --ifm-color-warning-dark: #4f566b;
   --ifm-toc-border-color: rgba(135, 149, 161, 0.2);
   --ifm-table-border-color: rgba(135, 149, 161, 0.2);
+  --ifm-card-background-color: #1a253c;
   --card-background: #1a253c; /* #1a1d46; */
   --list-background: #1a253c; /* #1a1d46; */
   --apiauthbackground: linear-gradient(40deg, #506e6e90 30%, #506e6e90);