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. 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.
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 Configure Cloud Organization 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 enable multiple authentication methods 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.
- 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.
- Autoprovisioning optionally removes the need to invite members to your organization. Autoprovisioning is disabled by default for each SSO authentication method.
- You can restrict the email domains that are allowed to sign in using an SSO authentication method. By default, any email domain is allowed.
To enable and configure Cloud Organization SSO, refer to Configure Cloud Organization SSO. The following sections provide more details about the features of Cloud Organization SSO.
Autoprovisioning allows you to centralize management of your users in an IdP and removes the need to invite users to your organization. When autoprovisioning is enabled, the first time a new user successfully signs in using the custom sign-in page, a CockroachDB Cloud account is automatically created for them and the user is assigned the Developer role by default.
Together with Allowed Email Domains, autoprovisioning allows new users to get started as soon as they are provisioned in your IdP, without waiting for an invitation.
Autoprovisioning is optional, and can be configured separately for each enabled SSO authentication method.
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 Manage Team Members.
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 Cloud organization.
If you require SSO authentication, then when you deprovision a member from your IdP, they can no longer access your CockroachDB Cloud organization and there is no need to manually remove them from your CockroachDB Cloud organization.
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.
Migration of individual members to SSO
After you enable Cloud Organization SSO and enable an authentication method 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.
Frequently Asked Questions (FAQ)
If a user already has an email address associated with an SSO provider such as Gmail, can they sign in with Basic SSO?
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.
With Basic SSO, once a user changes their active login method to a new SSO provider, can they still sign in using an email/password combination or GitHub identity?
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 .
Does this change how console admins invite users?
The workflow for inviting team members 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 an account is created automatically upon successfully authentication.
As a console admin, how do I deprovision a user's access to CockroachDB Cloud Console if they leave the relevant project?
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.
To remove a user's access to CockroachDB Cloud without deprovisioning the user from the IdP (such as when a user changes teams but does not leave the organization entirely), you can remove their CockroachDB Cloud user identity from your CockroachDB Cloud organization.
Can console admins require a particular authentication method for their CockroachDB Cloud organization?
Yes. When Cloud Organization SSO is enabled for your CockroachDB Cloud organization, only the authentication methods you have enabled are displayed to your users.
Which SAML-based authentication flows are supported with Cloud Organization SSO?
The primary flow is the service provider-initiated flow, where you initiate configuration of Cloud Organization SSO through the CockroachDB Cloud Console.
If you require an identity provider-initiated flow, contact your account team for assistance.
defaultrole is assigned to users when auto-provisioning is enabled in a CockroachDB Cloud organization?
Developer role is assigned by default to auto-provisioned users.
- Configure Cloud Organization SSO
- Learn more about authenticating to CockroachDB Cloud.