The Groups APIs can be used to update a user's role and organization. In the OneTrust application, a SCIM group is a combination of a role and organization. If your account has 20 roles and 2 organizations, that effectively means that you have 20 x 2 = 40 unique groups.
Steps
- Obtain the user's unique id
- Identify the SCIM group that corresponds to the required role and organization
- Obtain the group's id
- Use the Groups API to add the user to the group or to remove the user from the group
What parameters are required to update a user's role or organization?
- The user's unique id represented by
id - The group's unique id represented by
groupId
Step 1: Obtaining the user's unique id id
idThe GET /Users endpoint can be used to retrieve the list of all Active and Inactive users in the account. If any of the user's basic attributes such as 'First Name', Last Name' or 'Email Address' are known, they can be used to obtain the user's id.
Example Request:
GET /api/scim/v2/Users?filter=givenName sw "Google" and familyName sw "User" HTTP/1.1
Host: https://trial.onetrust.com
Content-Type: application/json
Authorization: Bearer {OAuth Access Token}
Response Body:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 8,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [
{
"id": "dd525596-f8bb-45d8-83e5-02bbb3c501a1",
"externalId": null,
"meta": {
"created": "2020-09-22T13:57:14.813+00:00",
"lastModified": "2020-10-08T20:23:12.147+00:00",
"location": "https://app-au.onetrust.com/api/scim/v2/Users/dd525596-f8bb-45d8-83e5-02bbb3c501a1",
"resourceType": "User"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"userName": "[email protected]",
"name": {
"familyName": "User",
"givenName": "Google"
},
"userType": "Internal",
"active": true,
"groups": [
{
"value": "444fd8af-e1ee-4742-b1af-94165a8c28c6:4a3227b7-a05f-423c-8ab0-307aa16a12b2",
"display": "Assessments Manager - Org5"
},
{
"value": "16e476bc-727d-41ae-88b2-298de3c41291:058adecf-b998-4886-9f06-87e36e09b037",
"display": "Awareness Training Learner - Org6.1"
},
{
"value": "7adac9e4-b3e4-4221-83d1-f174134b5445:6e051cbf-1e3b-4815-8216-50e2a0518438",
"display": "Audit Manager - Azure AD"
}
],
"emails": [
{
"value": "[email protected]",
"display": "[email protected]",
"primary": true,
"type": "work"
}
],
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"businessUnit": null,
"division": null,
"employeeId": null,
"officeLocation": null,
"department": null,
"manager": {
"value": null,
"displayName": null,
"$ref": "https://trial.onetrust.com/api/scim/v2/Users/dd525596-f8bb-45d8-83e5-02bbb3c501a1"
},
"jobTitle": null
}
}
]
}
Note that the above response contains the user's id which is dd525596-f8bb-45d8-83e5-02bbb3c501a1. Additionally, the response also returns the groups that the user is currently part of. The groups are:
- Assessments Manager - Org5
- Awareness Training Learner - Org6.1
- Audit Manager - Test Org
The naming convention of a group is in the format {Role} - {Organization}. Therefore, it can be inferred that the user has the Assessments Manager role in the organization Org5, the Awareness Training Learner role in the organization Org6.1, and the Audit Manager role in the organization Test Org.
Step 2: Obtaining the Group's unique Id groupId
groupIdThe GET /Groups endpoint can be used to retrieve the list of groups from the account.
SCIM filtering is not currently supported for Groups. By using custom scripts, the required role and organization combination can be obtained from the response of the above API.
Example Request:
GET /api/scim/v2/Groups?startIndex=1&count=1 HTTP/1.1
Host: https://trial.onetrust.com
Authorization: Bearer {OAuth_Access_Token}
Content-Type: application/x-www-form-urlencoded
Response Body:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"totalResults": 130,
"startIndex": 1,
"itemsPerPage": 1,
"Resources": [
{
"id": "444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
"externalId": null,
"meta": {
"created": "2020-10-08T20:20:41.213+00:00",
"lastModified": "2020-10-16T00:28:10.973+00:00",
"location": "https://trial.onetrust.com/api/scim/v2/Groups/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
"resourceType": "Group"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:onetrust:Group"
],
"displayName": "Site Admin - Azure AD",
"members": [],
"urn:ietf:params:scim:schemas:onetrust:Group": {
"category": "Azure AD",
"description": "Site Admin has access to this Azure AD"
}
}
]
}
Note that the above response contains the group's groupId which is 444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438.
Step 3: Adding a new role/organization to the user
The PATCH /Groups/{groupId} endpoint can be used to add a user to a group. The user will then get the group's respective Role and Organization.
Example Request:
PATCH /api/scim/v2/Groups/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438 HTTP/1.1
Host: https://trial.onetrust.com
Authorization: Bearer {OAuth_Access_Token}
Content-Type: application/json
Request Body:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "add",
"path": "members",
"value": [
{
"value": "dd525596-f8bb-45d8-83e5-02bbb3c501a1"
}
]
}
]
}
Response Body:
{
"id": "444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
"externalId": null,
"meta": {
"created": "2020-10-08T20:21:05.133+00:00",
"lastModified": "2020-10-08T20:21:05.133+00:00",
"location": "https://trial.onetrust.com/api/scim/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
"resourceType": "Group"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:onetrust:Group"
],
"displayName": "Site Admin - Test Org",
"members": [
{
"value": "dd525596-f8bb-45d8-83e5-02bbb3c501a1",
"type": "User",
"$ref": "https://trial.onetrust.com/api/scim/v2/Users/dd525596-f8bb-45d8-83e5-02bbb3c501a1"
}
],
"urn:ietf:params:scim:schemas:onetrust:Group": {
"category": "Azure AD",
"description": "Site Admin has access to this Test Org"
}
}
Step 4: Remove an existing role/organization from the user
The PATCH /Groups/{groupId} endpoint can be used to remove a user from a group.
Example Request:
PATCH /api/scim/v2/Groups/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438 HTTP/1.1
Host: https://trial.onetrust.com
Authorization: Bearer {OAuth_Access_Token}
Content-Type: application/json
Request Body:
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "remove",
"path": "members",
"value": [
{
"value": "dd525596-f8bb-45d8-83e5-02bbb3c501a1"
}
]
}
]
}
Response Body:
{
"id": "444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
"externalId": null,
"meta": {
"created": "2020-10-08T20:21:05.133+00:00",
"lastModified": "2020-10-08T20:21:05.133+00:00",
"location": "https://trial.onetrust.com/api/scim/444fd8af-e1ee-4742-b1af-94165a8c28c6:6e051cbf-1e3b-4815-8216-50e2a0518438",
"resourceType": "Group"
},
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:Group",
"urn:ietf:params:scim:schemas:onetrust:Group"
],
"displayName": "Site Admin - Test Org",
"members": [],
"urn:ietf:params:scim:schemas:onetrust:Group": {
"category": "Test Org",
"description": "Site Admin has access to this Test Org"
}
}