1. Checkbox
  2. Knowledge Base
  3. User Management and Access Controls

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:

  1. Go to Azure Active Directory service
  2. Go to Azure Active Directory > Enterprise Applications.
  3. Click + New Application above the application list.
  4. Enter a Name for the application and click Add.
  5. Under the Manage menu, click Provisioning.
  6. Set Provisioning Mode to Automatic.
  7. Set the SCIM API endpoint URL to https://[ACCOUNT_DOMAIN]/scim/v1 , e.g. https://app.checkbox.ai/scim/v1
  8. 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.
  9. Set Secret Token to token that is provided by Checkbox.
  10. Click Test Connection and wait for the message that confirms that the credentials are authorized to enable provisioning.
  11. Click Save.
  12. 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 supports the following attributes in the Core user schema:

  • userName
  • roles
  • name.givenName
  • name.familyName
  • active

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

  • eq

Supported logical operators:

  • and

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": "2441309d85324e7793ae",
"externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
"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": "5d48a0a8e9f04aa38008",
"externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
"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": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"userName": "lyla@example.net",
"active": true,
"name": {
"familyName": "June",
"givenName": "Lyla"
},
"roles": ["User"]
}

roles:

  • Only the first role in the array will be used, because we support only one role per user at the moment.
  • New role will be created if it is not yet exist.
  • If no roles were specified in the request JSON, we will assign last created role as the default role to the user.

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": "48af03ac28ad4fb88478",
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"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": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"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": "48af03ac28ad4fb88478",
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"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": "6764549bef60420686bc",
"externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
"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