mirror of
https://github.com/andwati/zitadel.git
synced 2026-11-02 04:12:16 +00:00
d8ea041c56
## Todos for release - [x] Configure Env in docs project on vercel - [x] Configure Root Path in the docs project on vercel - [ ] Remove old CSP https://github.com/zitadel/website/pull/1592 ## What we did This pull request migrates the project documentation from the old `docs/` directory to the new `apps/docs/` directory, introduces a new documentation system built with Next.js and Fumadocs, and updates all relevant references, configuration files, and documentation to reflect this change. It also adds new configuration and ignore files for the new documentation app, updates CI and linting to exclude the new docs from certain checks, and revises the contributing guidelines accordingly. **Documentation System Migration and New Docs App** * Migrated all documentation from `docs/` to `apps/docs/`, and updated all references in `README.md`, `CONTRIBUTING.md`, and other files to point to the new location. [[1]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L585-L640) [[2]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L660-R607) [[3]](diffhunk://#diff-eca12c0a30e25b4b46522ebf89465a03ba72a03f540796c979137931d8f92055L740-R687) [[4]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L2-R3) [[5]](diffhunk://#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5L30-R30) * Added a new Next.js/Fumadocs-based documentation app under `apps/docs/`, including core app files, layouts, routing, search API, and a comprehensive `README.md` with development and contribution instructions. [[1]](diffhunk://#diff-5a1b07344a2c1b4d3f37b23ff1388b62cd9f57dea3c1cd23d8a0412b7602b132R1-R74) [[2]](diffhunk://#diff-462b9ad1eabbb7d1c29bb9c36e4931eb180fd7190900e6d2babf8f4d66ad1c28R1-R39) [[3]](diffhunk://#diff-e16ae25660ded787b10ac35dea96d5ecaacf895dae0afc8a9bd4382dc79a8c87R1-R7) [apps/docs/app/[[...slug]]/layout.tsxR1-R81](diffhunk://#diff-59e08acde4e805b7aeccef1dcf98f1d71dfc550777e6b9402085cee0e9fa4e0aR1-R81), [apps/docs/app/[[...slug]]/page.tsxR1-R79](diffhunk://#diff-e5df3f80d0fa01e12d63d81f29c57a9d14e846c78fd3beabb2ef768e38fd9580R1-R79), [[4]](diffhunk://#diff-389b34918e040cacaa87cd7201ffa462cc2b0b716736f537e3d3c660ac69353bR1-R7) [[5]](diffhunk://#diff-d3b03416d1c457b19f1c27b26f2db741412df841b875c26ccadc36e4522247f4R1-R29) [[6]](diffhunk://#diff-c8fb8339570a5305809be7c618e14705fd86390dc278e6ce8ba224a7bc8b0c3cR1-R25) **Configuration and Tooling Updates** * Updated `.github/workflows/codeql.yml`, `.golangci.yaml`, and `.github/dependabot.yml` to properly handle the new docs app: excluded `apps/docs` from certain checks, added npm dependency updates for the docs app, and excluded generated content. [[1]](diffhunk://#diff-12783128521e452af0cfac94b99b8d250413c516ec71fe6d97dbea666ff7ba27L8-R14) [[2]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R5-R6) [[3]](diffhunk://#diff-9917ddc9f1c3304218f7269265b746d997c5c0615478177b5fceecd33ef47cb5R126-R129) [[4]](diffhunk://#diff-dd4fbda47e51f1e35defb9275a9cd9c212ecde0b870cba89ddaaae65c5f3cd28R89-R106) * Updated `.devcontainer/devcontainer.json` to use the latest Go 1.25.3 version for consistency. **Licensing and Miscellaneous** * Added `apps/docs/` to the list of licensed directories in `LICENSING.md`. These changes ensure the documentation is now maintained in a modern, scalable system and all project tooling is updated to support the new structure. --------- Co-authored-by: Federico Coppede <[email protected]>
129 lines
5.9 KiB
Plaintext
129 lines
5.9 KiB
Plaintext
---
|
|
title: Domain Discovery in ZITADEL
|
|
sidebar_label: 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](/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, [Entra ID](/guides/integrate/identity-providers/azure-ad-oidc)).
|
|
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](/guides/manage/console/default-settings#login-behavior-and-access) Policy and [Identity Providers](/guides/manage/console/default-settings#identity-providers) for the **CIAM** users on the instance itself.
|
|
|
|
<Callout>
|
|
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](https://zitadel.com/playgrounds/oidc).
|
|
</Callout>
|
|
|
|
### Default Organization
|
|
|
|
Set **CIAM** as [default organization](/guides/manage/console/organizations-overview#default-organization).
|
|
You will find the overview of all organizations under the "Organizations" tab on the Default 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](/guides/manage/console/default-settings#login-behavior-and-access) enable "Domain discovery allowed"
|
|
|
|
### Configure login with email
|
|
|
|
Follow this [configuration guide](/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](/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](/guides/manage/console/default-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](/guides/manage/console/default-settings#identity-providers).
|
|
|
|
<Callout>
|
|
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.
|
|
</Callout>
|
|
|
|
### 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](/concepts/structure/managers) to setup accounts.
|
|
- **External IDP allowed**: Disabled
|
|
|
|
Make sure to [Force MFA](/guides/manage/console/default-settings#multifactor-mfa) so that users must setup a second factor for authentication.
|
|
|
|
### Verify domains
|
|
|
|
Switch to the organization **Alpha** and navigate to the settings and "Verified domains".
|
|
Verify the domain alpha.com following the [organization guide](/guides/manage/console/organizations-overview#usernames-and-domains).
|
|
|
|
Do the same for the **Beta** organization.
|
|
|
|
<Callout>
|
|
You can also disable domain verification with acme challenge in the [default settings](/guides/manage/console/default-settings#domain-settings).
|
|
</Callout>
|
|
|
|
## 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 Entra ID 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
|