SCIM: User Provisioning

What is SCIM?

SCIM, or System for Cross-domain Identity Management, is an open standard that allows for the automation of user provisioning. It makes it easy to add, update or remove users across different applications simultaneously. The solution is built using the SCIM 2.0 specification.

How to use SCIM with Scoro?
SCIM can be set up in two different ways:

1. SCIM API solution
   - Build your own user provisioning process with the Scoro SCIM API
   - Read more about it in the “API documentation” section
2. Custom SCIM integration with the existing solutions of various identity providers (IdP)
   Here are the main IdPs that our solution currently supports and the respective instructions:
   - User provisioning with Microsoft Entra ID
   - User provisioning with Okta
   - User provisioning with OneLogin

How to configure SCIM in Scoro?

SCIM is available with the Ultimate package.

1. SCIM settings can be found under Settings → Integrations → SCIM
2. Admin users can set the default values for new users created via SCIM:
   
   - Default entity (only available in case of multiple entities)
   - Default user type
   - Email notification with account data
3. In order to enable the SCIM API, you must generate an OAuth bearer token
4. Once SCIM is enabled, the API credentials will allow you to use:
   
   - SCIM REST API
   - Custom SCIM integration with IdP-s
5. Detailed instructions about how to use the SCIM API can be found in the next paragraph

API documentation

General information

All requests sent to the SCIM API have to use the following:

• company base URL - https://#sitename.scoro.com/scim/v2

• bearer token - can be generated in the SCIM settings

The bearer token must be added to the request via the Authorization header with Bearer type for all requests.

GET /scim/v2/Users
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

User fields

Scoro SCIM API is built on top of the SCIM core “user” schema. This means that Scoro doesn’t support fields that are not included in the core schema. Some of the fields are read-only, which means that Scoro will return these fields in the response, but doesn’t allow to add or modify them.

Here is a list of all the supported fields and the general rules for these fields between Scoro and the SCIM API:

Available requests

Below is a list of all the available requests that the Scoro SCIM API supports.

GET /Users

This request will return a paginated list of users with 100 itemsPerPage by default. It is also possible to filter by username with the exact match operator (“eq”). All other query parameters, apart from pagination and filtering, are ignored.

Pagination

In order to use pagination, the request must include the following:

1. startIndex (default value = 1)
   
   - 1-based index of the first query result (the first user is 1, not 0)
   - A value less than 1 is interpreted as 1
2. count (default & max value = 100)
   
   - Non-negative integer. Specifies the desired number of query results per page, for example: 10
   - A negative value is interpreted as 0
   - A value of 0 indicates that no resource results are to be returned, except for total results

Read more about SCIM pagination.

GET /scim/v2/Users?count=10&startIndex=21
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

Filtering

In order to use filtering, the request must include the following:

1. filter
   
   - Users can be filtered by “userName” only
   - All the other filters will receive an error
2. operator
   
   - Users can be filtered by operator “eq” only
   - All the other operators will receive an error

GET /scim/v2/Users?count=10&startIndex=21
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

GET /Users/#id

This request will return a single specified user from Scoro with the given Scoro user ID. The Scoro user ID can be obtained from the list request by filtering it with the unique “userName” value.

GET /scim/v2/Users/823
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

POST /Users

This request will create a new user in Scoro. In order to create a new user, the request must have the following mandatory fields filled:

• userName

• first name

• active

Other fields that are not mandatory but are filled with data when not provided by request:

• userType - default value is “user”

• email - default value is taken from “userName”

Other fields and their general rules are listed in the “User fields” table.

If there are not enough licenses available in Scoro, the system will return error 409, stating that there are not enough licenses. If a user with the same userName or email already exists in Scoro, the system will return a 409 error about uniqueness. Successful user creation will return 201.

Note: All read-only and unknown fields added with the request are ignored!

POST /scim/v2/Users
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
   "userName": "myemail@mycompany.com",
   "name": {
       "givenName": "Test",
       "familyName": "User"
   },
   "emails": [{
       "value": "myemail@mycompany.com",
       "primary": true,
       "type": "work" 
   }],
   "phoneNumbers": [{
       "value": "256-591-8363",
       "primary": true,
       "type": "work" 
   }],
   "title": "Tester",
   "userType": "admin",
   "active": true
}

PUT /Users/#id

This request will update the whole user object by replacing all the values that are listed in the “User fields” table. If no value is provided with the request, then it will write it empty if possible, otherwise, it will return an error. Therefore, it is important to send all the user fields when using a PUT request.

Note: All read-only and unknown fields added with the request are ignored!

PUT /scim/v2/Users/32142144543532
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

{
   "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
   "userName": "myemail@mycompany.com",
   "name": {
       "givenName": "Test",
       "familyName": "User"
   },
   "emails": [{
       "value": "myemail@mycompany.com",
       "primary": true,
       "type": "work" 
   }],
   "phoneNumbers": [{
       "value": "256-591-8363",
       "primary": true,
       "type": "work" 
   }],
   "title": "Tester",
   "userType": "admin",
   "active": true
}

PATCH /Users/#id

This request allows updating only the attributes of a specific user, provided with the request, without modifying all the other attributes. Available operations are “add”, “replace” or “delete”.

Both “add” and “replace” require “path” and “value” in order to update the value. There are two ways to add “path” and “value”, both are shown in Example 1 and Example 2 below. If one of these values is not provided, the update will be ignored. “Remove” requires only “path” in order to remove the value.

Note: All read-only and unknown fields added with the request are ignored!

Example 1:

PATCH /scim/v2/Users/32142144543532
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":[{
            "op":"replace",
            "value":{
                "active":false
            }
    }]
}

Example 2:

PATCH /scim/v2/Users/32142144543532
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":[{
            "op":"replace",
            "path":"active",
            "value": True
    }]
}

Multi-values can be updated by using filtering for “path”. Only “work” type can be used for filtering since Scoro allows to add only one email and one mobile number via SCIM.

{
    "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations":[
        {
            "op":"add",
            "path": "emails[type eq "work"].value",
            "value":"myname@gmycompany.com"
                
        }
    ]
}

DELETE /Users/#id

This request will deactivate the user in Scoro. It will not delete the user from Scoro and the user can be reactivated at any time by updating the active value to “true” with PUT or PATCH.

DELETE /scim/v2/Users/32142144543532
Host: #sitename.scoro.com
Content-Type: application/scim
Authorization: Bearer eyJ0e...

Common errors