Contract Management user license assignments not syncing to Adobe I/O API

CRM Adobe Experience Cloud
, , , , , , , ,
1

We’re experiencing a critical issue where user license assignments created in Contract Management aren’t syncing properly to the Adobe I/O API endpoints. When we assign contract roles to users through the Contract Management interface, the entitlements show up correctly in the admin console, but downstream systems querying the Adobe I/O API don’t see these assignments.

We’ve verified our SSO attribute mapping includes the contract role claims, and the Adobe I/O service account has the required permissions. The sync connector logs show successful API calls, but the entitlement validation seems to fail silently.

{
  "userId": "user@company.com",
  "contractRoles": ["contract_viewer", "contract_editor"],
  "syncStatus": "success"
}

However, querying the same user through Adobe I/O returns empty contract roles. This is blocking 45+ users from accessing contract workflows. Has anyone dealt with multi-valued claim handling issues in the API gateway layer?

system 2

I’ll walk you through the complete fix since we just resolved this exact scenario last month.

1. SSO Attribute Mapping for Contract Roles: First, update your identity provider to send contract roles as a proper multi-valued claim. In your SAML configuration, change the contractRoles attribute type from ‘String’ to ‘Array’ or ‘Multi-valued’. The assertion should look like:

<Attribute Name="contractRoles">
  <AttributeValue>contract_viewer</AttributeValue>
  <AttributeValue>contract_editor</AttributeValue>
</Attribute>

2. Adobe I/O Service Account Permissions: Verify your service account has these specific scopes: ‘openid’, ‘AdobeID’, ‘read_organizations’, ‘additional_info.roles’, and ‘contract_management’. The ‘additional_info.roles’ scope is critical but often missed. You can check this in the Adobe Developer Console under your integration’s OAuth configuration.

3. Entitlement Validation Logic: The sync connector in AEC 2021 requires a schema version attribute in the claim metadata. Add this to your SAML assertion or JWT token:


schemaVersion: "v2.0"
claimType: "contractRoles"

4. Multi-valued Claim Handling in API Gateway: The API gateway expects contract roles in a specific JSON structure. When querying Adobe I/O API, ensure your request includes the ‘x-api-key’ header and the ‘expand=contractRoles’ query parameter. Without the expand parameter, the API returns user info but omits entitlement details.

Test the fix by:

  1. Assign a test user a contract role in Contract Management
  2. Wait 5-10 minutes for sync propagation
  3. Query Adobe I/O API with: GET /users/{userId}?expand=contractRoles
  4. Verify the response includes the contractRoles array

If you’re still seeing issues after these changes, enable debug logging in the sync connector (set log level to TRACE) and check for validation errors. The logs should show exactly where the entitlement validation is failing. In our case, the schema version was missing, causing silent failures that only showed up in trace-level logs.

One more thing - if you have multiple business units, ensure the contract role claims include the business unit context. The entitlement validator checks role-to-unit mappings, and missing context can cause authorization failures even when the roles sync correctly.

This draft is based on general Adobe Experience Cloud knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.

3

I’ve seen similar behavior with entitlement syncing. Check if your Adobe I/O service account has the ‘User.Read.All’ and ‘Contract.Manage’ scopes explicitly granted. Sometimes the sync appears successful but the API gateway filters out entitlements if the service account lacks proper delegation permissions.

cwright 4

Tested this on our Okta-to-Adobe SAML integration — switching contractRoles from String to Multi-valued attribute type immediately resolved the Adobe I/O API sync failures.

5

The issue might be with how multi-valued claims are being processed. Adobe I/O API expects contract roles as a JSON array, but some SSO providers send them as comma-separated strings. When the API gateway receives a string instead of an array, it might skip the entitlement validation entirely rather than throwing an error.

You should check your SAML assertion or JWT token structure. If the contractRoles claim is coming through as a string, you’ll need to configure your identity provider to send it as a proper array. Also verify that the claim name exactly matches what the sync connector expects - case sensitivity matters here. We had to update our Azure AD attribute mapping to use ‘extension_contractRoles’ instead of ‘contractRoles’ for proper array handling.

6

Good point about the claim format. I checked our SAML assertions and they’re sending contract roles as a single string with pipe delimiters: ‘contract_viewer|contract_editor’. That would explain why the API gateway isn’t processing them correctly. Did you need to make changes on both the IdP side and within Adobe Experience Cloud configuration?

7

Yes, this requires coordination between your identity provider and Adobe Experience Cloud settings. You need to configure your IdP to send the claim as a multi-valued attribute, not a delimited string. In most SAML configurations, there’s an option to mark an attribute as ‘multi-valued’ or ‘array type’. Once that’s fixed on the IdP side, verify the Adobe I/O service account permissions include both read and write access to contract entitlements.

8

Also worth checking the entitlement validation logic in your sync connector configuration. In AEC 2021, there’s a known quirk where the validator expects a specific schema version in the claim metadata. If your SAML assertion doesn’t include the schema version attribute, the gateway accepts the claim but doesn’t propagate it to the API layer.

You can test this by making a direct API call with a properly formatted JWT token that includes schema version ‘v2.0’ in the claim metadata. If that works, you know the issue is in the SSO attribute mapping rather than the Adobe I/O permissions.

giuseppe_martini 9

Once that’s fixed on the IdP side, verify the Adobe I/O service account permissions include both read and write access to contract entitlements.