How to set up SCIM User provisioning

Setting up Checkbox user provisioning with SCIM

* These steps assume Azure Active Directory, but the steps should be similar with other providers:

Go to Azure Active Directory service
Go to Azure Active Directory > Enterprise Applications.
Click + New Application above the application list.
Enter a Name for the application and click Add.
Under the Manage menu, click Provisioning.
Set Provisioning Mode to Automatic.
Set the SCIM API endpoint URL to https://[ACCOUNT_DOMAIN]/scim/v1 , e.g. https://app.checkbox.ai/scim/v1
Please note that for single tenant customers, this can just be the registered domain, for multi-tenant, this should point to the WHITELABELLED DOMAIN, which should NOT be empty.
Set Secret Token to token that is provided by Checkbox. (For other providers, this may be referred to as "Bearer Token" or "Authorization" header with "Bearer <token>")
Click Test Connection and wait for the message that confirms that the credentials are authorized to enable provisioning.
Click Save.
Ensure that Users/Groups are added to this application to enable automated provisioning. If all users are desired, then the All Users group must be added.

Checkbox SCIM Endpoints

The Checkbox SCIM API is rate limited at 100 requests/seconds.

We support the following attributes in the Core user schema:

userName
roles
name.givenName
name.familyName
active

We also support the following custom attribute:

externalId

We only take in supported attributes listed above, any other fields will be skipped.

Authentication

Basic auth - To authenticate using Basic Auth mode, you need to provide the username and password for your Checkbox account with Administrator role.

curl https://app.checkbox.ai/scim/v1/Users/{id}
-H "Authorization: Basic {base64 encoded email:password}"

Bearer token - To authenticate using Authorization Header mode, a secret token can be obtained from Checkbox to be included in each request headers

curl https://app.checkbox.ai/scim/v1/Users/{id}
-H "Accept: application/scim+json"
-H "Authorization: Bearer {token}"

Get Users

Request

GET https://app.checkbox.ai/scim/v1/Users?startIndex=0&itemsPerPage=5&filter=userName eq "Test_User_dfeef4c5-5681-4387-b016-bdf221e82081"

Supported fields:

userName
name.familyName
name.givenName
externalId

Supported comparison operators:

Supported logical operators:

Response

HTTP/1.1 200 OK

{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "7fce0092-d52e-4f76-b727-3955bd72c939",
"externalId": "abc123",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "lyla@example.net",
"name": {
"familyName": "June",
"givenName": "Lyla"
},
"active": true,
"roles": ["User"]
}],
"startIndex": 1,
"itemsPerPage": 20
}

Get User

Request

GET https://app.checkbox.ai/scim/v1/Users/{id}

Response

HTTP/1.1 200 OK

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "7fce0092-d52e-4f76-b727-3955bd72c939",
"externalId": "abc123",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "lyla@example.net",
"name": {
"familyName": "June",
"givenName": "Lyla",
},
"active": true,
"roles": ["User"]
}

Create User

Request

POST https://app.checkbox.ai/scim/v1/Users

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"externalId": "abc123",
"userName": "lyla@example.net",
"active": true,
"name": {
"familyName": "June",
"givenName": "Lyla"
},
"roles": ["User"]
}

roles:

Only the first role in the array will be used, the rest will be ignored. Checkbox users can be assigned only 1 application role.
New role will be created if it doesn't exist yet. The newly created role will be created with a blank set of permissions (all permissions unchecked).
If the roles attribute is not specified in the request body, the user will be assigned to the "Default" role in Checkbox.

name:

familyName and givenName are required
but if it is not specified, the user name will become anonymous

Response

HTTP/1.1 201 Created

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "7fce0092-d52e-4f76-b727-3955bd72c939",
"externalId": "abc123",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "lyla@example.net",
"name": {
"familyName": "June",
"givenName": "Lyla"
},
"active": true,
"roles": ["User"]
}

Update User

Request

PUT https://app.checkbox.ai/scim/v1/Users/{id}

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"externalId": "abc123",
"userName": "lyla@example.net",
"active": true,
"name": {
"familyName": "Julia",
"givenName": "Lyla"
},
"roles": ["User"]
}

Response

HTTP/1.1 200 OK

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "7fce0092-d52e-4f76-b727-3955bd72c939",
"externalId": "abc123",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "lyla@example.net",
"name": {
"familyName": "Julia",
"givenName": "Lyla"
},
"active": true,
"roles": ["User"]
}

Patch User

Request

PATCH https://app.checkbox.ai/scim/v1/Users/{id}

{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "replace",
"path": "name.familyName",
"value": "updatedFamilyName"
}
]
}

Response

HTTP/1.1 200 OK

{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "7fce0092-d52e-4f76-b727-3955bd72c939",
"externalId": "abc123",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "lyla@example.net",
"name": {
"familyName": "updatedFamilyName",
"givenName": "Lyla"
},
"active": true
}

Delete User

Request

DELETE https://app.checkbox.ai/scim/v1/Users/{id}

Response

HTTP/1.1 204 No Content