mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-14 01:45:12 +00:00
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
This commit is contained in:
mffap
@@ -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.
|
||||
|
||||
@@ -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,
|
||||
|
||||
|
||||
|
||||
> **_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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
|
||||
|
||||
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 `[email protected]` to the **Alpha Organization** and `[email protected]` 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 [email protected] 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 [email protected] 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
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
title: Introduction
|
||||
---
|
||||
|
||||
import {
|
||||
ListElement,
|
||||
ListWrapper,
|
||||
ICONTYPE,
|
||||
} from "../../../src/components/list";
|
||||
import Column from "../../../src/components/column";
|
||||
|
||||
## Solution Scenarios
|
||||
|
||||
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.
|
||||
|
||||
<ListWrapper title="Solution Scenarios">
|
||||
<ListElement
|
||||
link="./b2c"
|
||||
iconClasses="las la-paragraph"
|
||||
roundClasses="custom-rounded rounded-split"
|
||||
label="B2C"
|
||||
title="Business to Consumer"
|
||||
description="Organizations with your SDLC, Domains, Authentication, Hosted Login"
|
||||
/>
|
||||
<ListElement
|
||||
link="./b2b"
|
||||
iconClasses="las la-paragraph"
|
||||
roundClasses="custom-rounded rounded-split"
|
||||
label="B2B"
|
||||
title="Business to Business"
|
||||
description="Planning considerations, B2B Sample Case"
|
||||
/>
|
||||
</ListWrapper>
|
||||
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: SaaS Product with Authentication and Authorization
|
||||
sidebar_label: Software-as-a-Service
|
||||
---
|
||||
|
||||
This is an example architecture for a typical SaaS product.
|
||||
To illustrate it, a fictional organization and project is used.
|
||||
|
||||
## Example Case
|
||||
|
||||
The Timing Company has a product called Time.
|
||||
They have two environments, the development and the production environment.
|
||||
In this case Time uses authentication and authorizations from ZITADEL.
|
||||
This means that the users and also their authorizations will be managed within ZITADEL.
|
||||
|
||||
|
||||
|
||||
## Organization
|
||||
|
||||
An organization is the ZITADEL resource which contains users, projects, applications, policies and so on.
|
||||
In an organization projects and users are managed by the organization.
|
||||
You need at least one organization for your own company in our case "The Timing Company".
|
||||
As next step grate an organization for each of your costumers.
|
||||
|
||||
## Project
|
||||
|
||||
The idea of projects is to have a vessel for all components who are closely related to each other.
|
||||
|
||||
In this use case we would have two different projects, for each environment one. So lets call it "Time Dev" and "Time Prod".
|
||||
These projects should be created in "The Timing Company" organization, because it is the owner of the project.
|
||||
|
||||
In the project you will configure all your roles and applications (clients and APIs).
|
||||
|
||||
### Project Settings
|
||||
|
||||
You can configure `check roles on authentication` on the project, if you want to restrict access to users that have the correct authorization for the project.
|
||||
|
||||
### Project Grant
|
||||
|
||||
To give a customer permissions to a project, a project grant to the customers organization is needed (search the granted organization by its domain).
|
||||
It is also possible to delegate only specific roles of the project to a certain customer.
|
||||
As soon as a project grant exists, the customer will see the project in the granted projects section of his organization and will be able to authorize his own users to the given project.
|
||||
|
||||
## Authorizations
|
||||
|
||||
To give a user permission to a project an authorization is needed.
|
||||
All organizations which own the project or received a grant are able to authorize users.
|
||||
It is also possible to authorize users outside the own company if the exact login name of the user is known.
|
||||
|
||||
## Project Login
|
||||
|
||||
There are some different use cases how the login should behave and look like:
|
||||
|
||||
1. Restrict Organization
|
||||
|
||||
With the primary domain scope the organization will be restricted to the requested domain, this means only users of the requested organization will be able to login.
|
||||
The private labeling (branding) and the login policy of the requested organization will be set automatically.
|
||||
|
||||
:::note
|
||||
More about the [Scopes](/apis/openidoauth/scopes)
|
||||
:::
|
||||
|
||||
2. Show private labeling (branding) of the project organization
|
||||
|
||||
You can configure on project-level which branding should be shown to users.
|
||||
In the default the design of the instance will be shown, but as soon as the user is identified, the policy of the users organization (if specified) will be triggered.
|
||||
If the setting is set to `Ensure Project Resource Owner Setting`, the private labeling of the project organization will always be triggered.
|
||||
The last possibility is to show the private labeling of the project organization and as soon as the user is identified the user organization settings will be triggered.
|
||||
For this the Allow User Resource Owner Setting should be set.
|
||||
:::note
|
||||
More about [Private Labeling](/guides/manage/customize/branding)
|
||||
:::
|
||||
Reference in New Issue
Block a user