From 89eadb1e4534b355e7901787e9a61924849b8443 Mon Sep 17 00:00:00 2001 From: awxxxxxx Date: Thu, 11 Jun 2026 16:43:07 +0800 Subject: [PATCH 1/6] docs: add domain verification for org sso --- .../tidb-cloud-org-sso-authentication.md | 35 ++++++++++++++----- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/tidb-cloud/tidb-cloud-org-sso-authentication.md b/tidb-cloud/tidb-cloud-org-sso-authentication.md index dc25790b6d6e9..a77e2e2c086bf 100644 --- a/tidb-cloud/tidb-cloud-org-sso-authentication.md +++ b/tidb-cloud/tidb-cloud-org-sso-authentication.md @@ -60,7 +60,9 @@ Auto-provision is a feature that allows members to automatically join an organiz - When auto-provision is disabled for an authentication method, only users who have been invited by an `Organization Owner` or `Project Owner` can log in to your custom URL. - When auto-provision is enabled for an authentication method, any users using this authentication method can log in to your custom URL. After login, they are automatically assigned the default `Organization Viewer` role within the organization. -For security considerations, if you choose to enable auto-provision, it is recommended to limit the allowed email domains for authentication when you [configure the authentication method details](#step-2-configure-authentication-methods). +For OIDC and SAML authentication methods, you must configure allowed email domains when you [configure the authentication method details](#step-2-configure-authentication-methods). Before you can use a domain in the **Allowed Email Domains** field, add and verify it in the **Domains** area. + +For other authentication methods, if you choose to enable auto-provision, it is recommended to limit the allowed email domains for authentication. ### Notify your members about the Cloud Organization SSO migration plan @@ -116,6 +118,23 @@ After enabling Cloud Organization Cloud, you can configure username and password 4. Click **Save**. +### Add and verify domains for OIDC and SAML + +Before configuring OIDC or SAML, add and verify the email domains that your organization members use to sign in. Only domains with the **Verified** status can be used in **Allowed Email Domains** for OIDC and SAML. + +To add and verify a domain, take the following steps: + +1. On the **Organization Settings** page, click the **Authentication** tab. +2. In **Domains**, click **Add Domain**. +3. Enter the domain that you want to allow, for example, `example.com`, and then click **Add domain and next**. +4. In the verification dialog, copy the TXT record **Host** and **Value**. +5. In your DNS provider, add a TXT record using the copied **Host** and **Value**. +6. Wait for DNS propagation, return to TiDB Cloud, and then click **Verify**. + + DNS changes can take several minutes to take effect. If verification fails, wait a few minutes, and then try again. + +7. Confirm that the domain status becomes **Verified**. + ### Configure the OIDC authentication method If you have an identity provider that uses the OIDC identity protocol, you can enable the OIDC authentication method for TiDB Cloud login. @@ -141,15 +160,15 @@ In TiDB Cloud, the OIDC authentication method is disabled by default. After enab - [**Auto-provision Accounts**](#decide-whether-to-enable-auto-provision) - It is disabled by default. You can enable it according to your need. For security considerations, if you choose to enable auto-provision, it is recommended to limit the allowed email domains for authentication. + It is disabled by default. You can enable it according to your need. - **Allowed Email Domains** - After this field is configured, only the specified email domains of this authentication method can log in to TiDB Cloud using the custom URL. When filling in domain names, you need to exclude the `@` symbol and separate them with commas. For example, `company1.com,company2.com`. + This field is required for OIDC. Enter only domains that are already verified in the **Domains** area. Only users whose email domains match these domains can log in to TiDB Cloud using the custom URL. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. > **Note:** > - > If you have configured email domains, before saving the settings, make sure that you add the email domain that you currently use for login, to avoid that you are locked out by TiDB Cloud. + > Before saving the settings, make sure that you include the verified email domain that you currently use for login, to avoid being locked out by TiDB Cloud. 4. Click **Save**. @@ -185,15 +204,15 @@ In TiDB Cloud, the SAML authentication method is disabled by default. After enab - [**Auto-provision Accounts**](#decide-whether-to-enable-auto-provision) - It is disabled by default. You can enable it according to your need. For security considerations, if you choose to enable auto-provision, it is recommended to limit the allowed email domains for authentication. + It is disabled by default. You can enable it according to your need. - **Allowed Email Domains** - After this field is configured, only the specified email domains of this authentication method can log in to TiDB Cloud using the custom URL. When filling in domain names, you need to exclude the `@` symbol and separate them with commas. For example, `company1.com,company2.com`. + This field is required for SAML. Enter only domains that are already verified in the **Domains** area. Only users whose email domains match these domains can log in to TiDB Cloud using the custom URL. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. > **Note:** > - > If you have configured email domains, before saving the settings, make sure that you add the email domain that you currently use for login, to avoid that you are locked out by TiDB Cloud. + > Before saving the settings, make sure that you include the verified email domain that you currently use for login, to avoid being locked out by TiDB Cloud. - **SCIM Provisioning Accounts** @@ -248,4 +267,4 @@ In TiDB Cloud, the SAML authentication method is disabled by default. After enab 5. If you change the members of the pushed groups in your identity provider, these changes are dynamically synchronized to the corresponding groups in TiDB Cloud. - If new members are added to the groups in your identity provider, these members gain the roles of the corresponding groups. - - If some members are removed from the groups in your identity provider, these members are also removed from the corresponding groups in TiDB Cloud. \ No newline at end of file + - If some members are removed from the groups in your identity provider, these members are also removed from the corresponding groups in TiDB Cloud. From ceaaeb9de3ae83c1fa51433c72a617824c348369 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Thu, 11 Jun 2026 18:07:17 +0800 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> --- tidb-cloud/tidb-cloud-org-sso-authentication.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/tidb-cloud/tidb-cloud-org-sso-authentication.md b/tidb-cloud/tidb-cloud-org-sso-authentication.md index a77e2e2c086bf..7c80018caa732 100644 --- a/tidb-cloud/tidb-cloud-org-sso-authentication.md +++ b/tidb-cloud/tidb-cloud-org-sso-authentication.md @@ -160,15 +160,15 @@ In TiDB Cloud, the OIDC authentication method is disabled by default. After enab - [**Auto-provision Accounts**](#decide-whether-to-enable-auto-provision) - It is disabled by default. You can enable it according to your need. + It is disabled by default. You can enable it as needed. - **Allowed Email Domains** - This field is required for OIDC. Enter only domains that are already verified in the **Domains** area. Only users whose email domains match these domains can log in to TiDB Cloud using the custom URL. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. + This field is required for OIDC. Enter only domains that you have verified in the **Domains** area. Only users with these email domains can log in to TiDB Cloud using the custom URL. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. > **Note:** > - > Before saving the settings, make sure that you include the verified email domain that you currently use for login, to avoid being locked out by TiDB Cloud. + > Before saving the settings, make sure that you include the verified email domain that you currently use for login, to avoid being locked out of TiDB Cloud. 4. Click **Save**. @@ -204,15 +204,15 @@ In TiDB Cloud, the SAML authentication method is disabled by default. After enab - [**Auto-provision Accounts**](#decide-whether-to-enable-auto-provision) - It is disabled by default. You can enable it according to your need. + It is disabled by default. You can enable it as needed. - **Allowed Email Domains** - This field is required for SAML. Enter only domains that are already verified in the **Domains** area. Only users whose email domains match these domains can log in to TiDB Cloud using the custom URL. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. + This field is required for SAML. Enter only domains that you have verified in the **Domains** area. Only users with these email domains can log in to TiDB Cloud using the custom URL. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. > **Note:** > - > Before saving the settings, make sure that you include the verified email domain that you currently use for login, to avoid being locked out by TiDB Cloud. + > Before saving the settings, make sure that you include the verified email domain that you currently use for login, to avoid being locked out of TiDB Cloud. - **SCIM Provisioning Accounts** From 91bb9a4c116e4c0069e85c81008b0c7ce90db4cd Mon Sep 17 00:00:00 2001 From: awxxxxxx Date: Fri, 12 Jun 2026 13:21:07 +0800 Subject: [PATCH 3/6] docs: update org sso domain requirements --- tidb-cloud/tidb-cloud-org-sso-authentication.md | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/tidb-cloud/tidb-cloud-org-sso-authentication.md b/tidb-cloud/tidb-cloud-org-sso-authentication.md index 7c80018caa732..f026032dca797 100644 --- a/tidb-cloud/tidb-cloud-org-sso-authentication.md +++ b/tidb-cloud/tidb-cloud-org-sso-authentication.md @@ -60,7 +60,7 @@ Auto-provision is a feature that allows members to automatically join an organiz - When auto-provision is disabled for an authentication method, only users who have been invited by an `Organization Owner` or `Project Owner` can log in to your custom URL. - When auto-provision is enabled for an authentication method, any users using this authentication method can log in to your custom URL. After login, they are automatically assigned the default `Organization Viewer` role within the organization. -For OIDC and SAML authentication methods, you must configure allowed email domains when you [configure the authentication method details](#step-2-configure-authentication-methods). Before you can use a domain in the **Allowed Email Domains** field, add and verify it in the **Domains** area. +For OIDC and SAML authentication methods, if you enable **Auto-provision Accounts**, you must configure **Allowed Email Domains** when you [configure the authentication method details](#step-2-configure-authentication-methods). For SAML, this requirement also applies if you enable **SCIM Provisioning Accounts**. Before you can use a domain in **Allowed Email Domains**, add and verify it in the **Domains** area. For other authentication methods, if you choose to enable auto-provision, it is recommended to limit the allowed email domains for authentication. @@ -120,7 +120,9 @@ After enabling Cloud Organization Cloud, you can configure username and password ### Add and verify domains for OIDC and SAML -Before configuring OIDC or SAML, add and verify the email domains that your organization members use to sign in. Only domains with the **Verified** status can be used in **Allowed Email Domains** for OIDC and SAML. +If you want to enable **Auto-provision Accounts** for OIDC or SAML, or enable **SCIM Provisioning Accounts** for SAML, add and verify the email domains that your organization members use to sign in. In these cases, **Allowed Email Domains** is required, and only domains with the **Verified** status can be used. + +If auto-provision and SCIM provisioning are disabled, **Allowed Email Domains** is optional. If you enter any domains in this field, they must still be verified in the **Domains** area. To add and verify a domain, take the following steps: @@ -164,7 +166,9 @@ In TiDB Cloud, the OIDC authentication method is disabled by default. After enab - **Allowed Email Domains** - This field is required for OIDC. Enter only domains that you have verified in the **Domains** area. Only users with these email domains can log in to TiDB Cloud using the custom URL. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. + This field is required if you enable **Auto-provision Accounts** for OIDC. Enter only domains that you have verified in the **Domains** area. Only users with these email domains can log in to TiDB Cloud using the custom URL and be auto-provisioned into your organization. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. + + If **Auto-provision Accounts** is disabled, this field is optional. If you enter any domains, they must still be verified in the **Domains** area. > **Note:** > @@ -208,7 +212,9 @@ In TiDB Cloud, the SAML authentication method is disabled by default. After enab - **Allowed Email Domains** - This field is required for SAML. Enter only domains that you have verified in the **Domains** area. Only users with these email domains can log in to TiDB Cloud using the custom URL. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. + This field is required if you enable **Auto-provision Accounts** or **SCIM Provisioning Accounts** for SAML. Enter only domains that you have verified in the **Domains** area. Only users with these email domains can log in to TiDB Cloud using the custom URL and be provisioned into your organization. Exclude the `@` symbol and separate multiple domains with commas. For example, `company1.com,company2.com`. + + If both **Auto-provision Accounts** and **SCIM Provisioning Accounts** are disabled, this field is optional. If you enter any domains, they must still be verified in the **Domains** area. > **Note:** > @@ -218,6 +224,8 @@ In TiDB Cloud, the SAML authentication method is disabled by default. After enab It is disabled by default. You can enable it if you want to centralize and automate provisioning, deprovisioning, and identity management for TiDB Cloud organization users and groups from your identity provider. For detailed configuration steps, see [Configure SCIM provisioning](#configure-scim-provisioning). + Before enabling **SCIM Provisioning Accounts**, add and verify the domains that can be provisioned, and configure them in **Allowed Email Domains**. + 4. Click **Save**. #### Configure SCIM provisioning From 98f5cf7e1b83532c297f318cc17a091b773e4626 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 12 Jun 2026 15:06:26 +0800 Subject: [PATCH 4/6] Update references from Cloud Organization Cloud to SSO --- tidb-cloud/tidb-cloud-org-sso-authentication.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/tidb-cloud/tidb-cloud-org-sso-authentication.md b/tidb-cloud/tidb-cloud-org-sso-authentication.md index f026032dca797..8fa2371c0a938 100644 --- a/tidb-cloud/tidb-cloud-org-sso-authentication.md +++ b/tidb-cloud/tidb-cloud-org-sso-authentication.md @@ -98,7 +98,7 @@ Enabling an authentication method in TiDB Cloud allows members using that method ### Configure username and password, Google, GitHub, or Microsoft authentication methods -After enabling Cloud Organization Cloud, you can configure username and password, Google, GitHub, or Microsoft authentication methods as follows: +After enabling Cloud Organization SSO, you can configure username and password, Google, GitHub, or Microsoft authentication methods as follows: 1. On the **Organization Settings** page, enable or disable the Google, GitHub, or Microsoft authentication methods according to your need. 2. For an enabled authentication method, you can click to configure the method details. @@ -141,7 +141,7 @@ To add and verify a domain, take the following steps: If you have an identity provider that uses the OIDC identity protocol, you can enable the OIDC authentication method for TiDB Cloud login. -In TiDB Cloud, the OIDC authentication method is disabled by default. After enabling Cloud Organization Cloud, you can enable and configure the OIDC authentication method as follows: +In TiDB Cloud, the OIDC authentication method is disabled by default. After enabling Cloud Organization SSO, you can enable and configure the OIDC authentication method as follows: 1. Get the following information from your identity provider for TiDB Cloud Organization SSO: @@ -184,7 +184,7 @@ If you have an identity provider that uses the SAML identity protocol, you can e > > TiDB Cloud uses email addresses as unique identifiers for different users. Therefore, ensure that the `email` attribute for your organization members is configured in your identity provider. -In TiDB Cloud, the SAML authentication method is disabled by default. After enabling Cloud Organization Cloud, you can enable and configure the SAML authentication method as follows: +In TiDB Cloud, the SAML authentication method is disabled by default. After enabling Cloud Organization SSO, you can enable and configure the SAML authentication method as follows: 1. Get the following information from your identity provider for TiDB Cloud Organization SSO: From 34a1ecb5b436915f2ee6751ec5898add37bd87f1 Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 12 Jun 2026 16:46:59 +0800 Subject: [PATCH 5/6] update UI steps about accessing the Authentication page --- tidb-cloud/tidb-cloud-org-sso-authentication.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tidb-cloud/tidb-cloud-org-sso-authentication.md b/tidb-cloud/tidb-cloud-org-sso-authentication.md index 8fa2371c0a938..4087841059248 100644 --- a/tidb-cloud/tidb-cloud-org-sso-authentication.md +++ b/tidb-cloud/tidb-cloud-org-sso-authentication.md @@ -126,8 +126,8 @@ If auto-provision and SCIM provisioning are disabled, **Allowed Email Domains** To add and verify a domain, take the following steps: -1. On the **Organization Settings** page, click the **Authentication** tab. -2. In **Domains**, click **Add Domain**. +1. In the left navigation pane, click **Organization Settings** > **Authentication**. +2. On the **Authentication** page, click **Add Domain** in the **Domains** area. 3. Enter the domain that you want to allow, for example, `example.com`, and then click **Add domain and next**. 4. In the verification dialog, copy the TXT record **Host** and **Value**. 5. In your DNS provider, add a TXT record using the copied **Host** and **Value**. @@ -149,7 +149,7 @@ In TiDB Cloud, the OIDC authentication method is disabled by default. After enab - Client ID - Client secret -2. On the **Organization Settings** page, click the **Authentication** tab, locate the row of OIDC in the **Authentication Methods** area, and then click to show the OIDC method details. +2. On the **Authentication** page of your TiDB Cloud console, locate the row of OIDC in the **Authentication Methods** area, and then click to show the OIDC method details. 3. In the method details, you can configure the following: - **Name** @@ -191,7 +191,7 @@ In TiDB Cloud, the SAML authentication method is disabled by default. After enab - Sign on URL - Signing Certificate -2. On the **Organization Settings** page, click the **Authentication** tab in the left navigation pane, locate the row of SAML in the **Authentication Methods** area, and then click to show the SAML method details. +2. On the **Authentication** page of your TiDB Cloud console, locate the row of SAML in the **Authentication Methods** area, and then click to show the SAML method details. 3. In the method details, you can configure the following: - **Name** From dbe396e8d57caab524cc0cfb27423a7644cbce6f Mon Sep 17 00:00:00 2001 From: Grace Cai Date: Fri, 12 Jun 2026 16:56:38 +0800 Subject: [PATCH 6/6] revise descriptions --- tidb-cloud/tidb-cloud-org-sso-authentication.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tidb-cloud/tidb-cloud-org-sso-authentication.md b/tidb-cloud/tidb-cloud-org-sso-authentication.md index 4087841059248..c1d9a4ec05c6d 100644 --- a/tidb-cloud/tidb-cloud-org-sso-authentication.md +++ b/tidb-cloud/tidb-cloud-org-sso-authentication.md @@ -122,7 +122,7 @@ After enabling Cloud Organization SSO, you can configure username and password, If you want to enable **Auto-provision Accounts** for OIDC or SAML, or enable **SCIM Provisioning Accounts** for SAML, add and verify the email domains that your organization members use to sign in. In these cases, **Allowed Email Domains** is required, and only domains with the **Verified** status can be used. -If auto-provision and SCIM provisioning are disabled, **Allowed Email Domains** is optional. If you enter any domains in this field, they must still be verified in the **Domains** area. +If **Auto-provision Accounts** and **SCIM Provisioning Accounts** are disabled, **Allowed Email Domains** is optional. If you enter any domains in this field, they must still be verified in the **Domains** area. To add and verify a domain, take the following steps: @@ -224,7 +224,7 @@ In TiDB Cloud, the SAML authentication method is disabled by default. After enab It is disabled by default. You can enable it if you want to centralize and automate provisioning, deprovisioning, and identity management for TiDB Cloud organization users and groups from your identity provider. For detailed configuration steps, see [Configure SCIM provisioning](#configure-scim-provisioning). - Before enabling **SCIM Provisioning Accounts**, add and verify the domains that can be provisioned, and configure them in **Allowed Email Domains**. + Before enabling **SCIM Provisioning Accounts**, add and verify the email domains for users to be provisioned, and configure them in the **Allowed Email Domains** field. 4. Click **Save**.