Configure Cloud Organization Single Sign-On (SSO)

On this page Carat arrow pointing down
Note:

This feature is in preview and is only available to enrolled organizations. To enroll your organization in the preview, contact your Cockroach Labs account team. This feature is subject to change.

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 provides additional customization and capabilities to help your organization meet its security and compliance requirements. For example, it 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.

Tip:

If you sign in using a URL other than https://cockroachlabs.cloud, Cloud Organization SSO is already enabled for your organization.

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.

Note:

After it is enabled, Cloud Organization SSO cannot be disabled. To configure Cloud Organization SSO to behave like Basic SSO, refer to Emulate Basic SSO.

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 IdP using the Security Access Markup Language (SAML) 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. If they previously had the console admin 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.

Enable Cloud Organization SSO

To enable Cloud Organization SSO:

  1. Log in to CockroachDB Cloud Console as a console admin.
  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 a console admin.
  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 console 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. 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

By default, autoprovisioning is disabled. In order to log in to CockroachDB Cloud using SSO without autoprovisioning:

  • A member's email address must exist in the SSO IdP.
  • A console admin must have already invited the member to the CockroachDB Cloud organization.

Autoprovisioning allows members to access your organization without an invitation. Members are assigned the Developer role by default. If you enable autoprovisioning, Cockroach Labs recommends that you also limit the allowed email domains for the authentication method.

To enable autoprovisioning for an SSO authentication method:

  1. Log in to CockroachDB Cloud Console as a console admin.
  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 Security Access Markup Language (SAML) or OpenID Connect (OIDC).

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 console admin.
  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 console admin.
  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. Refer to the documentation for your IdP.

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's next?


Yes No
On this page

Yes No