Configure SCIM provisioning

On this page

System for Cross-Domain Identity Management SCIM autoprovisioning centralizes and automates provisioning and deprovisioning of CockroachDB Cloud organization users and groups from your identity provider (IdP).

Rather than using invitations or self-service autoprovisioning, SCIM autoprovisioning tasks are performed centrally by a team of IAM admins in your IdP, who manage the assignment of your organization's users to your organization's app integrations. This page describes SCIM provisioning and shows how to configure and use it to provision CockroachDB Cloud users.

Overview of SCIM provisioning

This section describes how SCIM provisioning works if you use Okta. Depending on how your IdP has implemented SCIM, some details may differ.

1. In your IdP, an IAM admin creates a SCIM app integration and configures it to authenticate to CockroachDB Cloud using a CockroachDB Cloud service account with the Org Administrator (legacy) role.
2. In your IdP, an IAM admin assigns users and groups to the app integration.
3. The app integration provisions or deactivates users in CockroachDB Cloud based on the app integration's assignments.

Depending on your IdP's configuration, provisioned users can access your CockroachDB Cloud organization using either your IdP's interface or your CockroachDB Cloud organization's custom sign-in URL. The first time a user successfully authenticates to your CockroachDB Cloud organization, the identity for the provisioned user is created.

SCIM operations on a group are applied to each member of the group individually. For example, assigning a group to an app integration provisions accounts for each of its members, and they can access CockroachDB Cloud. However, CockroachDB Cloud has no awareness of the IAM group itself unless an IAM admin uses the app integration to push the group to CockroachDB Cloud. If a group is pushed but not assigned to the app integration, new users are not provisioned in the app integration, but memberships of users that have already been assigned to the app integration are automatically affected. Refer to Automate Group Management.

When a user is directly or indirectly unassigned, their CockroachDB Cloud account is disabled or removed, depending on the capabilities of your IdP. To remove a disabled user from CockroachDB Cloud, refer to Manage an Organization's Members.

To learn more about user and group assignments and group push on Okta, refer to the following topics in the Okta documentation:

• Manage Users
• Manage Groups
• Manage Group Push

Before following these instructions, if your IdP is Okta, then it may be helpful to read Okta's article about SCIM, as well as Configure provisioning for an app integration in the Okta documentation. Otherwise, refer to your IdP's documentation about configuring SCIM.

Requirements

1. As a user with the Org Administrator (legacy) role:

   1. Enable Cloud Organization SSO.
   2. Create a service account with the Org Administrator (legacy) role and make a note of its API token. This is the bearer token the IdP will use to authenticate to the CockroachDB Cloud API.
   3. Contact your account team to enable your CockroachDB Cloud organization in SCIM limited access.

2. If your IdP is Okta, SCIM provisioning can be enabled only on a custom SAML authentication method. This requirement is imposed by Okta, and is not part of the SCIM or SAML protocols.

Individual IdPs may impose different requirements, and the exact steps and requirements for enabling SCIM autoprovisioning depend upon your IdP. Refer to your IdP's documentation about configuring SCIM provisioning.

Configure SCIM provisioning on Okta

The exact steps and requirements for enabling SCIM provisioning depend upon your IdP. At a minimum, you must provide your IdP two pieces of information:

• The endpoint to the CockroachDB Cloud SCIM API, https://cockroachlabs.cloud/api/scim/v2.
• The API token of a CockroachDB Cloud service account with the Org Administrator (legacy) role.

To add SCIM provisioning to a SAML app integration in Okta:

1. Log in to Okta Admin Dashboard as an admin user.
2. Click Applications and edit the SAML app integration for your CockroachDB Cloud organization.
3. Click Edit.
4. Click Provisioning.
5. Select SCIM and click Save.
6. In the integration's settings page, click Provisioning again, then click Edit.

7. Click Integrations. This tab controls the app integration's authentication to the CockroachDB Cloud API. Set:

   • SCIM connector base URL: https://cockroachlabs.cloud/api/scim/v2
   • API authentication token: the API token for a CockroachDB Cloud service account with the Org Administrator (legacy) role
   • Unique identifier field for users: userName
   • Authentication Mode: HTTP Header

8. Click Test Connector Configuration.

9. Click Save.

10. Click To App. This tab controls assignment of Okta identities to CockroachDB Cloud. To allow provisioning and deprovisioning of users, ensure that Create Users and Deactivate Users are selected, and make any other desired changes.

11. Optionally, click To Okta. This tab allows you to perform a one-time import of a CockroachDB Cloud organization's existing users into Okta. Refer to Okta's documentation about mapping individual fields. Make any desired changes.

To learn more, refer to Add SCIM Provisioning to App Integrations in the Okta documentation

Manage users and groups on Okta

The following sections show how to manage the access of Okta users to your CockroachDB Cloud organization.

Assign a user or group

To provision a user or group to CockroachDB Cloud, you assign the user or group to the app integration.

1. Log in to Okta Admin Dashboard as an IAM admin.
2. Click Applications and click the SAML application for your CockroachDB Cloud organization.
3. Click Assignments. When a user or group is assigned to an application, Okta allows them to sign in to the application.

4. Click Assign, then select Assign to People or Assign to Groups.

   Operations on a group are applied to each member of the group individually by the CockroachDB Cloud API. For example, assigning a group to the app integration provisions an account for each of the group's members at the time of assignment. Changes to a group's membership in Okta are not automatically reflected in CockroachDB Cloud unless the group is linked in the app integration. Refer to Automate Group Management.

   Filter or search for a user or group. Next to them, click Assign, then Save and go back.

   CockroachDB Cloud accounts are provisioned when a user or group is assigned to the app integration.

5. Instruct the user how to access your CockroachDB Cloud organization. CockroachDB Cloud does not notify a user when an account is provisioned for them using SCIM. Users may use your IdP's web interface or a browser plugin, or they may access your CockroachDB Cloud organization's custom login URL directly and select an SSO login method.

To learn more, refer to Assign An App Integration to a User in the Okta documentation.

If you assign a group to the app integration, its members are provisioned and appear in CockroachDB Cloud, but members who are subsequently added to the group in Okta are not automatically provisioned to CockroachDB Cloud unless you push the groups to CockroachDB Cloud in the app integration. Refer to Automate Group Management.

Unassign a user or group

To remove a user's access to CockroachDB Cloud, unassign the user from the app integration.

1. Log in to Okta Admin Dashboard as an admin user.
2. Click Applications and click the SAML application for your CockroachDB Cloud organization.
3. Click Assignments.

4. Next to a user or group, click More Actions > Deactivate.

   Note:

   Unassigning an IdP group from the app integration disables each group member's CockroachDB Cloud organization account. Changes to a group's membership in Okta are not automatically reflected in CockroachDB Cloud unless the group is linked in the app integration. Refer to Automate Group Management.

5. In the dialog, click Deactivate.

   The app integration deprovisions the user's account from your CockroachDB Cloud organization.

To learn more, refer to Deprovision a user in the Okta documentation.

A linked group that is unassigned from the app integration continues to appear in CockroachDB Cloud unless it is unlinked. Refer to Automate Group Management.

Automate group management

By default, users and groups are provisioned in CockroachDB Cloud only when they are assigned to the app integration, and changes to a group's membership in Okta are not automatically reflected in CockroachDB Cloud. When Group Push is enabled in an app integration, modifying group membership in Okta is automatically reflected in CockroachDB Cloud.

To enable Group Push and link groups:

1. Log in to Okta Admin Dashboard as an admin user.
2. Click Applications and click the SAML app integration for your CockroachDB Cloud organization.

3. Click the Push Groups tab. Unless you disable Push group memberships immediately, changes you make in this tab will be applied immediately.

   1. To link a group, click Push Groups, then select it.
   2. To unlink a linked group, select it, then click Unlink pushed group.
   3. If you disabled Push group memberships immediately, click Push Now.

4. To disable Group Push, click Deactivate Group Push.

For more information and troubleshooting, refer to Manage Group Push in the Okta documentation.

What next?

• Learn more about Cloud Organization SSO
• Configure Cloud Organization SSO
• Learn more about authenticating to CockroachDB Cloud.

Was this helpful?