Deserialization error in Entra ID attribute mapping using appRoleAssignment

Question

Deserialization error in Entra ID attribute mapping using appRoleAssignment

Katie 0

We have noticed a specific scenario where, when an appRoleAssignment is added as a user attribute mapping for an enterprise SCIM app with any of the following values:

roles[primary eq "True"].value
roles[primary eq "True"].display
roles[primary eq "True"].type

some users end up with a corrupted roles field, which prevents us from applying changes to SCIM resources. Once the attributes enter this bad state, we encounter the following deserialization error in Entra when attempting to make subsequent changes to that user:

errorCode: SystemForCrossDomainIdentityManagementServiceIncompatible errorMessage: Error: We are not able to deserialize the resource received from your SCIM endpoint because your SCIM endpoint is not fully compatible with the Azure Active Directory SCIM client.

Upon examining the attribute mappings received in the target service, we observed that sometimes the roles attribute is sent to the service provider in the following format, which does not cause issues:

"roles": [
  {
    "type": "WindowsAzureActiveDirectoryRole",
    "value": "<?xml version=\"1.0\" encoding=\"utf-16\"?>.....",
    "primary": true
  },
  {...}
]

However, other times it appears in this format:

"roles": [
  {
    "type": "WindowsAzureActiveDirectoryRole",
    "value": "<?xml version=\"1.0\" encoding=\"utf-16\"?>.....",
    "primary": "True"
  },
  {...}
]

This second format results in the deserialization error mentioned above. We suspect that the issue is caused by the "primary" attribute being sent as a string ("True") instead of a boolean (true). We have a few questions regarding this behavior:

What is the source field for the deserialization error?
Why is this field inconsistent? What causes it to appear as a string in some cases and a boolean in others?
Should appRoleAssignment NOT be used as a direct attribute mapping field?

We noticed a note in Microsoft’s documentation on attribute mapping for SCIM apps stating:

Mapping an appRoleAssignment in Microsoft Entra ID to a role in your application requires that you transform the attribute using an expression. The appRoleAssignment attribute shouldn't be mapped directly to a role attribute without using an expression to parse the role details.

Does this mean that appRoleAssignment should NOT be mapped directly, and instead should always be transformed using an expression to correctly handle role data and avoid issues like this?

1 answer

Your answer

Answer 1

Hello Katie,

Welcome to Microsoft Q&A Platform. Thank you for reaching out & hope you are doing well.

I will try to clarify your doubts regarding this issue.

As you asked, "What is the source field for the deserialization error?"

The source field causing the error is the primary attribute within the roles complex type. The deserialization failure occurs because the Entra ID SCIM client receives a string value ("True") for this field, while its internal schema (and the SCIM specification) requires a boolean value (true). You’re mapping appRoleAssignment directly to a SCIM role attribute. Sometimes the data looks fine, but other times the “primary” field is sent as text "True" instead of a real boolean true. When that happens, Entra can’t understand the response from your SCIM endpoint and throws a deserialization error. This happens because the raw appRoleAssignment data isn’t normalized for SCIM, it’s XML-based and needs parsing before sending to the target app.

Why is this field inconsistent? What causes it to appear as a string in some cases and a boolean in others?

This inconsistency is a symptom of an internal platform behavior within the Entra ID provisioning service when handling the raw multi-valued appRoleAssignment attribute. It suggests that the logic responsible for translating the native Entra ID role structure into the SCIM format sometimes fails to cast the boolean flag correctly, resulting in an inconsistent serialization, this behavior is not controllable by the user.

Should appRoleAssignment NOT be used as a direct attribute mapping field?

Your understanding is correct, the specific note you found in the documentation indicates that appRoleAssignment should not be mapped directly.

The raw appRoleAssignment attribute in Entra ID is a complex, multi-valued attribute that represents the entire collection of roles assigned to a user for that application. Mapping it directly leads to the internal serialization inconsistencies you observed, as the provisioning engine handles the entire structure.

Does this mean that appRoleAssignment should NOT be mapped directly, and instead should always be transformed using an expression to correctly handle role data and avoid issues like this?

Yes, the recommendation is 'Do NOT map appRoleAssignment directly'. Instead of mapping the complex appRoleAssignment attribute directly, you must use an expression (a provisioning function) to extract and format the specific piece of data you need.

This function takes the list of appRoleAssignment objects and transforms it into a clean, SCIM-compliant array of roles, correctly formatting all fields (including primary) as needed. Use transformation expressions like SingleAppRoleAssignment or AppRoleAssignmentsComplex to extract, parse, and correctly format role assignments before syncing. This ensures the "primary" field is consistently a boolean, preventing deserialization errors.

For e.g. You should replace your direct mapping (e.g., roles[primary eq "True"].value) with an expression, typically using the SelectRole function: SelectRole(appRoleAssignment, "RoleName")

Source Attribute: appRoleAssignment
Target Attribute: roles
Mapping Type: Expression
Expression: SelectRole(appRoleAssignment, "Admin") (where "Admin" is the value of the role you want to map).

This transformation can ensure the data conforms to the SCIM schema and bypasses the internal serialization issue, preventing the primary: "True" error.

Please do refer below document for reference:

https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes

https://learn.microsoft.com/en-us/entra/identity/app-provisioning/known-issues?pivots=app-provisioning#deserialization-error-in-entra-id-using-approleassignment

https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups

NOTE: The error occurs because the SCIM payload is invalid when primary is a string. This happens if appRoleAssignment is mapped directly. Microsoft recommends always using an expression to parse and normalize appRoleAssignment data before sending it to the SCIM endpoint.

Hope this helps somehow! If it answered your question, please consider clicking Accept Answer and Upvote. This will help us and others in the community as well.

If you need more info, feel free to ask in the comments. Happy to help!

Regards,

Monalisha

Share via

Deserialization error in Entra ID attribute mapping using appRoleAssignment

1 answer

Your answer