User Provisioning via SCIM – Support Center

This is a premium product add-on and must be purchased and configured through your Account Manager.

System for Cross-domain Identity Management (SCIM) is a system used for linking and managing identities in cloud-based applications and services. MANTL provides a SCIM 2.0 API, allowing the automation of onboarding, group reassignment, and off-boarding of users directly from your existing Identity Provider.

Official System for Cross-domain Identity Management website.

SCIM 2.0 was released as RFC7642, RFC7643 and RFC7644 under IETF in September 2015.

RFC7643 - SCIM: Core Schema
The Core Schema provides a platform-neutral schema and extension model for representing users and groups.
RFC7644 - SCIM: Protocol
The SCIM Protocol is an application-level, REST protocol for provisioning and managing identity data on the web.
RFC7642 - SCIM: Definitions, Overview, Concepts, and Requirements
This document lists the user scenarios and use cases of System for Cross-domain Identity Management (SCIM).

Considerations for Using SCIM

When choosing to use SCIM provisioning, carefully consider the following:

When SCIM is enabled for your organization in MANTL, users and roles in MANTL Console will become read-only. While you will be able to update a role's description and associated permissions, you will not be able to otherwise edit roles using the MANTL Console. User profiles and roles will need to be updated in your Identity Provider. Permissions and role associations must still be edited in the MANTL Console.
Users can only be deactivated, not deleted. If a user is off-boarded or removed from a relevant group, their status in MANTL should be updated accordingly. All other historical information associated with that user will remain in MANTL.
Deactivated users can be reenabled.
Groups can be hard-deleted, but not soft-deleted.
For organizations with multiple clients (i.e. brands) they may manage client assignment either at the user or role level.
- By default client assignments are made at the user level and managed within the Console. The system default is to assign all clients to a user. As a result, admins would update a user via the Console to limit client access as needed.
- Managing client assignments via roles may be desirable for organizations that have many users with varying client access. In this case, a group system will need to be created in the Identity Provider to control client assignments, after which client/role assignment can be managed via the Console, similar to permission/role assignment.

Supported Attributes

MANTL supports the following user attributes when working with SCIM provisioning:

First / Last Name: Users in the MANTL Console are required to have first and last name attributes.
Contact Info: MANTL only supports a single email address (required) and a phone number (optional) per user.
Address: MANTL does not support physical address, locale, or time zone attributes for users.
Core Code: Depending on your core configuration, some MANTL users have an optional attribute referred to as their Core Code. If this attribute is available in your core and IdP, it can be mapped to the employeeNumber attribute from the urn:ietf:params:scim:schemas:extension:enterprise:2.0:User schema.
Note: This value must contain only digits.

Our schemas are available from the API as part of our Service Provider Configuration Endpoints.

Integration

The remainder of this article dives into the technical aspects of our SCIM API to allow for development of custom integrations. If your Identity Provider is Azure/Entra ID, Okta, or SailPoint please refer to these specific integration articles instead:

SCIM in conjunction with Single Sign-On

It is presumed, although not required, that integrators of MANTL's SCIM API will also be integrating with our Open ID Connect (OIDC) support to allow the provisioned users easy login. In order for both systems to work together, MANTL needs to know which user attribute from the SCIM server maps to the sub (or other configured) claim provided by the OIDC Identity Provider. Notify your CSM or implementation manager which attribute should be used before syncing Users.

Supported Attributes:

userName (default)
externalId
email (not recommended as it would cause log in issues if the user's email were to change)

Accessing the API

Base URLs

Production: https://console.mantl.com/scim/v2
UAT: https://console.uat.mantl.com/scim/v2

Authorization

All requests made to MANTL's SCIM 2.0 API must be made using secure connections (https://) and include a Bearer Token via the Authorization Request Header Field (RFC 6750).

Your MANTL CSM will provide you with a token for authenticating requests. Because this is highly sensitive information, this will be sent to you using your preferred secured messaging platform and not emailed.

Rate Limiting

Once a client exceeds a limiting threshold, further requests to the Console domain are blocked with an HTTP 429 response that includes a Retry-After header to indicate when the client can resume sending requests. 429 responses will not include a valid SCIM JSON response body.

Service Provider Configuration Endpoints

MANTL supports the three endpoints defined by SCIM to facilitate discovery of SCIM service provider features and schemas.

/ServiceProviderConfig
An HTTP GET to this endpoint will return a JSON structure that describes the SCIM specification features available.
/Schemas
An HTTP GET to this endpoint is used to retrieve information about resource schemas supported by MANTL as a service provider.
/ResourceTypes
An HTTP GET to this endpoint is used to discover the types of resources available from the service provider (e.g., Users and Groups). Each resource type defines the endpoints, the core schema URI that defines the resource, and any supported schema extensions.

Supported Features

MANTL's SCIM API does not implement the following endpoints: /Bulk, /Me, /.Search.
SCIM allows for nested groups. However, MANTL maps SCIM Groups one-to-one with our Roles, this means our SCIM API will only allow Users to be members of Groups.
We do support modifying with PATCH per RFC 7644 Sec.3.5.2.
- PATCH requests always return an HTTP 204 response without a body.
MANTL only supports a subset of filtering operations when querying or PATCHing Resources.
The following are allowed: and, eq, (), and single-level attribute access via [].
Both attributes and excludedAttributes are supported per RFC 7644 Sec. 3.4.2.5.
We do not support returning groups when searching for users nor do we support returning users when searching for groups.
- This data is available when querying an individual User or Group, using the attributes param.
- SCIM does not have support for pagination on large collections of nested data, making it hard to control response size.

Example Requests

Search for User via userName

curl --request GET --header 'Authorization: Bearer {token}' 'https://console.uat.mantl.com/scim/v2/Users?filter=userName%20eq%20%22jane.doe%22'

{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "itemsPerPage": 1,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
      ],
      "id": "8faeee07-0347-435c-9d4a-8c8c6a6d2fcc",
      "userName": "jane.doe",
      "active": true,
      "name": {
        "familyName": "Doe",
        "givenName": "Jane"
      },
      "emails": [
        {
          "primary": true,
          "value": "jane_doe42@example.com",
          "type": "work"
        }
      ],
      "phoneNumbers": [],
      "meta": {
        "resourceType": "User",
        "created": "2022-11-21T14:54:38.986Z",
        "lastModified": "2022-11-21T14:54:41.050Z",
        "location": "/scim/v2/Users/8faeee07-0347-435c-9d4a-8c8c6a6d2fcc"
      }
    }
  ]
}

Deactivate User

curl --request PATCH 'https://console.uat.mantl.com/scim/v2/Users/8faeee07-0347-435c-9d4a-8c8c6a6d2fcc' \ 
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}'

PATCH requests always return an HTTP 204 response without a body.

Create Group

curl --request POST 'https://console.uat.mantl.com/scim/v2/Groups' \ 
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "externalId": "7c25a28e-9ebf-42a6-aaf3-c182111e208c",
    "displayName": "Consumer Account Managers",
    "meta": {
        "resourceType": "Group"
    }
}

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "05f33d22-75b7-47df-b3a0-68b57f746328",
  "externalId": "7c25a28e-9ebf-42a6-aaf3-c182111e208c",
  "displayName": "Consumer Account Managers",
  "members": [],
  "meta": {
    "resourceType": "Group",
    "location": "/scim/v2/Groups/05f33d22-75b7-47df-b3a0-68b57f746328"
  }
}

Add/Remove Members to Group

curl --request PATCH 'https://console.uat.mantl.com/scim/v2/Groups/05f33d22-75b7-47df-b3a0-68b57f746328' \ 
  --header 'Authorization: Bearer {token}' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "schemas": [
    "urn:ietf:params:scim:api:messages:2.0:PatchOp"
  ],
  "Operations": [
    {
      "op": "add",
      "path": "members",
      "value": [{ "value": "8d691641-d06e-4f01-9e9b-1c8d90ede1f4" }]
    },
    {
      "op": "remove",
      "path": "members[value eq \"80cdffc2-aecb-43da-9644-4cc84ec52876\"]"
    }
  ]
}'