# SCIM Protocol The SCIM protocol streamlines user management for identity providers. By using SCIM, identity providers can ensure that changes made to user entitlements or profiles in their central system are pushed out to Immuta automatically. Without SCIM, users would have to log in to Immuta for updates in the identity provider to be reflected in Immuta. In the illustration below, the identity provider remains the source of truth for user accounts in Immuta and the external data platform. SCIM provisioning ensures that the user's account () remains in sync in the external data platform (Snowflake, for example) and Immuta.
Once SCIM is configured, users and their groups will be automatically provisioned in Immuta and will stay in sync, without users having to log directly in to Immuta. Then, Immuta can use groups from your identity provider to enforce access controls for your registered users, as illustrated in the image below.
When Taylor logs in to Snowflake to query the `Employee surveys` table, she is granted access to that table because the Immuta policy applies that grants users in the `Managers` group, the group that she is assigned to in the identity provider. ## SCIM provisioning in Immuta {% hint style="info" %} **SAML or OpenID Connect required** SAML or OpenID Connect are required to use SCIM in Immuta, and SCIM must be set up using the same identity provider as your SAML or OpenID Connect protocol. {% endhint %} Immuta supports the SCIM 2.0 protocol. SCIM operations are triggered in Immuta by one of two events: 1. **Identity provider registered in Immuta**: When your identity provider is connected to Immuta with SCIM enabled, Immuta checks for existing user accounts in Immuta. 1. If no user exists in Immuta, Immuta creates an Immuta account for the user. 2. If duplicates are found, Immuta sends a 409 error. 2. **Identity provider events**: After startup, subsequent SCIM updates are initiated by events in the identity provider. When a change is made to a user profile or a scheduled sync begins in the identity provider, the identity provider calls one of Immuta's SCIM endpoints. This design ensures that the identity provider is the single source of truth for user profiles. 1. Complete update 2. Partial update 3. Soft delete Scheduled SCIM syncs and reconciliations are not controlled by Immuta and must be configured in your identity provider. ### Sample SCIM JSON Immuta accepts the standard schema for users and groups as specified in [System for Cross-domain Identity Management: Core Schema](https://datatracker.ietf.org/doc/html/rfc7643). The following SCIM API endpoints are available for identity providers to send HTTP requests to in order to keep Immuta user accounts in sync with their profiles in your identity provider: * `GET`: Search for SCIM users and groups. * `POST`: Create SCIM users and groups. * `PUT`: Complete replacement of a user profile or group. * `PATCH`: Partial update of a user profile or group. * `DELETE`: Soft-delete a user profile or group. ### Provisioning group updates Immuta processes incremental, standards-compliant SCIM updates. To ensure that group membership changes are synced reliably, use the `PATCH` SCIM method to provide partial updates to your groups. The snippet below illustrates how to add members to a group using this method. See section 3.5.2 of [System for Cross-domain Identity Management: Protocol](https://datatracker.ietf.org/doc/html/rfc7644#section-3.5.2) for more guidance. {% code overflow="wrap" %} ``` { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], "Operations": [ { "op": "add", "path": "members", "value": [ { "value": "user-id-001" }, { "value": "user-id-002" }, { "value": "user-id-003" } // … // Approximately 100 members per request ] } ] } ``` {% endcode %} #### SCIM payload limits To ensure that group membership changes are synced reliably, use the `PATCH` SCIM method to provide partial updates to your groups, and batch these group membership updates to approximately [100 users per request](#user-content-fn-1)[^1]. Batching group membership updates helps mitigate the risk of provisioning timeout errors and failures. If you encounter SCIM provisioning errors related to group membership updates, reduce the batch size. ### Provisioning users #### Mapping external usernames to Immuta In order for policies to apply to users, external usernames must match between Immuta, the identity provider, and the data platform (Snowflake, Databricks, etc.). Validate that the usernames in your identity provider match those in your data platform. If they are incorrect in the IAM or the casing doesn't match, fix the data platform username in the identity provider before configuring SCIM in Immuta. Otherwise, policies will not be enforced correctly, as illustrated in the image below.
Additionally, if someone's username changes in the identity provider, SCIM will not update their username in Immuta. The account with the old username will remain active in Immuta even though the username is no longer valid in the identity provider. If you do need to update the username in Immuta, you must delete the user and provision a new one. To avoid this issue, use a unique identifier (such as an employee number) for Immuta usernames instead of email addresses (which could change if a user's name changes). #### Disabling user accounts Immuta never deletes users; instead, user accounts are disabled to preserve details for audit. * **User disabled in the identity provider**: The identity provider will call the `DELETE` SCIM endpoint in Immuta, and the user will be disabled in Immuta. If the user is ever re-enabled in the identity provider, a subsequent SCIM update will re-enable their account in Immuta. * **User account disabled in Immuta:** If a user account is disabled in Immuta, but not in the identity provider, subsequent SCIM updates will re-enable that user's account in Immuta. See the [Troubleshoot SCIM guide](/saas/configuration/people/section-contents/reference-guides/scim-protocol/troubleshoot-scim.md#user-accounts-are-orphaned-in-immuta) for more details on this behavior and potential problems it may cause. ## Microsoft Entra ID SCIM limitation {% hint style="info" %} **SCIM and Microsoft Entra ID** In some instances, updates in Microsoft Entra ID are instantly pushed to Immuta. In others, however, pushes update on a schedule (roughly every 40 minutes), and there is more than one sync event (i.e., users may be updated in the first event and user memberships in another). {% endhint %} Microsoft Entra ID SCIM will skip updates and will not inform Immuta that an attribute should be removed from a user in the following scenarios, even if the attribute mapping has been deleted from the IAM configuration on the Immuta app settings page: * Attribute is **set to empty** (removed) in Microsoft Entra ID * Attribute is **deleted** in Microsoft Entra ID In both of these scenarios, Microsoft Entra ID doesn’t send Immuta a payload to remove the attribute, as it considers the action a redundant export. As a result, the attribute values that previously existed in Microsoft Entra ID will not get removed from the user in Immuta. To remediate this limitation, take one of the following actions: * Change the attribute to a non-impacting value other than empty in Microsoft Entra ID. * Alternatively, remove the [attribute mapping from the attribute schema section of the IAM configuration on the Immuta app settings page](/saas/configuration/people/section-contents/how-to-guides/saml/microsoft-entra-id.md#create-an-iam). Then, trigger an update for that user in Microsoft Entra ID by making a change to any value for that user. Microsoft Entra ID will send an update for that user to Immuta, and Immuta will remove the attribute from the user. Note that if that attribute mapping is ever re-added in Immuta on the app settings page, that attribute will be added to the user again. See [Known issues for provisioning in Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/known-issues?pivots=app-provisioning#null-attribute-cant-be-provisioned) for more details about this limitation. [^1]: The maximum size is determined by the SCIM application. Most SCIM providers will limit batches like this automatically; however, if you've developed your own SCIM application, this limit is considered industry best practice. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://documentation.immuta.com/saas/configuration/people/section-contents/reference-guides/scim-protocol.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.