📣
TiDB Cloud Premium is now in public preview. Unlimited growth, instant elasticity, advanced security for enterprise workloads. Try it out →
​
Sign InStart for Free
AI
Developer
Best Practices
API
​
Sign InStart for Free

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:

  • Standard SSO: members can log in to the TiDB Cloud console using their GitHub, Google, or Microsoft authentication methods. The standard 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 standard 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 standard 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 Organization Viewer role within the organization.

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

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 the TiDB Cloud console as a user with the Organization Owner role, and then switch to your target organization using the combo box in the upper-left corner.

  2. In the left navigation pane, click Organization Settings > Authentication.

  3. On the Authentication page, click Enable.

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

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

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

  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.

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

      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 as needed.

    • Allowed Email Domains

      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.

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

      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 as needed.

    • Allowed Email Domains

      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.

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

      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

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 TiDB Cloud console, switch to your target organization using the combo box in the upper-left corner.
    2. In the left navigation pane, click Organization Settings > Authentication.
    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.

    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.

Was this page helpful?