Organization SSO Authentication

Single Sign-On (SSO) is an authentication scheme that enables members in your TiDB Cloud organization to log in to TiDB Cloud using identities from an identity provider (IdP) instead of email addresses and passwords.

TiDB Cloud supports the following two types of SSO authentication:

• Basic SSO: members can log in to the TiDB Cloud console using their GitHub, Google, or Microsoft authentication methods. The basic SSO is enabled by default for all organizations in TiDB Cloud.

• Cloud Organization SSO: members can log in to a custom login page of TiDB Cloud using the authentication methods specified by your organization. The Cloud Organization SSO is disabled by default.

Compared with basic SSO, Cloud Organization SSO provides more flexibility and customization so you can better meet your organization's security and compliance requirements. For example, you can specify which authentication methods are displayed on the login page, limit which email address domains are allowed for login, and let your members log in to TiDB Cloud with your identity provider (IdP) that uses the OpenID Connect (OIDC) or Security Assertion Markup Language (SAML) identity protocol.

In this document, you will learn how to migrate the authentication scheme of your organization from basic SSO to Cloud Organization SSO.

Before you begin

Before migrating to Cloud Organization SSO, check and confirm the items in this section for your organization.

Decide a custom URL for the TiDB Cloud login page of your organization

When Cloud Organization SSO is enabled, your members must use your custom URL instead of the public login URL (https://tidbcloud.com) to log in to TiDB Cloud.

The custom URL cannot be changed after the enablement, so you need to decide which URL to be used in advance.

The format of the custom URL is https://tidbcloud.com/enterprise/signin/your-company-name, in which you can customize your company name.

Decide authentication methods for your organization members

TiDB Cloud provides the following authentication methods for Organization SSO.

• Username and password
• Google
• GitHub
• Microsoft
• OIDC
• SAML

When you enable Cloud Organization SSO, the first four methods are enabled by default. If you want to enforce the use of SSO for your organization, you can disable the username and password authentication method.

All the enabled authentication methods will be displayed on your custom TiDB Cloud login page, so you need to decide which authentication methods to be enabled or disabled in advance.

Decide whether to enable auto-provision

Auto-provision is a feature that allows members to automatically join an organization without requiring an invitation from the Organization Owner or Project Owner. In TiDB Cloud, it is disabled by default for all the supported authentication methods.

• 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 Member 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.

Notify your members about the Cloud Organization SSO migration plan

Before enabling Cloud Organization SSO, make sure to inform your members about the following:

• The custom login URL of TiDB Cloud
• The time when to start using the custom login URL instead of https://tidbcloud.com for login
• The available authentication methods
• Whether members need invitations to log in to the custom URL

Step 1. Enable Cloud Organization SSO

To enable Cloud Organization SSO, take the following steps:

1. Log in to TiDB Cloud console as a user with the Organization Owner role.

2. In the lower-left corner of the TiDB Cloud console, click , and then click Organization Settings.

3. In the left navigation pane, click the Authentication tab, and then click Enable.

4. In the dialog, fill in the custom URL for your organization, which must be unique in TiDB Cloud.

   Note

   The URL cannot be changed once Cloud Organization SSO is enabled. Members in your organization will only be able to log in to TiDB Cloud using your custom URL. If you need to change the configured URL later, contact TiDB Cloud Support for assistance.

5. Click the I understand and confirm check box, and then click Enable.

   Note

   If the dialog includes a list of users to be re-invited and re-join for Cloud Organization SSO, TiDB Cloud will automatically send the invitation emails to those users after you enable Cloud Organization SSO. After receiving the invitation email, each user needs to click the link in the email to verify their identity, and the custom login page shows.

Step 2. Configure authentication methods

Enabling an authentication method in TiDB Cloud allows members using that method to log in to TiDB Cloud using your custom URL.

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:

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.

3. In the method details, you can configure the following:

   • Auto-provision Accounts

     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.

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

     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.

4. Click Save.

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:

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 to show the OIDC method details.

3. In the method details, you can configure the following:

   • Name

     Specify a name for the OIDC authentication method to be displayed on your custom login page.

   • Issuer URL, Client ID, and Client Secret

     Paste the corresponding values that you get from your IdP.

   • Auto-provision Accounts

     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.

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

     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.

4. Click Save.

Configure the SAML authentication method

If you have an identity provider that uses the SAML identity protocol, you can enable the SAML authentication method for TiDB Cloud login.

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:

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 to show the SAML method details.

3. In the method details, you can configure the following:

   • Name

     Specify a name for the SAML authentication method to be displayed on your custom login page.

   • Sign on URL

     Paste the URL that you get from your IdP.

   • Signing Certificate

     Paste the entire signing certificate from your IdP, including the starting line ---begin certificate--- and the end line ---end certificate---.

   • Auto-provision Accounts

     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.

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

     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.

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

4. Click Save.

Configure SCIM provisioning

System for Cross-domain Identity Management (SCIM) is an open standard that automates the exchange of user identity information between identity domains and IT systems. By configuring SCIM provisioning, user groups from your identity provider can be automatically synchronized to TiDB Cloud, and you can centrally manage roles for these groups in TiDB Cloud.

1. In TiDB Cloud, enable the SCIM Provisioning Accounts option of the SAML authentication method, and then record the following information for later use.

   • SCIM connector base URL
   • Unique identifier field for users
   • Authentication Mode

2. In your identity provider, configure SCIM provisioning for TiDB Cloud.

   1. In your identity provider, add SCIM provisioning for your TiDB Cloud organization to your SAML app integration.

      For example, if your identity provider is Okta, see Add SCIM provisioning to app integrations.

   2. Assign your SAML app integration to the desired groups in your identity provider so members in the groups can access and use the app integration.

      For example, if your identity provider is Okta, see Assign an app integration to a group.

   3. Push user groups from your identity provider to TiDB Cloud.

      For example, if your identity provider is Okta, see Manage group push.

3. In TiDB Cloud, view groups pushed from your identity provider.

   1. In the lower-left corner of the TiDB Cloud console, click , and then click Organization Settings.
   2. In the left navigation pane, click the Authentication tab.
   3. Click the Groups tab. The groups synchronized from your identity provider are displayed.
   4. To view users in a group, click View.

4. In TiDB Cloud, grant roles to the groups pushed from your identity provider.

   Note

   Granting a role to a group means all members in the group gain that role. If a group includes members already in your TiDB Cloud organization, these members also gain the new role of the group.

   1. To grant organization roles to the groups, click By organization, and then configure the roles in the Organization Role column. To learn about permissions of organization roles, see Organization roles.
   2. To grant project roles to the groups, click By project, and then configure the roles in the Project Role column. To learn about permissions of the project roles, see Project roles.

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.