Configure SCIM Provisioning

On this page

System for Cross-Domain Identity Management SCIM helps centralize and automate provisioning, deprovisioning, and identity management for 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.

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.

To configure SCIM provisioning, an IAM admin creates a SCIM app integration in your IdP and configures it to authenticate to CockroachDB Cloud using a CockroachDB Cloud service account with the Org Administrator role.

From then on, the app integration works as follows.

Automatic provisioning

1. When an IAM admin assigns a user or group to the app integration, the app integration uses the CockroachDB Cloud API to provision an account for the user, or for each of the group's members.
2. When an IAM admin unassigns a user or group from the app integration, or when the user or group is removed from the IdP, the app integration removes or deactivates users in CockroachDB Cloud based on the app integration's assignments.

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.

SCIM Group Push with Okta

User accounts are provisioned in CockroachDB Cloud based on assignments in the SCIM app integration. Assigning an IAM group to the app integration is equivalent to assigning each of the group's members individually. However, depending on your IdP, assigning a group to the app integration may or may not automatically create a corresponding group in CockroachDB Cloud or keep its list of members in sync. Additional configuration of your IdP may be required. If you use Okta, you must enable Group Push to create and link groups in CockroachDB Cloud.

When CockroachDB Cloud has no awareness of group membership, role assignments must be applied to each user account separately.

Depending on what it supports, your IdP may provide a mechanism to sync IAM groups as groups in CockroachDB Cloud. In Okta, you must enable Group Push. When Group Push is enabled:

1. You can configure the SCIM app integration to selectively synchronize details about an IAM group to CockroachDB Cloud, including the group's name and membership list. In Okta, this group is said to be pushed.
2. Within CockroachDB Cloud, you can assign roles to a pushed group, and those roles are automatically assigned to the individual group members with provisioned accounts in CockroachDB Cloud.

3. A user account is only ever automatically provisioned in CockroachDB Cloud based on assignments in the SCIM app integration.

   • If a group is pushed but not assigned to the SCIM app in Okta, roles can be granted to the group in CockroachDB Cloud, and group members who are already provisioned in CockroachDB Cloud or who are assigned to the app integration in the future, automatically receive those roles.
   • If a group is assigned to the SCIM app in Okta but is not pushed, the group does not appear in CockroachDB Cloud, but user accounts are automatically provisioned for its members.

4. When details about a pushed IAM group change, such as the group's name or membership, these changes are automatically reflected in CockroachDB Cloud, unless group push is subsequently disabled for the group.

To learn more about Group Push, refer to Automate Group Management.

Requirements

1. As a user with the Org Administrator role:

   1. Enable Cloud Organization SSO.
   2. Create a service account with the Org Administrator 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.

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 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 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 import a CockroachDB Cloud organization's existing users into Okta. This helps to maintain an updated list of IAM users when an organization creates IAM users in a variety of ways. 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. To manage groups in CockroachDB Cloud, refer to Manage Groups in CockroachDB Cloud.

Assign a user or group

To provision a user to CockroachDB Cloud, you assign the user or one of their groups to the app integration.

After you assign a user to the app integration, changes that you make to the user's record in Okta, such as renaming the user or changing their email address, are automatically applied to the user's CockroachDB Cloud account.

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 user 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 with Okta

The following sections show how to enable and manage Okta's Group Push feature. For more information and troubleshooting, refer to Manage Group Push in the Okta documentation.

Enable Group Push

To enable Group Push and begin synchronizing a group with CockroachDB Cloud:

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:
      1. Click Push Groups, then select either Find groups by name or Find groups by rule.
      2. Find a group to push, and click its name.
      3. Under Match result & push action, click Create Group to create a new group in CockroachDB Cloud and link the Okta group to it. If a group exists in CockroachDB Cloud with the same name, click Link Group.
   2. To unlink a linked group, select it, then click Unlink pushed group.
   3. If you disabled Push group memberships immediately, click Push Now.

Disable Group Push

To disable Group Push, click Deactivate Group Push. You can optionally delete the group from CockroachDB Cloud. If you choose not to delete it, the group's membership stops being updated by the SCIM app integration, but the group's assigned roles continue to be applied to its members and can be modified.

Manage groups in CockroachDB Cloud

View a group's details

To view details about a group:

1. In CockroachDB Cloud Console, click Access Management > Groups.
2. In a group's row, click the three-dots Action button, then select any of View Members, View Parent Groups, or View Child Groups.

Manage a group's roles

Within CockroachDB Cloud, you can grant roles to a pushed group, and those roles are automatically granted to the group's members who have accounts in CockroachDB Cloud.

• When you push a group whose members already exist in CockroachDB Cloud and assign roles to the group, those members are granted the group's roles, in addition to roles explicitly granted to them.
• When the group's membership changes in your IdP, those changes are synchronized with the group in CockroachDB Cloud. If a CockroachDB Cloud account is added to or removed from the group in your IdP, they gain or lose roles granted to the group in CockroachDB Cloud.

This section shows how to view and manage a group's roles in the CockroachDB Cloud Console or using the Cloud API.

Troubleshooting

Assigned user is not provisioned in CockroachDB Cloud

When using Okta, if an assigned user, or all members of an assigned group, are not automatically provisioned, the failed operation is not automatically retried. To view the status of operations and retry failed operations, go to Dashboard > Tasks in the Okta admin dashboard. For further assistance, contact Support.

Group Push is enabled, but group is not provisioned in CockroachDB Cloud

When using Okta, if a configured group fails to be provisioned in CockroachDB Cloud, the failed operation is not automatically retried. To view the status of operations and retry failed operations, go to Dashboard > Tasks in the Okta admin dashboard. For further assistance, contact Support.

What next?

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

• Refer to the following topics in the Okta documentation:

  • Manage Users
  • Manage Groups
  • Manage Group Push

Was this helpful?