Use SCIM for Astra entitlement management

SCIM for Astra entitlement management is available only to qualified participants in the private preview release. Development is ongoing, and the features and functionality are subject to change. This private preview is governed by your Agreement and the DataStax Preview Terms.

System for Cross-domain Identity Management (SCIM) is an open standard protocol designed to automate user identity provisioning across cloud-based applications and services. It provides a standardized REST API for managing user accounts, groups, and entitlements, eliminating manual provisioning workflows and reducing administrative overhead.

SCIM operations in Astra

The following SCIM operations are supported by the SCIM integration for Astra.

Be aware of the mapping between SCIM operations and Astra RBAC operations because there is no formal concept of groups in Astra.

SCIM operation

Astra operation

Behavior

Add user

Invite user to organization

Add a user to one or more groups in the Astra SCIM app in your IdP.

If the user already belongs to the target organization, they are assigned to the roles associated with the groups, as explained in Add user to group.

If the user doesn’t already belong to the target organization, then an invitation is sent to the user to join the organization. The user must accept the invitation.

Remove user

Remove user from organization

Remove a user from your IdP completely to remove them from the associated Astra organization. If the user never accepted their original invitation to the organization, then the pending invitation is revoked.

If you remove a user from all mapped groups in your Astra SCIM app, the user remains in the organization with only the UI View Only role. The user can sign in to the Astra Portal but they cannot perform any operations.

If you want to remove a user from a Astra organization without removing them from your IdP, you must manually remove the user from the organization.

Add group

Create a custom role in an organization

Custom roles can be created in Astra, and then pulled and mapped to IdP groups. Alternatively, you can create groups in your IdP that then generate corresponding custom roles in Astra. However, permissions for custom roles must be managed in Astra. SCIM cannot set or edit individual permissions for custom roles, aside from the initial creation of the role.

Astra default roles aren’t supported for SCIM group mappings. If you want to use SCIM for entitlement management with default roles, you must create custom roles that mirror those default roles.

Remove group

Delete a custom role in an organization

If you delete a custom role (group) from the Astra SCIM app in your IdP, then the corresponding custom role in Astra is deleted as well. If any users were assigned to that group, then they lose that role assignment in Astra.

Add user to group

Edit user’s role assignment in an organization

In your IdP user directory, add users to IdP groups that are mapped to Astra roles through the Astra SCIM app. Once assigned to a group, the user is granted the corresponding role in the associated Astra organization.

If the user doesn’t already belong to the associated organization, an invitation is sent, as explained in Add user.

SCIM isn’t a global Astra RBAC utility, and manual role modifications are still permitted even when SCIM is enabled. For more information, see SCIM enforces group membership unilaterally and doesn’t manage manually assigned roles.

Remove user from group

Edit user’s role assignment in an organization

In your IdP user directory, remove users from IdP groups that are mapped to Astra roles through the Astra SCIM app. Once removed from a group, the user loses the corresponding role in the associated Astra organization. For more information, see SCIM enforces group membership unilaterally and doesn’t manage manually assigned roles.

SCIM enforces group membership unilaterally and doesn’t manage manually assigned roles

SCIM isn’t a global Astra RBAC utility.

Manual role modifications are still permitted even when SCIM is enabled.

Administrators must ensure that role assignments are managed consistently, either through IdP group membership only or through manual assignment in Astra only. Additionally, administrators must ensure that only authorized users are granted roles that allow them to change other users' role assignments.

SCIM enforces one-way role assignments based on group membership only.

If you manually assign a role to a user in Astra, there is no change to their IdP group membership. SCIM synchronization only checks that a user is assigned to the roles granted by their group memberships. It doesn’t remove the additional manually assigned role even if that role is mapped to an IdP group that the user doesn’t belong to.

Similarly, if a role is granted through SCIM, it must be revoked through SCIM by editing the user’s IdP group memberships. If a user is granted a role based on their IdP group membership, and you manually remove that role from the user in Astra, then the user is reassigned to that role the next time SCIM synchronizes.

Default roles aren’t supported for SCIM entitlement management

Astra default roles aren’t supported for SCIM group mappings. If you want to use SCIM for entitlement management with default roles, you must create custom roles that mirror those default roles. Then, you can map those custom roles to IdP groups in your Astra SCIM app.

Enable SCIM in an Astra organization

In your IdP, create a SCIM app integration with entitlement management using the following information. For specific instructions, see your IdP’s documentation.

SCIM base URL: DEVOPS_API_DOMAIN/v2/scim. The default is https://api.astra.datastax.com/v2/scim unless you use custom domains or private endpoints for Astra.
SCIM bearer token: An Astra application token with a role like Organization Administrator that can read and write custom roles and read and write users.
Import Groups: If there is an option to allow importing groups, make sure this setting is enabled.

Once the app is created, you can import or create groups, which are equivalent to roles in Astra. Then, assign users to the groups to grant them the corresponding roles in Astra.

Multiple organizations require separate SCIM apps and groups

Each SCIM app is limited to one Astra organization. The associated organization is inferred from the application token used for the SCIM app.

If you have multiple organizations, then you must create separate SCIM apps in your IdP for each organization. Each app must have an application token scoped to the corresponding organization.

Each SCIM app has its own set of groups that are mapped to roles in the corresponding Astra organization.

Enterprise role management isn’t supported

You can use SCIM for entitlement management in Astra organizations only.

SCIM isn’t available for entitlement management at the enterprise level. You can use it for all organizations within an enterprise, but it cannot provision the cross-organization and enterprise-level roles that are managed at the enterprise level only.

Use the DevOps API for SCIM operations

You can also use the DevOps API to perform SCIM operations programmatically: