Synchronizing users and groups between an Identity Provider (IdP) such as Azure Entra ID and the Maximo Application Suite (MAS) is a critical step in enabling centralized identity and access management. MAS supports SCIM 2.0 for provisioning, but several nuances — and a few pitfalls — can impact the sync process if not understood clearly.
‍

This blog walks through:

• SCIM configuration steps in MAS

• Generating tokens for authentication

• Building MAS SCIM profiles

• Configuring Azure Entra SCIM provisioning

• Known challenges and how to resolve them

Creating an API Key in Maximo Application Suite

SCIM provisioning from Azure Entra ID to MAS requires a JWT token, which is derived from a MAS API Key.

Steps

1. Navigate to Suite Administration → API Keys and click Create API Key.

2. Provide a description and define an authentication token expiry.

3. Under Suite administrative access, select User management.

4. Click Submit.

5. Copy both:
   • API Key ID
   • Authentication Token

Note: MAS does not allow recovery of authentication token details.
‍

If lost, you must generate a new API key.

Generate a JSON Web Token (JWT)  

Once the API key and token are created, you must issue a GET request to generate a JWT. You can use postman to generate the token with details below.

API Endpoint

GET https://api.%3cmasdomain%3e/v1/authenticate]https://api.<masdomain>/v1/authenticate

Requirements

• Basic Auth:
  
  • Password = Authentication Token
  • Username = API Key ID

• Header:
  • mas-jwt-expiry-duration: P90D (example for 90 days)

Response

The response returns a JWT token that will be used by Azure Entra SCIM provisioning.

Creating a MAS SCIM Profile

A SCIM profile controls how identities and entitlements sync from the IdP. To create  a profile, hit the following URL POST request with body as the below.
‍

https://api.%3cmasdomain%3e/scim/v2/Profiles]https://api.<masdomain>/scim/v2/Profiles

• id: Identifies the profile and must be unique. It is recommended to use names such as MasTestProfile, MASDevProfile, etc.

• version: Specifies the version number of the profile. If any change is required during the development phase, you may need to delete the existing profile, increment the version number, and recreate the profile using the APIs.

• Identities – id: Identifies the SAML configuration in MAS. The default value is "default-saml".

• Identities – type: Should be set to "saml".

• Identities – samlid: This must be a unique identifier that matches your organization’s SAML ID. In the example provided, we used externalid. The External ID is mapped to User Principal Name for user attribute mapping and Object ID for group attribute mapping.

• Entitlement - application: You may choose any MAS user entitlement as the default. In the sample below, we have used BASE.

• Workspaces – Application: Defines the names of applications that will use the SAML configuration.

Reference: User synchronization with SCIM 2.0 - IBM Documentation

Example SCIM Profile - body

{

"id": "MasProfile1",

"version": 1,

"identities": [

{

"id": "default-saml",

"type": "saml",

"samlId": "externalId"

}

],

"entitlement": {

"application": "BASE"

},

"runtimeConfigs": {

"useGroupDisplayNameAsGroupId": true

},

"workspaces": [

{

"id": "test",

"applications": ["manage"]

}

]

}

Another Example SCIM Profile - body

{

"id": "MasProfile2",

"version": 2,

"identities": [

{

"id": "default-saml",

"type": "saml",

"samlId": "externalId"

}

],

"entitlement": {

"application": "BASE"

},

"workspaces": [

{

"id": "uat",

"applications": ["manage"]

}

],

"runtimeConfigs": {

"useGroupDisplayNameAsGroupId": true

}

}

Configuring Azure Entra SCIM Provisioning

Steps

1. In Azure Entra ID → Enterprise Applications, create an application for MAS.

2. Enable SCIM provisioning.

3. Set the Base SCIM URL:
   [https://api.%7bdomain%7d/scim/v2/%7bprofileId%7d]https://api.{domain}/scim/v2/{profileId}

4. For authentication, add the JWT Token generated earlier.

5. Test the connection → Azure should issue SCIM requests successfully.

6. Assign users and groups → provisioning begins.

Understanding Group Synchronization Challenges

Maximo Security Groups and their membership can be managed in Azure Entra project, while application authorizations are managed in Maximo Manage. When groups sync via SCIM, the group ID (e.g., AP_MAXIMO_SUPERVISORS_tyhntb) gets mapped as the Group Name in Maximo, causing it to create a new group instead of linking to the existing AP_MAXIMO_SUPERVISORS group. Since AP_MAXIMO_SUPERVISORS_tyhntb is the SCIM group ID, we can’t remove or remap it.
‍

When groups sync from Azure AD → MAS Core:

• MAS appends a suffix to the group name.

• Example:
  Azure group: AP_MAXIMO_SUPERVISORS
  MAS group becomes: AP_MAXIMO_SUPERVISORS_tyhntb
  ‍

This causes a new group to be created in Maximo instead of mapping to the existing Maximo Security Group.

Impact

• Group mappings break

• Membership does not align

• Existing Manage application authorizations are not reused

Solution

Add the following tag while creating the SCIM profile.
‍

"useGroupDisplayNameAsGroupId": true

This ensures MAS uses the display name as the group ID and avoids unwanted suffixes.
‍

Note: If modifying an existing profile in MAS, increase the "version" number. MAS only updates when the version changes.

Challenge: Azure Entra Sends Non‑Compliant SCIM PATCH Requests

When you remove a user from Azure Entra group, Entra sends the following patch request to MAS which forces MAS to delete all users from the group instead of one specific user.
‍

The patch request logged in MAS Core logs:
‍

PATCH: /scim/v2/MASStgProfileExt/Groups/Maximo-SECGROUP
‍

{
 'schemas': [...],
 'Operations': [
   {
     'op': 'Remove',
     'path': 'members',
     'value': [{'value': 'userid'}]
   }
 ]
}

This is NOT SCIM  compliant.

Correct SCIM Payload Should Be

{

"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],

"Operations": [

{

"op": "remove",

"path": "members[value eq \"userid\"]"

}

]

}

Resolution

Azure Entra provides a SCIM compatibility mode.
‍

Enable it by appending this parameter to the SCIM URL:
‍

?aadOptscim062020

Final SCIM URL Example

https://api.%7bmas-instance-id%7d.%7bdomain%7d/scim/v2/%7bprofileId%7d?aadOptscim062020]https://api.{mas-instance-id}.{domain}/scim/v2/{profileId}?aadOptscim062020

This resolves:

• Incorrect PATCH operations

• Group membership update failures

• Several other Azure SCIM interoperability issues

Reference:
‍

https://learn.microsoft.com/en-us/entra/identity/app-provisioning/application-provisioning-config-problem-scim-compatibility

‍