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:

1. Log in to your IdP and gather the following information, which you will use to configure CockroachDB Cloud SSO:
   • Issuer URL
   • Client ID
   • Client secret
   • Callback URL
2. In a separate browser, log in to CockroachDB Cloud Console as a user with the Org Administrator role.
3. Go to Organization > Authentication.
4. Next to Authentication Methods, click Add.
5. Set Configuration to OIDC (OpenID Connect).
6. Set Provider Name to a display name for the connection.
7. Click Next.
8. The Provider Details page displays.
9. To edit the connection, click Edit.
10. Paste the values from your IdP for the Issuer URL, Client ID, Client Secret, and Callback URL.
11. Click Save.
12. The authentication method has been added but is disabled. To enable it, toggle Enable.
13. Click Test. If errors are shown, edit the configuration to fix the problems and try again.
14. Optionally, configure advanced settings for the new authentication method.

SAML

To configure a custom SAML authentication method:

1. Log in to your IdP and gather the following information, which you will use to configure CockroachDB Cloud SSO:
   • Sign-in URL
   • Signing certificate
2. In a separate browser, log in to CockroachDB Cloud Console as a user with the Org Administrator role.
3. Go to Organization > Authentication.
4. Next to Authentication Methods, click Add.
5. Set Configuration to SAML.
6. Set Provider Name to a display name for the connection.
7. Click Next.
8. The Provider Details page displays.
9. To edit the connection, click Edit.
10. Set Sign-in URL to the sign-in URL from your IdP.
11. Next to Signing Certificate, paste the entire certificate from your IdP, including the lines -begin certificate- and -end certificate.
12. Click Save.
13. Click Test. If errors are shown, edit the configuration to fix the problems and try again.
14. Optionally, configure advanced settings for the new authentication method.
15. Download metadata required by your IdP. Click Download. Open the file and make a note of the following values:
    • Entity ID: The entityID attribute of the <EntityDescriptor> tag.
    • Login URL: The location attribute of the <AssertionConsumerService> tag.
16. In the browser where you are logged in to your IdP, update the authentication configuration to use the Entity ID and Login URL from the metadata file.

17. Configure the SAML assertions that your IdP sends to CockroachDB Cloud.

    Your IdP must send an assertion with a name field and a second assertion with an email field, each mapped to the relevant fields in your IdP. To configure the SAML assertion, refer to the documentation for your IdP.

    In Okta, the SAML assertion does not include the email field by default, and it must be added. For detailed instructions, refer to How to Send Attributes via the SAML Assertion in the Okta documentation.

18. (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?