Configure SCIM Provisioning

On this page Carat arrow pointing down

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. Depending on how your IdP has implemented SCIM, some details may differ.

Refer to your IdP's documentation about configuring SCIM provisioning. For specific guidance, see the provider-specific sections below.

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 Organization Admin 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.

Note:

Some IdPs (such as Okta) disable deprovisioned users and do not support deleting them. Check your IdP's capabilities for user deprovisioning.

Supported features

  • Create users
  • Update user attributes
  • Deactivate users
  • Import users
  • Import groups
  • Group push

SCIM Group Provisioning

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 to enable group provisioning and create linked 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. When group provisioning 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.
  2. Within CockroachDB Cloud, you can assign roles to a provisioned 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 provisioned but not assigned to the SCIM app in your IdP, roles can be assigned 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 your IdP but is not provisioned, the group does not appear in CockroachDB Cloud, but user accounts are automatically provisioned for its members.

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

To learn more about group provisioning, refer to Automate Group Management.

Requirements

  1. As a user with the Organization Admin role:

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

Individual IdPs may impose different requirements, and the exact steps and requirements for enabling SCIM autoprovisioning depend upon your IdP. Some IdPs may require SCIM provisioning to be enabled only on specific authentication methods (such as custom SAML). Refer to your IdP's documentation about configuring SCIM provisioning.

Configure SCIM provisioning

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 Organization Admin role.

Depending on your setup, you can configure SCIM either via the Okta Integration Network (OIN) for a standardized app or manually for a custom SAML app integration.

Note:

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.

Add SCIM integration using Okta Integration Network (OIN)

  1. Log in to Okta Admin Dashboard as an admin user.
  2. Click Applications > Browse App Catalog.
  3. Search for Cockroach Labs > Click Add.
  4. Enter an Application label.
  5. Entity ID and ACS URL should be "NA".
  6. Click Next > Click Done.
  7. Go to Provisioning Tab and click Configure API Integration.
  8. Check Enable API integration.
  9. Provide API authentication token: the API token for a CockroachDB Cloud service account with the Organization Admin role.
  10. Test API Credentials > Click Save.
  11. 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.
  12. 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.

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 Organization Admin 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

Create Enterprise Application

  1. Go to the Azure portal.
  2. Navigate to Enterprise Applications.
  3. Click + New application.
  4. Choose Create your own application.
  5. Enter a name and select: "Integrate any other application you don't find in the gallery (Non-gallery)".
  6. Click Create.

Configure SAML SSO

  1. On the application's Overview page, click Set up single sign on.
  2. Next to the certificate labeled with Base64, click Download.
  3. Next to Login URL, click the Copy icon.

Configure SAML in CockroachDB Cloud

  1. Log in to CockroachDB Cloud Console as a user with the Org Administrator role.
  2. Navigate to Organization > Authentication.
  3. Next to Authentication Methods, click Add.
  4. Set Configuration to SAML.
  5. Set Provider Name to a display name of your choice.
  6. Click Next to open the Provider Details page.
  7. To edit the connection later, click Edit (keep the tab open).
  8. Paste the Login URL from Azure into the Sign-in URL field in CockroachDB Cloud Console.
  9. Open the downloaded Base64 SAML certificate file in a text editor and paste its contents (including the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines) into the Signing Certificate field.
  10. Click Save to store the configuration.

Complete SAML configuration in Azure

  1. Next to Download Metadata, click Download. The metadata file will be in XML format.
  2. Open the XML metadata and copy these values:
    • Entity ID: from the entityID attribute in <EntityDescriptor>
    • ACS URL: from the Location attribute in <AssertionConsumerService>
  3. Go back to Azure portal and under the Basic SAML Configuration, click Edit, then complete the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) fields using the values you retrieved from the metadata.
  4. Test the connection in the Cockroach console:
    • Click Test and follow the prompts.
    • If successful, the status will change to Verified.

Configure SCIM provisioning

  1. Create a service account in CockroachDB Cloud Console and generate an API token.
  2. Verify the SCIM endpoint by running:
   curl -X GET https://cockroachlabs.cloud/api/scim/v2/Users \
   -H "Authorization: Bearer <API_Token>"
  1. Go to Microsoft Entra Admin Center → Enterprise Applications, select the previously created SAML app, and navigate to Provisioning.
  2. Set the Provisioning Mode to Automatic.
  3. Fill in the admin credentials:
    • Tenant URL: https://cockroachlabs.cloud/api/scim/v2
    • Secret Token: use the API token created earlier.
    • Click Test Connection.
  4. Set User and Group mappings:
    • From the Microsoft Entra navigation, click "Attribute Mapping". The UI includes mappings like userPrincipalName → userName, mail → emails, etc.
    • Group mappings are also configured in a similar section.

Manage users and groups

The following sections show how to manage the access of users to your CockroachDB Cloud organization from your identity provider. 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.

Note:

When you assign a group to the app integration, accounts are provisioned for each of its members, but the group itself is not provisioned in CockroachDB Cloud. In Okta, you must enable Group Push to provision the group and add links to its member users in CockroachDB Cloud.

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

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.

Assign a user or group

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

Note:

When you assign a group to the Enterprise Application, accounts are provisioned for each of its members, but the group itself is not provisioned in CockroachDB Cloud unless group provisioning is enabled. To provision the group and add links to its member users in CockroachDB Cloud, ensure group provisioning is configured properly.

After you assign a user to the Enterprise Application, changes that you make to the user's record in Microsoft Entra ID, such as renaming the user or changing their email address, are automatically applied to the user's CockroachDB Cloud account.

  1. Log in to Microsoft Entra Admin Center as an admin user.
  2. Navigate to Enterprise Applications and click your CockroachDB application.
  3. Click Users and groups. When a user or group is assigned to an application, Microsoft Entra ID allows them to sign in to the application.
  4. Click Add user/group.
  5. Filter or search for a user or group. Next to them, click Select, then Assign.

CockroachDB Cloud user accounts are provisioned when a user or group is assigned to the Enterprise Application.

  1. 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 they may access your CockroachDB Cloud organization's custom login URL directly and select an SSO login method.

Unassign a user or group

To remove a user's access to CockroachDB Cloud, unassign the user from the Enterprise Application.

  1. Log in to Microsoft Entra Admin Center as an admin user.
  2. Navigate to Enterprise Applications and click your CockroachDB application.
  3. Click Users and groups.
  4. Next to a user or group, click the checkbox, then click Remove.

Note:
Unassigning an IdP group from the Enterprise Application disables each group member's CockroachDB Cloud organization account. Changes to a group's membership in Microsoft Entra ID are not automatically reflected in CockroachDB Cloud unless group provisioning is enabled.

  1. In the dialog, click Remove.

The Enterprise Application deprovisions the user's account from your CockroachDB Cloud organization.

Automate group management

Group provisioning in Microsoft Entra ID allows you to automatically synchronize groups from your IdP to CockroachDB Cloud.

Enable group provisioning

To enable group provisioning and begin synchronizing groups with CockroachDB Cloud:

  1. Log in to Microsoft Entra Admin Center as an admin user.
  2. Navigate to Enterprise Applications and click your CockroachDB application.
  3. Click Provisioning.
  4. Under Mappings, ensure that Provision Microsoft Entra ID Groups is enabled.
  5. Click Provision Microsoft Entra ID Groups to configure group attribute mappings.
  6. Ensure the necessary group attributes are mapped correctly (e.g., displayName → displayName).
  7. Save the configuration and monitor the provisioning status.

Disable group provisioning

To disable group provisioning, navigate to the Provisioning section and disable the Provision Microsoft Entra ID Groups mapping. You can optionally delete the groups from CockroachDB Cloud. If you choose not to delete them, the groups' membership stops being updated by the SCIM app integration, but the groups' assigned roles continue to be applied to their 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 assign Cloud Console roles to a provisioned group, and those roles are automatically assigned to the group's members who have accounts in CockroachDB Cloud.

  • When you provision a group whose members already exist in CockroachDB Cloud and assign roles to the group, those members are assigned the group's roles, in addition to roles explicitly assigned 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 assigned to the group in CockroachDB Cloud.

Using Cloud Console

  1. In CockroachDB Cloud Console, click Access Management > Groups.
  2. In a group's row, click the three-dots Action button, then click Edit Roles.
  3. The group's assigned roles are shown. Add or remove roles, then click Confirm.

Note:
The fields for inherited roles are read-only, because inherited roles cannot be edited directly. Instead, you must either remove the role from the parent group from which it is inherited, or remove the child group from the parent group.

Using ccloud API

Each group provisioned to CockroachDB Cloud is assigned an ID, which is required to manage the group's roles using the CockroachDB Cloud API or Terraform provider, but is not displayed in the CockroachDB Cloud Console. A group's ID is returned when you:

To manage a group's roles, you can use the Role Assignment API or the cockroach_user_role_grants Terraform provider resource.

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.

Assigned user is not provisioned in CockroachDB Cloud

When using Microsoft Entra ID, if an assigned user, or all members of an assigned group, are not automatically provisioned, check the provisioning status in the Provisioning section of your Enterprise Application. To view the status of operations and retry failed operations, go to Enterprise Applications > [Your App] > Provisioning > Provisioning logs in the Microsoft Entra Admin Center. For further assistance, contact Support.

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

When using Microsoft Entra ID, if a configured group fails to be provisioned in CockroachDB Cloud, check the group mappings and provisioning status. To view the status of operations and retry failed operations, go to Enterprise Applications > [Your App] > Provisioning > Provisioning logs in the Microsoft Entra Admin Center. Ensure that group provisioning is enabled in the attribute mappings. For further assistance, contact Support.

What next?

For Okta users, refer to the following topics in the Okta documentation: - Manage Users - Manage Groups - Manage Group Push

For Microsoft Entra ID users, refer to the following topics in the Microsoft documentation: - Manage users in Microsoft Entra ID - Manage groups in Microsoft Entra ID - Configure automatic user provisioning

On this page

Product

Resources

Learn

Support Channels

Company

Get developer news

×
★ ★ ★ ★ ★