New API's

Implement SCIM API in MainManager (EMM-2154)

SCIM is a standard for administering users and access in a system by external systems, e.g. Entra ID.

1. Overview

The API enables systems such as Entra ID to manage users automatically within MainManager. The API enables the system to create create, change and (soft) delete users and user roles. Users can not be completely deleted as they are important part of the history within the system.

To create a user the enterprise schema must be used as the employeeNumber attribute is required to identify the position within the organization hierarchy or the employee ID.

The API has the following settings:

If the default organization for new users is set, this is where all new employees will be located. They have to be manually moved to the correct organization within MainManager. If the value is not set, the enterprise schema field employeeNumber is assumed to have identification of the organization unit of the employee and it will be placed in the correct organization unit in the system.

The template user role is used to define access for new user role (SCIM group). This user role should have only the most basic access to ensure that new users do not get to much access automatically. The user role should then be manually adjusted to the correct intended access. Please note that administrators can easily copy access between user roles within the system.

Supported API calls are as follows:

2. User and group schema

If user is inactivated using e.g. PATCH then the position is inactivated and the user

Schema(example JSON Payload):

{

    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",

    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],

    "userName":"bjensen@testuser.com",

    "active": true,

    "id": "48af03ac28ad4fb88478",

    "externalId":"bjensen",

    "DisplayName": "Barbara Jensen",

    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

      "employeeNumber": "701984",

      "department": "Tour Operations"

      },

    "meta": {

     "resourceType": "User",

     "created": "2010-01-23T04:56:22Z",

     "lastModified": "2011-05-13T04:42:34Z",

     "version": "W\/\"3694e05e9dff591\"",

     "location":

"https://example.com/v2/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"

   }

}

In addition to the attributes required for the application, the JSON representation also includes the required id, externalId, and meta attributes.

3. Users and groups endpoints

This version of the SCIM implementation is focused on supporting Entra ID user mangement. See:

https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups

Users

Users have position(s) in MainManager. externalId is used as the users XID and the employeeNumber is used as the positions XID so we need to have the enterprise attributes containing the employeeNumber

Create user

Request

POST /Users

{

   "UserName": "UserNameUser1",

   "Active": true,

   "DisplayName": "DisplayNameUser1",

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:User",

    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User" ],

   "externalId": "externalIdUser1",

   "emails": [

       {

           "Primary": true,

           "type": "work",

           "value": "email1User1@SCIMTest.com"

       },

       {

           "Primary": false,

           "type": "home",

           "value": "email2User1Home@SCIMtest.com"

       }

   ],

   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

      "employeeNumber": "701984"

      }

}

Response

201 Created

{

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:User",

       "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

   ],

   "id": "2911",

   "userName": "UserNameUser1",

   "externalId": "externalIdUser1",

   "active": true,

   "emails": [

       {

           "Primary": false,

           "type": null,

           "value": "email1User1@SCIMTest.com"

       }

   ],

   "displayName": "DisplayNameUser1",

   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

       "employeeNumber": "701984",

       "costCenter": null,

       "organization": null,

       "division": null,

       "department": null

   },

   "meta": {

       "resourceType": "User",

       "created": "2024-08-07T14:44:53",

       "lastModified": "2024-08-07T14:44:53",

       "version": null,

       "location": "localhost/scim/v1/users/2911"

   }

}

409 Conflict

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:Error"

   ],

   "detail": "User already exists",

   "scimType": "uniqueness",

   "status": "409"

}

Change user

Request

PATCH /Users/2911

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:PatchOp"

   ],

   "Operations": [

       {

           "op": "replace",

           "path": "userName",

           "value": "UserNameUser1Changed"

       }

   ]

}

Response

200 OK

{

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:User",

       "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

   ],

   "id": "2911",

   "userName": "UserNameUser1Changed",

   "externalId": "externalIdUser1",

   "active": true,

   "emails": [

       {

           "Primary": false,

           "type": null,

           "value": "email1User1@SCIMTest.com"

       }

   ],

   "displayName": "DisplayNameUser1",

   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

       "employeeNumber": "701984",

       "costCenter": null,

       "organization": null,

       "division": null,

       "department": null

   },

   "meta": {

       "resourceType": "User",

       "created": "2024-08-07T14:44:53",

       "lastModified": "2024-08-09T11:31:00",

       "version": null,

       "location": "localhost/scim/v1/users/2911"

   }

}

404 Not Found

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:Error"

   ],

   "status": "409",

   "detail": "Resource 2922 not found"

}

Get user by id

Request

GET /Users/2911

Response

200 OK

{

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:User",

       "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

   ],

   "id": "2911",

   "userName": "UserNameUser1",

   "externalId": "externalIdUser1",

   "active": true,

   "emails": [

       {

           "Primary": false,

           "type": null,

           "value": "email1User1@SCIMTest.com"

       }

   ],

   "displayName": "DisplayNameUser1",

   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

       "employeeNumber": "701984",

       "costCenter": null,

       "organization": null,

       "division": null,

       "department": null

   },

   "meta": {

       "resourceType": "User",

       "created": "2024-08-07T14:44:53",

       "lastModified": "2024-08-07T14:44:53",

       "version": null,

       "location": "localhost/scim/v1/users/2911"

   }

}

404 Not found

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:Error"

   ],

   "status": "404",

   "detail": "User 2908 not found"

}

Get User by query

Request

GET /Users?filter=userName eq " UserNameUser1"

Response

{

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:User",

       "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

   ],

   "id": "2911",

   "userName": "UserNameUser1",

   "externalId": "externalIdUser1",

   "active": true,

   "emails": [

       {

           "Primary": false,

           "type": null,

           "value": "email1User1@SCIMTest.com"

       }

   ],

   "displayName": "DisplayNameUser1",

   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {

       "employeeNumber": "701984",

       "costCenter": null,

       "organization": null,

       "division": null,

       "department": null

   },

   "meta": {

       "resourceType": "User",

       "created": "2024-08-07T14:44:53",

       "lastModified": "2024-08-12T15:25:41",

       "version": null,

       "location": "localhost/scim/v1/users/2911"

   }

}

Delete User

Request

DELETE /Users/2911

Response

204 No Content

Groups

Create empty group

Request

POST /Groups

{

 "externalId":"externalIDGroup1}",

 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

 "displayName": "Group1DisplayName",

 "members":[]

}

Response

201 Created

{

   "members": [],

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:Group"

   ],

   "id": "94",

   "externalId": "externalIDGroup1",

   "meta": {

       "resourceType": "Group",

       "created": "2024-08-27T14:37:09",

       "lastModified": "2024-08-27T14:37:09",

       "version": null,

       "location": "localhost/scim/v1/groups/94"

   },

   "displayName": "Group1DisplayName"

}

409 Conflict

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:Error"

   ],

   "detail": "User role already exists",

   "scimType": "uniqueness",

   "status": "409"

}

Create group with members

Request

POST /Groups

{

 "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],

 "externalId":"externalIDGroup2",

 "displayName": "Group2DisplayName",

 "members":

 [

  {

  "value":"2924",

  "display":"DisplayNameUser1ForGroup2"

  }

 ]

}

Response

201 Created

{

   "members": [

       {

           "value": "2924",

           "display": "DisplayNameUser1ForGroup2",

           "ref": "localhost/scim/v1/users/2924"

       }

   ],

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:Group"

   ],

   "id": "96",

   "externalId": "externalIDGroup2",

   "meta": {

       "resourceType": "Group",

       "created": "2024-08-28T13:21:15",

       "lastModified": "2024-08-28T13:21:15",

       "version": null,

       "location": "localhost/scim/v1/groups/96"

   },

   "displayName": "Group2DisplayName"

}

Update group [Change display name]

Request

PATCH /Groups/96

{

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

   "Operations": [{

       "op": "Replace",

       "path": "displayName",

       "value": "Group2DisplayNameChanged"

   }]

}

Response

204 No Content

Update group [Add Members]

Request

PATCH /Groups/96

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:PatchOp"

   ],

   "Operations": [

       {

           "name": "addMember",

           "op": "add",

           "path": "members",

           "value": [

            {

            "displayName":"new User",

            "value":"2926"

            }

            ]

       }

   ]

}

Response

204 No Content

Update group [Remove Member list]

Request

PATCH /Groups/96

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:PatchOp"

   ],

   "Operations": [

       {

           "op": "remove",

           "path": "members",

           "value": [

            {

            "$ref": null,

            "value":"2926"

            }

            ]

       }

   ]

}

Response

204 No Content

Update group [Remove Member]

Request

PATCH /Groups/96

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:PatchOp"

   ],

   "Operations": [

       {

           "op": "remove",

           "path": "members[value eq "2926"]"

       }

   ]

}

Response

204 No Content

Update group [Remove all members from group]

Request

PATCH /Groups/96

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:PatchOp"

   ],

   "Operations": [

       {

           "op": "remove",

           "path": "members"

       }

   ]

}

Response

204 No Content

Get group by id

Request

GET /Groups/94

Response

200 OK

{

   "members": [],

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:Group"

   ],

   "id": "94",

   "externalId": "externalIDGroup1",

   "meta": {

       "resourceType": "Group",

       "created": "2024-08-27T14:37:09",

       "lastModified": "2024-08-27T14:37:09",

       "version": null,

       "location": "localhost/scim/v1/groups/94"

   },

   "displayName": "Group1DisplayName"

}

404 Not found

{

   "schemas": [

       "urn:ietf:params:scim:api:messages:2.0:Error"

   ],

   "status": "404",

   "detail": "User role 944 not found"

}

Get group by id excluding members

Request

GET /Groups/96?excludedAttributes=members

Response

200 OK

{

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:Group"

   ],

   "id": "96",

   "externalId": "externalIDGroup2",

   "meta": {

       "resourceType": "Group",

       "created": "2024-08-28T13:21:15",

       "lastModified": "2024-08-28T13:21:15",

       "version": null,

       "location": "localhost/scim/v1/groups/96"

   },

   "displayName": "Group2DisplayName"

}

Get Group by displayName

Request

GET /Groups?excludedAttributes=members&filter=displayName eq "externalIDGroup1"

Response

200 OK

{

   "schemas": [

       "urn:ietf:params:scim:schemas:core:2.0:Group"

   ],

   "id": "94",

   "externalId": "externalIDGroup1",

   "meta": {

       "resourceType": "Group",

       "created": "2024-08-27T14:37:09",

       "lastModified": "2024-08-27T14:37:09",

       "version": null,

       "location": "localhost/scim/v1/groups/94"

   },

   "displayName": "Group1DisplayName"

}

Get all Groups

Request

GET /Groups

Response

200 OK

[

   {

       "members": [],

       "schemas": [

           "urn:ietf:params:scim:schemas:core:2.0:Group"

       ],

       "id": "94",

       "externalId": "externalIDGroup1",

       "meta": {

           "resourceType": "Group",

           "created": "0001-01-01T00:00:00",

           "lastModified": "0001-01-01T00:00:00",

           "version": null,

           "location": "localhost/scim/v1/groups/94"

       },

       "displayName": "Group1DisplayName"

   },

   {

       "members": [

           {

               "value": "2924",

               "display": "DisplayNameUser1ForGroup2",

               "ref": "localhost/scim/v1/users/2924"

           }

       ],

       "schemas": [

           "urn:ietf:params:scim:schemas:core:2.0:Group"

       ],

       "id": "96",

       "externalId": "externalIDGroup2",

       "meta": {

           "resourceType": "Group",

           "created": "0001-01-01T00:00:00",

           "lastModified": "0001-01-01T00:00:00",

           "version": null,

           "location": "localhost/scim/v1/groups/96"

       },

       "displayName": "Group2DisplayNameChanged"

   }

]

Get all Groups excl members

Request

GET /Groups?excludedAttributes=members

Response

200 OK

[

   {

       "schemas": [

           "urn:ietf:params:scim:schemas:core:2.0:Group"

       ],

       "id": "94",

       "externalId": "externalIDGroup1",

       "meta": {

           "resourceType": "Group",

           "created": "0001-01-01T00:00:00",

           "lastModified": "0001-01-01T00:00:00",

           "version": null,

           "location": "localhost/scim/v1/groups/94"

       },

       "displayName": "Group1DisplayName"

   },

   {

       "schemas": [

           "urn:ietf:params:scim:schemas:core:2.0:Group"

       ],

       "id": "96",

       "externalId": "externalIDGroup2",

       "meta": {

           "resourceType": "Group",

           "created": "0001-01-01T00:00:00",

           "lastModified": "0001-01-01T00:00:00",

           "version": null,

           "location": "localhost/scim/v1/groups/96"

       },

       "displayName": "Group2DisplayNameChanged"

   }

]

Delete Group

Request

DELETE / Groups/96

Response

204 No Content