Single Sign-On (SSO) for CockroachDB Cloud organizations

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.

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.

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.

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

This page describes Basic SSO and Cloud Organization SSO. To enable Cloud Organization SSO, refer to .

Basic SSO

Basic SSO provides flexibility and convenience for your users, and is enabled by default for each CockroachDB Cloud organization. With no configuration required, members can sign in using an identity from GitHub, Google, or Microsoft instead of using a password.

Basic SSO has the following differences from Cloud Organization SSO:

• Configuration is not possible.
• New authentication methods cannot be added, and existing authentication methods cannot be modified, limited, or disabled.
• It is not possible to enforce a requirement to use SSO rather than password authentication.
• It is not possible to limit the email domains allowed to sign in using a given authentication method.
• Autoprovisioning is not supported, and members must be invited before they can sign in.
• A member may have only one active authentication method in an organization, but may change it at any time by logging in using a different method. However, for a member to switch back to using a password, they must be removed and re-invited to your CockroachDB Cloud organization.

If your organization needs more flexibility and customization to meet your security and compliance requirements, you can enable and configure Cloud Organization SSO.

Cloud Organization SSO

Cloud Organization SSO allows you to customize your SSO configuration to meet your organization’s security and business requirements:

• Members sign in using a custom URL that allows only the authentication methods that you have configured.
• Members can sign in using any enabled authentication method, to help reduce the impact of an IdP outage. If a member signs in using a new method for the first time, they are prompted to optionally update their default method. This is possible only as long as the members are using the same email address to sign in through each method.
• You can simultaneously. You can even add custom authentication methods that connect to IdPs such as Okta or ActiveDirectory through the Security Access Markup Language (SAML) and OpenID Connect (OIDC) identity protocols. If you use Okta, you can use the official to ease setup of custom SAML or OIDC authentication methods.
• You can disable any authentication method. To enforce a requirement to use SSO, you can enable only SSO authentication methods and disable password authentication. If you disable password authentication, passwords are not retained.
• You can that are allowed to sign in using an SSO authentication method. By default, any email domain is allowed.
• Autoprovisioning can be enabled for SSO authentication methods, and automatically creates a CockroachDB Cloud organization account when a member successfully authenticates using an SSO authentication method for the first time, with no invitation required.
• automatically creates a CockroachDB Cloud organization account when a user is assigned to the SCIM application in your IdP that is connected to your CockroachDB Cloud organization.

To enable and configure Cloud Organization SSO, refer to . The following sections provide more details about the features of Cloud Organization SSO.

If your organization includes members whose identity you don’t manage, such as partners or consultants, you can leave password authentication enabled for those members, while instructing your internal users to sign in using SSO. Members who sign in using a password must be removed from your CockroachDB Cloud organization manually.

Autoprovisioning

Autoprovisioning is a self-service mechanism that removes the need for a new user to be . When it is enabled, the first time a user successfully authentications using that method, CockroachDB Cloud organization account is automatically created for them. Autoprovisioned accounts are initially assigned the , which adds no permissions to perform cluster or organization actions. Additional roles can be assigned by a user with the .

Autoprovisioning is disabled by default, but can be enabled per SSO authentication method.

If you enable autoprovisioning, Cockroach Labs recommends that you also limit the for the SSO authentication method. This ensures that only your organization’s members can access your CockroachDB Cloud organization, and that only new accounts for the specified domains can be autoprovisioned.

CockroachDB Cloud users are identified by their email address. To reduce the risk of duplicated users, ensure that users have unique email addresses before you enable autoprovisioning for an authentication method. If duplicate users result from enabling autoprovisioning, you must delete them manually. Refer to .

Cockroach Labs recommends that you enable autoprovisioning on only a single SSO method at a time, and that you migrate your users gradually. Most organizations aim to manage users in a single centralized IdP. It may be necessary to temporarily enable autoprovisioning to migrate a group of users from your centralized IdP who have yet not been onboarded to your CockroachDB Cloud organization.

If you , then when you deprovision a member from your IdP, they can no longer access your CockroachDB Cloud UI and there is no need to manually remove them from your CockroachDB Cloud organization, but some organizations choose to do so.

If you require automated user management features, you can configure SCIM provisioning instead of autoprovisioning.

Migration of individual members to SSO

After you and for your organization, it will appear on your organization’s custom URL. Your existing users can then sign in using that method, rather than the method they were using previously. When an existing member signs in using an SSO authentication method for the first time, they can optionally designate that authentication method as their new default.

After you enable Cloud Organization SSO, all members of your organization must sign in again, even if they were previously signed in using Basic SSO. After signing in, they retain the same organizational roles they had previously.

However, members of your organization who also belong to other CockroachDB Cloud 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, you must re-invite them to your organization.

When you enable Cloud Organization SSO or when you enable or disable an authentication method, you are shown a list of the members who will be impacted and the action that must be taken for them to regain access. Those members are also notified about the change via email.

After all users have been migrated and signing in using SSO, you can .

SCIM provisioning

System for Cross-Domain Identity Management SCIM centralizes and automates provisioning and deprovisioning of CockroachDB Cloud organization users from your IdP.

Rather than using or self-service autoprovisioning, SCIM provisioning tasks are performed centrally by a team of IAM admins, who manage the assignment of your organization’s users to your organization’s applications. To learn more or configure SCIM provisioning, refer to .

Frequently Asked Questions (FAQ)

Yes, as long as the email address associated with the user’s SSO provider is exactly the same as the one associated with the user’s existing CockroachDB Cloud account. After successfully signing in, the user will be prompted to approve the updated authentication method for their account.

A user can view their current authentication method by clicking My Account in the CockroachDB Cloud Console.

No. With Basic SSO, only one authentication method can be active for each CockroachDB Cloud Console user. To view or update their active authentication method, a user can click My Account in the CockroachDB Cloud Console.

The to your CockroachDB Cloud organization remains the same.

However, if Cloud Organization SSO is enabled for your CockroachDB Cloud organization and autoprovisioning is enabled for the authentication method a member uses to sign in, then they can create an account and sign in without waiting for an invitation.

If SCIM provisioning is enabled, the user’s account is provisioned when an IdP admin assigns them to the SCIM application.

If Cloud Organization SSO is enabled, then deprovisioning a user at the level of the IdP also removes their access to the CockroachDB Cloud organization. However, their account is only automatically removed if you use SCIM provisioning.

To remove a user’s access to CockroachDB Cloud manually (such as when a user changes teams but does not leave the organization entirely), you can .

Yes. When Cloud Organization SSO is enabled for your CockroachDB Cloud organization, only the are displayed to your users.

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

Autoprovisioned accounts are initially assigned the , which adds no permissions to perform cluster or organization actions. Additional roles can be assigned by a user with the .

What’s next?

• Learn more about .