User synchronization with SCIM 2.0

Starting in Maximo® Application Suite 9.0, you can synchronize users and groups from an external identity provider by using the System for Cross-domain Identity Management (SCIM) 2.0 protocol.

SCIM 2.0 support simplifies user management by enabling external identity providers, such as Okta or Microsoft Entra, to synchronize users and groups through a push mechanism. The SCIM specification defines a common schema for user and group resources with a protocol that defines how operations are performed on those resources. SCIM facilitates the exchange of these resources across different services.

By using SCIM capabilities in Maximo Application Suite, existing users and groups that are defined in an identity provider are automatically synchronized with Maximo Application Suite when those resources are assigned access. Therefore, you do not need to manually add users or groups into the Suite. Also, updates or removal of access is automatically synchronized when the appropriate configuration is applied in the identity provider.

SCIM APIs

Maximo Application Suite can use SCIM 2.0 to integrate with identity providers by using a set of API endpoints from Maximo Application Suite. These APIs implement the SCIM 2.0 protocol and are initiated by the identity provider, which acts as a client, to manage user and group lifecycle operations.

Note: These APIs are to be used only with integration between Maximo Application Suite and an identity provider for user and group synchronization. This information is provided for reference usage by experienced administrators.

The Maximo Application Suite APIs are accessed by using the base URL: https://api.{mas-instance-id}.{domain}/scim/v2/{profileId}.

You can use the following endpoints to apply create, retrieve, update, and delete operations on user resources,

Table 1. User endpoints to create, retrieve, update, and delete operations on user resources
Endpoint	Method	Description
/scim/v2/`{profileId}`/Users	`POST`	Pushes a new user into Maximo Application Suite.
/scim/v2/`{profileId}`/Users	`GET`	Retrieves users with filtering and paging.
/scim/v2/`{profileId}`/Users/`{userId}`	`GET`	Retrieves a specific user.
/scim/v2/`{profileId}`/Users/`{userId}`	`PUT`	Updates a specific user.
/scim/v2/`{profileId}`/Users/`{userId}`	`PATCH`	Updates any changed fields for a specific user.
/scim/v2/`{profileId}`/Users/`{userId}`	DELETE	Deletes a specific user.

You can use the following endpoints to apply create, retrieve, update, and delete operations on group resources.

Table 2. Group endpoints to create, retrieve, update, and delete operations on group resources
Endpoint	Method	Description
/scim/v2/`{profileId}`/Groups	`POST`	Pushes a new group into Maximo Application Suite.
/scim/v2/`{profileId}`/Groups	`GET`	Retrieves groups with filtering and paging.
/scim/v2/`{profileId}`/Groups/`{groupId}`	`GET`	Retrieves a specific group.
/scim/v2/`{profileId}`/Groups/`{groupId}`	`PUT`	Updates a specific group
/scim/v2/`{profileId}`/Groups/`{groupId}`	`PATCH`	Updates any changed fields for a specific group
/scim/v2/`{profileId}`/Groups/`{groupId}`	`DELETE`	Deletes a specific group

Maximo Application Suite SCIM profiles

The {profileId} in the base URL is a user-selected ID for a Maximo Application Suite resource that is called the Maximo Application Suite SCIM profile.

A SCIM profile is a collection of Maximo Application Suite configurations that acts as a template to configure users and groups as they are added into Maximo Application Suite. You use a SCIM profile because the SCIM schema defines the general users and groups attributes and does not include specific Maximo Application Suite elements that are necessary for a functional user, such as the ability to log in, entitlements, and application permissions. This Maximo Application Suite SCIM profile is applied to the following configurations:

Workspace access
Application access
Entitlement
Identity configuration

The following fields are also included in the configuration:

id: The {profileId} that is used in the base URL and is how Maximo Application Suite identifies which profile to apply to incoming API requests.

version: The version of the profile model resource. The only valid value in Maximo Application Suite 9.0 is 1.

By including the {profileId} in the base URL that is used to configure an external identity provider SCIM integration, the provision requests that the identity provider are linked to a Maximo Application Suite SCIM profile. The configuration can be applied to the new users or groups at the point of synchronization. Synchronized users can then log in and access applications without the need for further manual administrative action.

The Maximo Application Suite SCIM profile is used to configure the user or group once, at the point that the user or group is created. The following rules are applied when you use the Maximo Application Suite SCIM profile:

If the profile does not exist when a user or group is added, the configuration is not applied. Administrators must manually configure the users.
If the profile is updated after a user or group is imported, those changes apply only to new users or groups that are created after the updates. Any changes are not retroactively applied to any existing users or groups.
If an administrator updates a user or group in Maximo Application Suite, those changes are not modified or undone by the application of a Maximo Application Suite SCIM profile.

In Maximo Application Suite 9.0, you can configure the SCIM profile resource only by using APIs.

Table 3. SCIM profile API endpoints
Endpoint	Method	Description
/scim/v2/Profiles	`POST`	Creates a Maximo Application SuiteSCIM profile.
/scim/v2/Profiles	`GET`	Retrieves Maximo Application Suite SCIM profiles with paging.
/scim/v2/Profiles`{profileId}`	`GET`	Retrieves a specific Maximo Application Suite SCIM profile.
/scim/v2/Profiles/`{profileId}`	`PUT`	Updates a specific Maximo Application Suite SCIM profile.
/scim/v2/Profiles/`{profileId}`	`DELETE`	Deletes a specific Maximo Application Suite SCIM profile.

A Maximo Application Suite SCIM profile has the following structure:

{
  "id": "myprofilename",
  "version": 1,
  "identities": [
    {
      "type": "local"
    },
    {
      "id": "default-saml",
      "type": "saml",
      "samlId": "userName"
    },
    {
      "id": "default-ldap",
      "type": "ldap",
      "ldapUsername": "userName"
    }
  ],
  "entitlement": {
    "application": "BASE"
  },
  "workspaces": [
    {
      "id": "workspace1",
      "applications": [
        "manage"
      ]
    }
  ]
}

You can provide the following main elements to the configuration:

Identities
Entitlement
Workspaces

Identities

Identities specify the authentication mechanisms that are configured when a new user is added to Maximo Application Suite. This mechanism is an array where multiple configurations can be added when necessary to enable multiple authentication options for users.

Starting in Maximo Application Suite 9.0, the following authentication type options are available for user identities:

local: User authentication is managed by a local Maximo Application Suite username and password.; When you specify local as the type of the identity configuration, additional configuration is not required. The SCIM userName field of the imported user is used as the Maximo Application Suite username and a random password is generated and emailed to the user.

Saml

User authentication is managed by a SAML identity provider.

When you specify saml as the type of identity configuration, the following fields are also required.

id: The Maximo Application Suite ID of the identity provider.

samlId

The name of a SCIM user attribute that is extracted from the imported user that represents the SAML ID.

When you specify the samlId field, you are not specifying a specific value for any particular user. You are indicating which field of the user record is used as the SAML ID, for example, whatever the value of the userName field is.

The value of this field supports a limited form of expressions to target the appropriate field. The expressions are based on the SCIM patch path expressions. For more information, see Modifying with Patch in the System for Cross-domain Identity Management (SCIM) specification.

The PATH attribute follows the ABNF syntax rule PATH = attrPath / valuePath [substrata]. Where attrPath and valuePath are defined by the ABNF filtering rules.

For more information, see Filtering for system for Cross-domain Identity Management 2.0 (SCIM) protocol.

Use a limited expression when you need to specify that the primary email field is to be used as the samlId but is not the same as the userName. When you use a limited expression, the samlId can be specified as emails[primary eq true].value

Ldap

User authentication that is managed by an LDAP identity provider.

When you specify ldap as the type of configuration, the following fields are also required.

id: The Maximo Application Suite ID of the identity provider.

ldapUsername: The name of a SCIM user attribute that is extracted from the imported user to represent the LDAP username.

When you specify the ldapUsername field, you are indicating which field of the user record is used as the LDAP username, for example, whatever the value of the userName field is.

The value of this field supports a limited form of expressions to target the appropriate field. The expressions are based on the SCIM patch path.

Entitlement

Entitlement specifies the level of entitlement that is granted to the user. Starting in Maximo Application Suite 9.0, you can automate the assignment of application- level entitlement by using only this configuration.

The following entitlements can be assigned:

NONE
SELF_SERVICE
LIMITED
BASE
PREMIUM

For more information, see User entitlement and access in Maximo Application Suite in 9.0 and earlier.

Workspaces

You configure workspaces to specify access to Maximo Application Suite workspaces and applications. This configuration is applied to both users and groups when they are pushed into Maximo Application Suite.

You specify the following fields in the workspace configuration:

id: The identity of the Maximo Application Suite workspace that the user or group is added to.

applications: A list of applications, by ID, that the user or group is added to.

The applications are listed by Maximo Application Suite application IDs that a user is granted a USER role to or that a group is synchronized with.

You can query the application IDs by using a GET request with the following API: https://api.{mas-instance-id}.{mas-domain}/applications. For more information, see API reference get information about all applications.