Configure Cloud Organization SSO

On this page

Single Sign-On (SSO) allows members of your CockroachDB Cloud organization to authenticate using an identity from an identity provider (IdP) instead of using an email address and password.

Basic SSO is enabled by default for each CockroachDB Cloud organization. members can authenticate to CockroachDB Cloud Console with any GitHub, Google, or Microsoft identity or with a password.

Cloud Organization SSO lets users sign in at a custom login page unique to your organization, and provides additional customization and capabilities to help your organization meet its security and compliance requirements.

Cloud Organization SSO supports autoprovisioning, allows you to restrict the email addresses that can log in using a given method, and allows you to connect to your identity provider (IdP) using the Security Access Markup Language (SAML) and OpenID Connect (OIDC) identity protocols.

This page describes how to enable Cloud Organization SSO and manage your SSO configuration.

Plan to enable Cloud Organization SSO

To ensure a smooth migration to Cloud Organization SSO, review the following information before you enable the feature.

Decide your custom URL

When you enable Cloud Organization SSO, you will configure a custom URL through which your members can access CockroachDB Cloud. After the feature is enabled, your members must use that page to sign in. Your custom URL must be unique within CockroachDB Cloud. Communicate this custom URL to your members ahead of time.

To change your custom URL after enabling Cloud Organization SSO, contact your account team.

Decide which authentication methods to enable

All enabled authentication methods appear on your custom URL and are available to your members. By default, when you enable Cloud Organization SSO, the following authentication methods are enabled by default:

• Password
• GitHub
• Google
• Microsoft

In addition, you can create authentication methods that connect to your identity provider (IdP) using the Security Access Markup Language (SAML), System for Cross-Domain Identity Management SCIM, and OpenID Connect (OIDC) identity protocols.

Members are identified by their email address. To allow members to migrate from password authentication to SSO, ensure that their email addresses in your CockroachDB Cloud organization match those in your IdPs. To allow your members to select from multiple SSO authentication methods, ensure that the email addresses match across all of them.

Communicate to your members

Before you enable Cloud Organization SSO, notify your members about what to expect, such as:

• The custom login URL and when they should begin using it.
• Which authentication methods they can use and whether they have autoprovisioning enabled.
• Some members may need to be re-added to your organization:
  • All members of your CockroachDB Cloud organization who were using Basic SSO rather than an email and password must sign in again to regain access to your organization. After signing in, members retain the same access they had before the migration.
  • Members who are also members of other organizations must be re-added to your organization. If they sign in using an authentication method with autoprovisioning enabled, they are automatically added upon successful sign-in. Otherwise, they must be re-invited or provisioned using SCIM. If a re-invited member previously had the Org Administrator role, it must be granted to them again.

During enablement of the feature, a list of affected members is shown, and those members are also notified individually.

Ensure that at least one organization admin belongs to no other CockroachDB Cloud organization

For your migration to succeed, you must ensure that at least one admin belongs to no other CockroachDB Cloud organization than the one to be migrated. If all admins belong to multiple organizations, the migration will fail with the generic error Cloud Organization SSO cannot be enabled.

If all of your administrators belong to multiple organizations, you can create a temporary user in your SSO provider or directly in CockroachDB Cloud. Grant the Org Administrator role to the temporary user, and use this temporary admin to enable Cloud Organization SSO. After migration, you should delete this temporary user or revoke the Org Administrator role.

Enable Cloud Organization SSO

To enable Cloud Organization SSO:

1. Log in to CockroachDB Cloud Console as an user with the Org Administrator role.
2. Go to Organization > Authentication.
3. Next to Enable Authentication, click Enable.

4. In the dialog, configure the custom URL your members will use to sign in. This value must be unique across CockroachDB Cloud. For more details, refer to Update the custom URL.

   Note:

   If you previously updated the custom URL from Organization > Authentication but did not enable Cloud Organization SSO, you are not prompted to configure it again. The value you have already configured is automatically used during enablement. To edit the custom URL again, click Back in the dialog.

   Click Next

5. The list of default authentication methods displays. By default, Password, GitHub, Google, and Microsoft are enabled.

   To configure an authentication method, click its name and fill in the details. You can also do this later. Refer to Configure advanced settings. To disable an authentication method, click Disable. You can also do this later.

   Warning:

   If you disable password authentication, members can no longer authenticate to CockroachDB Cloud Console using the passwords that were previously stored for them, and those passwords are not retained. Cockroach Labs recommends that you thoroughly test each SSO authentication method that you enable before disabling password authentication.

   Click Next.

6. Select Confirm, then click Enable.

Cloud Organization SSO is enabled, and members can sign in by using the custom URL and selecting any enabled authentication method.

Update the custom URL

After you enable Cloud Organization SSO, your members sign in at a custom URL that exposes only the authentication methods that you enable, rather than the public sign-in URL at https://cockroachlabs.cloud.

To update the custom URL after Cloud Organization SSO is enabled, contact your account team.

Enable or disable an authentication method

When you enable an authentication method, members can begin authenticating to CockroachDB Cloud using that authentication method. A member can log in using any enabled authentication method, as long as the email address for the member is the same across all enabled methods. When they successfully sign in with a new authentication method for the first time, they have the option to update their default authentication method. You can optionally configure advanced settings for each enabled authentication method.

When you disable an authentication method, members who are no longer associated with the other enabled authentication method(s) can no longer sign in and must be provisioned in an IdP that is associated with one of those other enabled methods.

When you enable or disable an authentication method, a notification is displayed with a list of members who must sign in with a different authentication method to regain access. Each affected member also receives an email notification prompting them to sign in again.

To enable or disable an authentication method:

1. Log in to CockroachDB Cloud Console as user with the Org Administrator role.
2. Go to Organization > Authentication.
3. To configure an authentication method, click its name.
4. To enable or disable the authentication method, toggle Enable.
5. If desired, configure advanced settings for the authentication method.
6. Click Save.

Configure advanced settings

The following sections describe the advanced settings you can configure for an SSO authentication method. To configure an authentication method:

1. Log in to CockroachDB Cloud Console as an organizational admin.
2. Go to Organization > Authentication.
3. To configure an authentication method, click its name.
4. At the top of the page, click Edit.
5. Click Advanced Settings.
6. Configure the advanced settings as desired.
7. Click Save.

Allowed email domains

By default, members can access your CockroachDB Cloud organization from any email domain. To restrict access to a specific list of email domains:

1. Log in to CockroachDB Cloud Console as a user with the Org Administrator role.
2. Go to Organization > Authentication.
3. To configure an authentication method, click its name.
4. At the top of the page, click Edit.
5. Set Allowed Email Domains to a comma-separated list of email domains. Each domain should begin with a @. To ensure that you are not locked out of CockroachDB Cloud while you are configuring Cloud Organization SSO, be sure to allow access to the email domain that you use to sign in.
6. Click Save.

Autoprovisioning

Autoprovisioning allows members to sign up for an account without waiting for an invitation. By default, autoprovisioning is disabled, and a member must exist in the SSO provider and must be invited by a user with the Org Administrator role before they can create an account. When autoprovisioning is enabled, no invitation is required.

Autoprovisioned accounts are initially assigned the Organization Member role, which grants no permissions to perform cluster or org actions. Additional roles can be granted by a user with the Org Administrator role.

If a member's identity is removed from the SSO provider, they can no longer log in to CockroachDB Cloud, but their account is not automatically deprovisioned. If you require automatic deprovisioning or other centralized account automation features, refer to SCIM Provisioning.

Cockroach Labs does not recommend enabling both autoprovisioning and SCIM provisioning for the same authentication method.

To enable autoprovisioning for an SSO authentication method:

1. Log in to CockroachDB Cloud Console as a user with the Org Administrator role.
2. Go to Organization > Authentication.
3. Click the name of an authentication method.
4. Click Advanced Settings.
5. Next to Autoprovisioning, click Enable.

Add a custom authentication method

You can add a custom authentication method to connect to any IdP that supports OpenID Connect (OIDC) or Security Access Markup Language (SAML).

OIDC

To configure a custom OIDC authentication method, you need the following information from your IdP:

• Issuer URL
• Client ID
• Client secret

These instructions work for Okta. If you use a different IdP, refer to its documentation for configuring OIDC.

1. Log in to Okta as a user with the Admin role.
2. In the Admin Console, click Applications, then click Browse Catalog.
3. Search for "Cockroach Labs", then click Add integration.
4. Set Application label to a name for the integration. Set Entity ID and ACS URL to none. These fields are ignored.
5. Click Next.
6. In Sign-On Options, select OpenID Connect. SAML is selected by default.
7. Set Application username format to Email.
8. Click Done. The app integration's details appear.
9. Assign at least one Okta identity to the application, such as the identity you already use to sign in to CockroachDB Cloud. Click Assignments, then click Assign to People. Find the identity, click Assign, then click Save and go back. Click Done to close the assignment dialog.
10. Click the Sign-On tab. Find the link for OpenID Provider Metadata. Right-click and copy the URL. This is your issuer URL, which you will provide to CockroachDB Cloud.
11. Keep this tab open so that you can copy the Client ID and Client Secret to CockroachDB Cloud.
12. In a separate browser, log in to CockroachDB Cloud Console as a user with the Org Administrator role.
13. Go to Organization > Authentication.
14. Next to Authentication Methods, click Add.
15. Set Configuration to OIDC (OpenID Connect) and provide a name for the connection. This name will appear on your custom sign-in page.
16. Click Submit. The authentication method's details are displayed. Click Edit.
17. Set Issuer URL to the issuer URL you copied from Okta, beginning with https:// and ending with /openid-configuration.
18. Copy the Client ID and Client Secret from the Okta browser tab.
19. Test the connection. This is recommended before enabling the method. Click Test, then follow the prompts. If you get an error, review your configuration details, then try again. When the test is successful, the test status changes to Verified.
20. Click Save.
21. The authentication method has been added but is disabled. To enable it, toggle Enable.
22. Optionally, configure advanced settings for the new authentication method.

SAML

To configure a custom SAML authentication method, you need the following information from your IdP:

• Sign On URL
• Signing certificate

These instructions work for Okta. If you use a different IdP, refer to its documentation for configuring SAML.

1. Log in to CockroachDB Cloud Console as a user with the Org Administrator role.
2. Go to Organization > Authentication.
3. Next to Authentication Methods, click Add.
4. Set Configuration to SAML.
5. Set Provider Name to a display name for the connection.
6. Click Next. The Provider Details page opens.
7. To edit the connection, click Edit. Keep this browser tab open.
8. In a separate browser tab, log in to Okta as a user with the Admin role.
9. In the Admin Console, click Applications, then click Browse Catalog.
10. Search for "Cockroach Labs", Click Add integration.
11. SAML is selected by default. Provide a name for the connection. This name will appear on your custom sign-in page.
12. Click Submit. The authentication method's details are displayed.
13. To download the metadata you will need to provide to Okta, click Download. The metadata is downloaded in XML format.

14. Open the metadata file. Make a note of the following:

    • Entity ID: The entityID attribute of the <EntityDescriptor> tag.
    • ACS URL: The location attribute of the <AssertionConsumerService> tag.

    Close the metadata file. Keep the browser tab open.

15. Next to Sign On Certificate, click Download. Do not click Copy. Open the downloaded file in a text editor.

16. In the browser tab for CockroachDB Cloud, click Edit.

17. Set Sign-in URL to the Sign on URL from Okta.

18. Copy the entire contents of the certificate from your text editor into Signing Certificate, including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines, and paste it into the Signing Certificate field.

19. Test the connection. This is recommended before enabling the method. Click Test, then follow the prompts. If you get an error, review your configuration details, then try again. When the test is successful, the test status changes to Verified.

20. Click Save.

21. The authentication method has been added but is disabled. To enable it, toggle Enable.

22. (Optional) Configure SCIM autoprovisioning.

After SAML is configured, your users can sign in to the CockroachDB Cloud Console in two different ways:

• Service provider-initiated flow: Users sign in to the CockroachDB Cloud Console directly, using your custom sign-in URL.
• Identity provider-initiated flow: Users sign in to the CockroachDB Cloud Console from within your IdP (for example, by accessing its tile in Okta).

Require SSO

To begin enforcing a requirement to sign in using SSO:

1. Enable Cloud Organization SSO.
2. Disable SSO authentication methods that you don't need and optionally configure advanced settings for those that are enabled.
3. After thorough testing, disable email authentication.

Emulate Basic SSO

After Cloud Organization SSO is enabled, it cannot be disabled. To emulate the behavior of Basic SSO:

1. Enable the following authentication methods:
   • Password
   • GitHub
   • Google
   • Microsoft
2. For GitHub, Google, and Microsoft authentication methods, allow all email domains and disable autoprovisioning.

Members must still sign in using your organization's custom URL.

What next?

• Cloud Organization SSO Frequently Asked Questions.
• Configure SCIM Provisioning
• Learn more about authenticating to CockroachDB Cloud.

Was this helpful?