Skip to content

docs: add domain verification for org sso #23045

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
awxxxxxx wants to merge 6 commits into
base: release-8.5
Choose a base branch
from
+40 −13
Open

docs: add domain verification for org sso #23045

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
89eadb1
docs: add domain verification for org sso
awxxxxxx Jun 11, 2026
ceaaeb9
Apply suggestions from code review
qiancai Jun 11, 2026
91bb9a4
docs: update org sso domain requirements
awxxxxxx Jun 12, 2026
98f5cf7
Update references from Cloud Organization Cloud to SSO
qiancai Jun 12, 2026
34a1ecb
update UI steps about accessing the Authentication page
qiancai Jun 12, 2026
dbe396e
revise descriptions
qiancai Jun 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 40 additions & 13 deletions tidb-cloud/tidb-cloud-org-sso-authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, 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.

### Notify your members about the Cloud Organization SSO migration plan

Expand Down Expand Up @@ -96,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 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 20H21M3.00003 20H4.67457C5.16376 20 5.40835 20 5.63852 19.9447C5.84259 19.8957 6.03768 19.8149 6.21663 19.7053C6.41846 19.5816 6.59141 19.4086 6.93732 19.0627L19.5001 6.49998C20.3285 5.67156 20.3285 4.32841 19.5001 3.49998C18.6716 2.67156 17.3285 2.67156 16.5001 3.49998L3.93729 16.0627C3.59139 16.4086 3.41843 16.5816 3.29475 16.7834C3.18509 16.9624 3.10428 17.1574 3.05529 17.3615C3.00003 17.5917 3.00003 17.8363 3.00003 18.3255V20Z" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg> to configure the method details.
Expand All @@ -116,19 +118,38 @@ After enabling Cloud Organization Cloud, you can configure username and password

4. Click **Save**.

### Add and verify 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 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:

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**.
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.

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:

- Issuer URL
- 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 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 20H21M3.00003 20H4.67457C5.16376 20 5.40835 20 5.63852 19.9447C5.84259 19.8957 6.03768 19.8149 6.21663 19.7053C6.41846 19.5816 6.59141 19.4086 6.93732 19.0627L19.5001 6.49998C20.3285 5.67156 20.3285 4.32841 19.5001 3.49998C18.6716 2.67156 17.3285 2.67156 16.5001 3.49998L3.93729 16.0627C3.59139 16.4086 3.41843 16.5816 3.29475 16.7834C3.18509 16.9624 3.10428 17.1574 3.05529 17.3615C3.00003 17.5917 3.00003 17.8363 3.00003 18.3255V20Z" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg> 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 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 20H21M3.00003 20H4.67457C5.16376 20 5.40835 20 5.63852 19.9447C5.84259 19.8957 6.03768 19.8149 6.21663 19.7053C6.41846 19.5816 6.59141 19.4086 6.93732 19.0627L19.5001 6.49998C20.3285 5.67156 20.3285 4.32841 19.5001 3.49998C18.6716 2.67156 17.3285 2.67156 16.5001 3.49998L3.93729 16.0627C3.59139 16.4086 3.41843 16.5816 3.29475 16.7834C3.18509 16.9624 3.10428 17.1574 3.05529 17.3615C3.00003 17.5917 3.00003 17.8363 3.00003 18.3255V20Z" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg> to show the OIDC method details.
3. In the method details, you can configure the following:

- **Name**
Expand All @@ -141,15 +162,17 @@ 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 as needed.

- **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 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:**
>
> 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 of TiDB Cloud.

4. Click **Save**.

Expand All @@ -161,14 +184,14 @@ 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:

- 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 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 20H21M3.00003 20H4.67457C5.16376 20 5.40835 20 5.63852 19.9447C5.84259 19.8957 6.03768 19.8149 6.21663 19.7053C6.41846 19.5816 6.59141 19.4086 6.93732 19.0627L19.5001 6.49998C20.3285 5.67156 20.3285 4.32841 19.5001 3.49998C18.6716 2.67156 17.3285 2.67156 16.5001 3.49998L3.93729 16.0627C3.59139 16.4086 3.41843 16.5816 3.29475 16.7834C3.18509 16.9624 3.10428 17.1574 3.05529 17.3615C3.00003 17.5917 3.00003 17.8363 3.00003 18.3255V20Z" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg> 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 <svg width="16" height="16" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 20H21M3.00003 20H4.67457C5.16376 20 5.40835 20 5.63852 19.9447C5.84259 19.8957 6.03768 19.8149 6.21663 19.7053C6.41846 19.5816 6.59141 19.4086 6.93732 19.0627L19.5001 6.49998C20.3285 5.67156 20.3285 4.32841 19.5001 3.49998C18.6716 2.67156 17.3285 2.67156 16.5001 3.49998L3.93729 16.0627C3.59139 16.4086 3.41843 16.5816 3.29475 16.7834C3.18509 16.9624 3.10428 17.1574 3.05529 17.3615C3.00003 17.5917 3.00003 17.8363 3.00003 18.3255V20Z" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg> to show the SAML method details.
3. In the method details, you can configure the following:

- **Name**
Expand All @@ -185,20 +208,24 @@ 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 as needed.

- **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 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:**
>
> 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 of TiDB Cloud.

- **SCIM Provisioning Accounts**

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 email domains for users to be provisioned, and configure them in the **Allowed Email Domains** field.

4. Click **Save**.

#### Configure SCIM provisioning
Expand Down Expand Up @@ -248,4 +275,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.
- If some members are removed from the groups in your identity provider, these members are also removed from the corresponding groups in TiDB Cloud.
Loading