chore: consistent naming for organization domain (#11356)

# Which Problems Are Solved

As part of the consistent naming effort, this PR focuses on
"Organization domain".

# How the Problems Are Solved

- All terms referring referring to Organization Domains where changed to
be Organization Domain

# Additional Changes

None

# Additional Context

- closes [#11283](https://github.com/zitadel/zitadel/issues/11283)

---------

Co-authored-by: Copilot <[email protected]>
This commit is contained in:
Ramon
2026-02-18 14:46:21 +00:00
committed by GitHub
co-authored by Copilot
parent 699ed17918
commit b23346f6ca
78 changed files with 258 additions and 257 deletions
@@ -117,7 +117,7 @@ The information sent to the Endpoint is structured as JSON:
"org": {
"id": "ID of the organization the user belongs to",
"name": "Name of the organization the user belongs to",
"primary_domain": "Primary domain of the organization the user belongs to"
"primary_domain": "Organization Domain the user belongs to"
},
"user_grants": [
{
@@ -211,7 +211,7 @@ The information sent to the Endpoint is structured as JSON:
"org": {
"id": "ID of the organization the user belongs to",
"name": "Name of the organization the user belongs to",
"primary_domain": "Primary domain of the organization the user belongs to"
"primary_domain": "Organization Domain the user belongs to"
},
"user_grants": [
{
@@ -36,7 +36,7 @@ Overall, ZITADEL's hosted login page simplifies the authentication process for d
### Flexible usernames
Different login name formats can be used on ZITADEL's hosted login page to select a user.
Login methods can be a user's username, containing the username and an [organization domain](/guides/manage/console/organizations-overview#usernames-and-domains), their email addresses, or their phone numbers.
Login methods can be a user's username, containing the username and an [Organization Domain](/guides/manage/console/organizations-overview#usernames-and-domains), their email addresses, or their phone numbers.
By default, all of these login methods are allowed and can be adjusted by [Administrators](/concepts/structure/administrators) to meet their requirements.
### Support for multiple authentication methods
@@ -77,7 +77,7 @@ Developers can customize elements such as logos, colors, and messaging to ensure
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](/guides/solution-scenarios/domain-discovery). 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.
By default, the displayed branding is defined [based on the user's domain](/guides/solution-scenarios/domain-discovery). In case you want to show the branding of a specific organization by default, you need to either pass an Organization Domain scope (`urn:zitadel:iam:org:domain:primary:{domainname}`) with the authorization request, or define the behavior on your Project's settings.
</Callout>
### Fast account switching
@@ -21,7 +21,7 @@ At this time Google supports SSO with OpenID Connect only for few providers.
Prerequisites:
- You need to have a domain registered with your Google Workspace account to configure SSO profiles
- Make sure that you [verify the same domain also in your ZITADEL organization and set it as primary domain](/guides/manage/console/organizations-overview#primary-domain)
- Make sure that you [verify the same domain also in your ZITADEL organization and set it as Organization Domain](/guides/manage/console/organizations-overview#organization-domain)
- A user in Google Workspace (eg, [email protected])
- A user in ZITADEL with the same username (eg, [email protected]); make sure you verify the domain to set the username. This is different than the user's email address
@@ -140,7 +140,7 @@ The Login Policy defines how the login process should look like and which authen
| Register allowed | Enable self register possibility in the login ui, this enables username password registration as well as registration with configured external identity providers |
| External IDP allowed | Possibility to login with an external identity (e.g Google, Microsoft, Apple, etc), If you like to allow external Identity providers add them to the providers list |
| Hide password reset | Disable the self-service option for users to reset their password. |
| Domain discovery allowed | If this setting is enabled, the user doesn't have to exist when entering the username. It is required to have verified domains on the organization. Example: ZITADEL is registered as organization with the domain zitadel.com and Entra ID as identity provider. A user enters [email protected] in the login but the user doesn't exist. The domain can be mapped to the organization and therefore the user can be redirected to the Entra ID. |
| Domain discovery allowed | If this setting is enabled, the user doesn't have to exist when entering the username. It is required to have an Organization Domain on the organization. Example: ZITADEL is registered as organization with the domain zitadel.com and Entra ID as identity provider. A user enters [email protected] in the login but the user doesn't exist. The domain can be mapped to the organization and therefore the user can be redirected to the Entra ID. |
| Ignore unknown usernames | This setting can be enabled, if no error message should be shown if the user doesn't exist. Example: A user enters the login name [email protected], the user doesn't exist, but will be redirected to the password screen. After entering a password, the user will get an error that either username or password are wrong. |
| Disable login with email address | By default users can additionally [login with the email attribute](/guides/solution-scenarios/configurations#use-an-email-address-as-username) of their user. Check this option to disable. |
| Disable login with phone number | By default users can additionally [login with the phonenumber attribute](/guides/solution-scenarios/configurations#use-a-phone-number-as-username) of their user. Check this option to disable. |
@@ -264,11 +264,11 @@ If an account is locked, the administrator has to unlock it in the ZITADEL Manag
## Domain settings
### Add organization domain as suffix to loginnames
### Add Organization Domain as suffix to loginnames
If you enable this setting, all loginnames will be suffixed with the organization domain. If this setting is disabled, you have to ensure that usernames are unique over all organizations.
If you enable this setting, all loginnames will be suffixed with the Organization Domain. If this setting is disabled, you have to ensure that usernames are unique over all organizations.
### Validate Org domains
### Validate Organization Domains
If this is enabled all created domains on an organization must be verified per dns/acme challenge.
@@ -88,26 +88,26 @@ You can verify your own domain names (e.g., `acme.ch`) to simplify the user expe
Only one user with the username `john.doe` can exist within the organization `ACME`, regardless of which domain suffix they use to log in.
</Callout>
### Primary Domain
An organization can have multiple domain names, but only one is **Primary**. The primary domain determines:
### Organization Domain
An organization can have multiple domain names, but only one is configured as the **Organization Domain**. The Organization Domain determines:
* Which login name is displayed to the user in the UI.
* What information is asserted in `access_tokens` (specifically the `preferred_username` claim).
<Callout type="caution">
Setting a Primary Domain affects users.
Setting an Organization Domain affects users.
If a user `coyote` exists in the global organization with the login name `[email protected]`, and you subsequently verify `acme.ch` for a specific organization, the global user's login name will be replaced with `coyote@{randomvalue.tld}`. ZITADEL will notify users affected by this change.
</Callout>
## Domain Verification Guide
If the **validate org domains** setting in [Domain Settings](./default-settings#domain-settings) is set to `true`, you must prove ownership of your domain via DNS or HTTP challenge.
If the **validate Organization Domains** setting in [Domain Settings](./default-settings#domain-settings) is set to `true`, you must prove ownership of your domain via DNS or HTTP challenge.
<Callout type="info">
You can disable domain verification requirements in the [default settings](/guides/manage/console/default-settings#domain-settings) if you are running a self-hosted instance and do not require strict validation.
</Callout>
1. Navigate to your **Organization Settings**.
2. Select the menu entry **Verified domains**.
2. Select the menu entry **Organization Domains**.
3. Click on the domain name you wish to verify. A dialog will appear offering DNS or HTTP challenge methods.
<img
@@ -107,7 +107,7 @@ If you have different designs for your organizations (Private Labeling), you can
| **Enforce project's policy** | This forces the branding of the organization that *owns* the project throughout the entire login process. Useful if you want your users to always see *your* brand, even if they belong to a partner org. |
| **Allow login user policy** | The login starts with the project's branding. However, as soon as the user is identified (e.g., by entering their email), the branding switches to match the user's organization. |
In a B2B use case, you would typically use **Allow login user policy**. If you want to skip the detection step, you can preselect an organization using the [primary domain scope](/apis/openidoauth/scopes#reserved-scopes) (e.g., `urn:zitadel:iam:org:domain:primary:{domainname}`).
In a B2B use case, you would typically use **Allow login user policy**. If you want to skip the detection step, you can preselect an organization using the [Organization Domain scope](/apis/openidoauth/scopes#reserved-scopes) (e.g., `urn:zitadel:iam:org:domain:primary:{domainname}`).
### Role Settings
You can configure strict security checks regarding roles during authentication.
@@ -47,7 +47,7 @@ A user with an administrator role is not just an end-user of your application bu
### Uniqueness of Users
* **Scope:** Users exist strictly within **one** [Organization](./organizations-overview). It is currently not possible to move users between organizations.
* **Identifier:** User accounts are uniquely identified by their `id` or their `loginname` combined with the `organization domain` (e.g., `[email protected]`).
* **Identifier:** User accounts are uniquely identified by their `id` or their `loginname` combined with the `Organization Domain` (e.g., `[email protected]`).
* **Emails:** You can reuse the same email address for different user accounts across organizations.
### Structuring User Pools
@@ -41,10 +41,10 @@ In the advanced behavior you can choose if the loginname suffix (domain e.g. roa
If you like to trigger your settings for your applications you have different possibilities.
### 1. Primary Domain Scope
### 1. Organization Domain Scope
Send a [reserved scope](/apis/openidoauth/scopes) with your [authorization request](../../integrate/login/oidc/login-users) to trigger your organization.
The primary domain scope will restrict the login to your organization, so only users of your own organization will be able to log in.
The Organization Domain scope will restrict the login to your organization, so only users of your own organization will be able to log in.
You can use our [OpenID Authentication Request Playground](https://zitadel.com/playgrounds/oidc) to learn more about how to trigger an [organization's policies and branding](https://zitadel.com/playgrounds/oidc#organization-policies-and-branding).
@@ -39,7 +39,7 @@ To define the need of the **Portal Application**, some planning considerations a
### Login
You can decide whether an organization is preselected for the login or if the user is redirected to the default login screen. Using OpenID Connect, you can send the user to a specific organization by defining the organization in a [reserved scope](/apis/openidoauth/scopes#reserved-scopes) (primary domain).
You can decide whether an organization is preselected for the login or if the user is redirected to the default login screen. Using OpenID Connect, you can send the user to a specific organization by defining the organization in a [reserved scope](/apis/openidoauth/scopes#reserved-scopes) (Organization Domain).
Settings to the branding or the login options of the organization can be made from the organization section in [Console](/guides/manage/console/console-overview).
The behavior of the login branding can be set in your project detail page. You can choose the branding of the selected organization, the user's organization, or the project's organization.
@@ -21,7 +21,7 @@ Depending on your Software Development Life Cycle (SDLC) you can create multiple
### Organization Domain
Right after org creation you'll be greeted with the domain section of your organization.
ZITADEL automatically creates an organization domain of the form `[orgname].zitadel.cloud`, but you can create your own. Depending on the settings on the [Domain Policy](../../concepts/structure/policies) it has to be verified by saving a verification file on the specified location.
ZITADEL automatically creates an Organization Domain of the form `[orgname].zitadel.cloud`, but you can create your own. Depending on the settings on the [Domain Policy](../../concepts/structure/policies) it has to be verified by saving a verification file on the specified location.
We recommend that you create your domains early as they create a sense of confidence and trust for your application and changes later on might create additional migration effort.
You can read more about how ZITADEL handles usernames [here](../manage/console/organizations-overview#login-name-formats).
@@ -18,7 +18,7 @@ If a user of this organization wants to login, you don't want them to enter thei
3. Go to the "Login Behavior and Security" settings of the organization
4. Disable "Username Password Allowed" and enable "External IDP allowed" in the Advanced Section
Now your application can send either the organizations id (`urn:zitadel:iam:org:id:{id}`) or organizations primary domain (`urn:zitadel:iam:org:domain:primary:{domainname}`) scope on your authorization request to identify on which organization the users should be logged in.
Now your application can send either the organizations id (`urn:zitadel:iam:org:id:{id}`) or Organization Domain (`urn:zitadel:iam:org:domain:primary:{domainname}`) scope on your authorization request to identify on which organization the users should be logged in.
More about the [scopes](/apis/openidoauth/scopes#reserved-scopes)
@@ -44,7 +44,7 @@ This will have the following impacts:
- Trigger organization branding
- Only allow users from selected organization to login
To request the organization send either the the organization id (`urn:zitadel:iam:org:id:{id}`) or organization primary domain (`urn:zitadel:iam:org:domain:primary:{domainname}`) scope on your authentication request from your application.
To request the organization send either the the organization id (`urn:zitadel:iam:org:id:{id}`) or Organization Domain (`urn:zitadel:iam:org:domain:primary:{domainname}`) scope on your authentication request from your application.
More about the [scopes](/apis/openidoauth/scopes#reserved-scopes)
## Use email to login
@@ -88,7 +88,7 @@ Make sure to [Force MFA](/guides/manage/console/default-settings#multifactor-mfa
### Verify domains
Switch to the organization **Alpha** and navigate to the settings and "Verified domains".
Switch to the organization **Alpha** and navigate to the settings and "Organization 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.
@@ -53,7 +53,7 @@ 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 log in.
With the Organization Domain scope the organization will be restricted to the requested domain, this means only users of the requested organization will be able to log in.
The private labeling (branding) and the login policy of the requested organization will be set automatically.
<Callout>