Why is Entra ID sending 'Add' Operations instead of 'Replace' Operations in PATCH request for multi-value attributes?

Question

I'm working on updating my application's SCIM endpoints to support Microsoft Entra ID, and I just noticed some strange behavior when a User is being updated, which seems specific to multi-value attributes.

In my Entra ID testing environment, I've set up the User Attribute Mappings to include a custom attribute, and checked the box for Multi-Value?: urn:ietf:params:scim:schemas:extension:greenhouse:2.0:User:department_ids, and am setting the value via an Expression on the User's department field: Split([department], ","). The odd behavior I'm experiencing is this - when I provision a User, and then update the department field on the Entra ID User, and re-provision them, I can see that the PATCH request being sent includes an Add Operation, rather than a Replace, which is what I would have expected. The body of the request looks like this:

{
  "schemas" => ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations" => [
    {
      "op" => "Add",
      "path" => "
urn:ietf:params:scim:schemas:extension:greenhouse:2.0:User:department_ids
",
      "value" => [{ "value" => "1"}]
    }
}

This is causing unexpected behavior, because from the perspective of someone trying to update a User in Entra ID, when they clear out and update the value of the User's department field, it should overwrite any existing value, i.e. trigger a Replace Operation. But instead since this is triggers an Add Operation, the end result is this: when a User in our application already has a value set for this department_ids, we will append that value to the existing value, and so the Entra ID User and the User in our application are out of sync.

How can I change things to trigger a Replace Operation in this case, rather than an Add? Am I mis-configuring this custom multi-value attributes? I have seen some confusing information in the Entra ID docs about custom mult-value attributes not being fully supported. For example from this documentation page:

Custom attributes can't be referential attributes, multi-value, or complex-typed attributes. Custom multi-value and complex-typed extension attributes are currently supported only for applications in the gallery.

Our application is in the Gallery, but is not yet approved for use with SCIM: does this mean this behavior with multi-value custom attributes will change once the application is approved for SCIM?

Finally, I also found two other similar questions (1 and 2), but the answer for 1 didn't apply in my case, and answer for the second was not particularly helpful.

Answer 1

As mentioned in the documentation that you quoted, custom multi-valued attributes are not supported. Not supported doesn't always mean "won't work at all" and can sometimes mean that the scenario hasn't been intentionally accounted for in the software design.

You cannot change the current behavior and should avoid using custom multi-valued attributes. Ideally the provisioning service would disallow you from configuring this, but that safeguard/restriction is not in place. If/when we add support for custom multi-valued attributes in the future, additional controls such as whether to use add or replace may be added, in addition to documentation on the behaviors of the provisioning service when interacting with multi-valued attributes.

Answer 2

Let's address your questions regarding multi-value custom attributes in Microsoft Entra ID.

Behavior of Multi-Value Attributes

When you’re updating a multi-value attribute like department_ids, Entra ID uses an “Add” operation instead of a “Replace” operation. This behavior is by design. When you re-provision a user, Entra ID appends the new value to the existing values rather than replacing them entirely. This is why you’re seeing the unexpected behavior.

Custom Multi-Value Attributes

Custom multi-value attributes are supported in Entra ID, but there are some limitations. According to the Microsoft Entra ID documentation, custom multi-value attributes are currently supported only for applications in the gallery. Since your application is in the gallery but not yet approved for SCIM, this behavior should change once your application is approved for SCIM.

Changing to Replace Operation

To achieve a “Replace” operation for multi-value attributes, you’ll need to handle this logic in your application. Here’s how you can do it:

1. Retrieve Existing Values: When updating a user’s department_ids, first retrieve the existing values.
2. Modify the Values: Modify the values as needed to reflect the desired changes.
3. Send a PATCH Request: Send a PATCH request with the updated values, ensuring the new value replaces the existing ones.

Here’s an example of how you can structure your PATCH request to remove existing values and add the new ones:

jsonCopy code
{

Remember that custom security attributes in Entra ID allow you to define and assign key-value pairs to objects, providing fine-grained access control. For more information on custom security attributes, you can have a look at these links:

• Custom Security Attributes Overview
• How to Use Custom Security Attributes
• Manage custom security attributes for an application

Next Steps

1. Modify your SCIM endpoint to handle the "Remove" operation followed by an "Add" operation as described above.
2. Review the attribute mappings in Entra ID to ensure they are correctly set up.
3. Monitor the approval process for your application's SCIM support, as full approval may resolve these limitations.