Skip to content

SCIM Provisioning#

Critical Manufacturing Security Portal supports System for Cross-domain Identity Management (SCIM) provisioning. The integration was developed and tested with Microsoft Entra ID, but it follows SCIM protocols and may also work with other SCIM clients.

Unless otherwise specified, the SCIM endpoint URLs in this page use the following base URL:

https://myserver/SecurityPortal/tenant/MES/scim/v2

Supported SCIM APIs#

Security Portal supports the ServiceProviderConfig, Schemas, and ResourceTypes metadata APIs.

List Users#

Use GET /Users to return a list of users. If the request includes a filter, the filter is applied before returning the list.

This endpoint supports the count, sortBy, sortOrder, and startIndex parameters.

Get User#

Use GET /Users/:id to return the user whose ID matches the id request parameter.

If the user is found and loaded correctly, a 204 response is returned with the user's data. If the user doesn't exist, a 404 response is returned.

Create User#

Use POST (/strategy/:strategy)?/Users/ to create a user in MES.

SCIM field MES User column
name.formatted, or displayName if name.formatted isn't set User name (UserName)
active Whether the user is enabled (IsEnabled)
userName User account (UserAccount)
strategyId, if defined as a URL parameter User strategy (StrategyId)
Primary email, or the first retrieved email if no primary email exists User email (MailAddress)
externalId User external ID (ExternalId)

Table 1: SCIM user creation mapping

The user name is mandatory and is derived in the following order:

  1. If the request contains the name subdocument, Security Portal uses name.formatted.
  2. If name.formatted doesn't exist or isn't set, Security Portal uses name.givenName and name.familyName.
  3. If name exists as a field and not as a subdocument, Security Portal uses the name value.
  4. If the request doesn't contain name, Security Portal uses displayName.

If the name isn't set, a 400 response is returned. If a user with the same name already exists, a 409 response is returned. If a generic error occurs, a 500 response is returned. If the user is created successfully, a 201 response is returned with the user's data.

Update User#

Use PATCH /Users/:id or PUT /Users/:id to update an existing user.

If the user doesn't exist, a 404 response is returned.

Operation SCIM field MES User column
Replace/Add emails. Add updates the email only if the current email isn't defined. User email (MailAddress)
Replace name.formatted or displayName User name (UserName)
Replace active Whether the user is enabled (IsEnabled)
Replace externalId User external ID (ExternalId)
strategyId, if defined as a URL parameter User strategy (StrategyId)

Table 2: SCIM user update mapping

Note

A soft delete from Microsoft Entra ID calls a patch operation and replaces the active value with false.

Delete User#

Use DELETE /Users/:id to delete the MES user that has the ID passed as a parameter.

If the user is deleted successfully, a 204 response is returned. If the user has references in MES and the deletion fails, Security Portal disables the user in MES. If the user is disabled successfully, a 204 response is returned.

If any other error occurs, a 500 response is returned. If the user doesn't exist, a 404 response is returned.

Create Role#

Use POST /Groups to create a role in MES.

SCIM field MES Role column
displayName Role name (Name)
externalId Role external ID (ExternalId)
description Role description (Description)

Table 3: SCIM role creation mapping

If the role is created successfully, a 201 response is returned with the role data.

Update Role#

Use PATCH /Groups/:id or POST /Groups/:id to update an existing role. This operation can also add or remove members by ID or external ID.

If the role doesn't exist, a 404 response is returned.

Operation SCIM field MES Role column or behavior
Replace displayName Group name (Name)
Replace description Role description (Description)
Replace/Add externalId Role external ID (ExternalId)
Add/Remove members Adds users or subroles to the role, or removes users or subroles from the role. The reference can be by ID or external ID.

Table 4: SCIM role update mapping

Bulk Operations#

Bulk operations aren't implemented.

Configure Microsoft Entra ID Provisioning#

The following procedure shows how to configure provisioning in Microsoft Entra ID to connect to Security Portal.

Note

This setup requires Microsoft Entra ID permissions that may not be available in all Azure accounts. For testing, you can use a Microsoft Entra Suite trial. A credit card may be requested during trial creation, but the trial used for this validation wasn't charged. For more information, see Try Microsoft Entra Suite for free ⧉.

Create an Enterprise Application#

Create an enterprise application to represent Security Portal. Because Security Portal and MES don't have a registered Microsoft Entra application, create a custom application.

  1. In the Microsoft Entra admin center ⧉, search for Enterprise applications.
  2. Select Create your own application.
  3. Enter the application name.
  4. Select Integrate any other application you don't find in the gallery (Non-gallery).

Create your own application dialog with the non-gallery application option selected.

Assign Users and Groups#

After you create the application, assign the users or groups that must be synchronized with MES.

Security Portal enterprise application overview page in Microsoft Entra ID, with the Assign users and groups tile highlighted.

If you have a group with the users that you want to synchronize with MES, select that group. The users in that group are created during provisioning.

Users and groups selection dialog with two groups selected.

Create a Provisioning Configuration#

Provisioning synchronizes the selected Microsoft Entra ID users and groups with Security Portal. Changes are made in the identity provider and then replicated in Security Portal.

  1. In the Security Portal enterprise application, select Provisioning.

    Security Portal enterprise application overview page with Provisioning selected in the navigation menu.

  2. Select New configuration, and then select Connect your application.

    Provisioning overview page with New configuration and Connect your application highlighted.

Microsoft Entra ID provisioning supports OpenID and bearer token authentication, so it works with Critical Manufacturing Security Portal.

Configure Admin Credentials#

To configure the provisioning credentials, use the OpenID configuration file for the Security Portal tenant:

https://%servername%/SecurityPortal/tenant/%tenantname%/.well-known/openid-configuration

Use the following values in the Microsoft Entra ID provisioning configuration:

Field Value
Authentication method OAuth2 client credentials grant
Tenant URL The issuer value from the OpenID configuration plus /scim/v2. Example: https://enigmatic-computatively-eleanor.ngrok-free.dev/SecurityPortal/tenant/MES/scim/v2
Token endpoint The token_endpoint value from the OpenID configuration. Example: https://enigmatic-computatively-eleanor.ngrok-free.dev/SecurityPortal/api/tenant/MES/oauth2/token
Client identifier The Security Portal client identifier. In the example, the value is MES.
Client secret The client secret from the Security Portal configuration.

Table 5: Microsoft Entra ID provisioning credential values

New provisioning configuration page showing OAuth2 client credentials grant fields for Tenant URL, Token endpoint, Client identifier, and Client secret.

The token_endpoint value is available in the OpenID configuration.

OpenID configuration JSON with the issuer and token_endpoint values highlighted.

Note

The example uses ngrok to expose a local development system to Microsoft Entra ID.

After entering the values, select Test connection. If the connection test is successful, start the provisioning process.

Provisioning overview page with Start provisioning highlighted.

Verify Provisioning in MES#

After provisioning runs, the roles assigned to the enterprise application are created in MES.

MES Roles page showing provisioned roles from Microsoft Entra ID.

The users associated with those roles are also created in MES.

MES Users page showing provisioned users from Microsoft Entra ID.

Note

In Microsoft Entra ID, if you have a subgroup that isn't part of the application groups, the members of that subgroup aren't synchronized. In the example, the TopSecurityGroup and The Beatles groups were assigned to the application, but the NotTopMostSecurityGroup subgroup wasn't. The subgroup itself was created because it is a direct member of TopSecurityGroup, but the members of the subgroup weren't added.

Microsoft Entra ID warning explaining that assigning a group to an application doesn't cascade access to nested groups.

Microsoft Entra ID provisioning runs every 40 minutes. During testing, this interval behaved as the minimum time between provisioning runs, and the actual interval was often longer than 40 minutes.