---
alias: operation-guide-security-portal-config-scim-provisioning
description: "Configure SCIM provisioning between Microsoft Entra ID and Critical Manufacturing Security Portal"
---

# 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:

```text
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](https://signup.microsoft.com/get-started/signup?products=FAF849AB-BD30-42B2-856C-8F1EDC230CE9&ali=1).

### 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](https://entra.microsoft.com/), 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.](../../images/scim_create_custom_application.png)

### 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.](../../images/scim_enterprise_application_overview.png)

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.](../../images/scim_select_users_and_groups.png)

### 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.](../../images/scim_open_provisioning.png)

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

    ![Provisioning overview page with New configuration and Connect your application highlighted.](../../images/scim_new_provisioning_configuration.png)

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:

```text
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.](../../images/scim_provisioning_credentials.png)

The `token_endpoint` value is available in the OpenID configuration.

![OpenID configuration JSON with the issuer and token_endpoint values highlighted.](../../images/scim_openid_configuration_token_endpoint.png)

!!! 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.](../../images/scim_start_provisioning.png)

## 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.](../../images/scim_mes_roles_created.png)

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

![MES Users page showing provisioned users from Microsoft Entra ID.](../../images/scim_mes_users_created.png)

!!! 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.](../../images/scim_nested_groups_warning.png)

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.