User Provisioning - SCIM 2.0

Describes how to provision users with SCIM 2.0 from other systems that support it or by the creation of custom integrations

About SCIM 2.0

SCIM stands for "System for Cross-domain Identity Management" (official documentation) and is a protocol to facilitate automatic one-directional provisioning/syncing of users from an identity management system or database to Eletive. The identity management system is called an "identity provider" and Eletive is called a "service provider" within the SCIM protocol. Eletive is kept up-to-date with any system supporting the SCIM 2.0 protocol like Microsoft Azure Active Directory and many others or through custom integrations.

Configuration

In Eletive

• Go to "Setting -> Integrations"
• Select "User Provisioning"
• Press the "Connect" button
• Copy the "SCIM 2.0 URL" and the "Bearer Token" and send it to your IT professional. 
  
  

Identity provider

If an identity provider that supports SCIM 2.0 is used then no custom integration is needed, set up the user provisioning through the identity provider. 

If a custom integration is needed, see the next section.

Custom integration

Operations

The official documentation of SCIM 2.0 should be used for general information, this description will only provide the specifics of Eletives SCIM 2.0 implementation. Eletive supports the following operations in the SCIM 2.0 protocol.

API limitations

• On average 300 requests/min 

Get a specific user

GET /Users/{id}

Returns a user by their unique ID (Eletives), which is received when using the POST operation for example. To get the user by externalID, use "Get all users" instead and use the filter or utilize Eletives ID.

Get all users

GET /Users

Returns all users in Eletive for the organization. Filtering is supported by userName and externalId and by the operator eq. For pagination, see the SCIM 2.0 documentation for startIndex and count. If count is omitted, 1000 is the standard amount. The max count amount is also 1000.

GET /Users?filter=userName eq "firstname.lastname@company.com"
GET /Users?filter=externalId eq "someIdOfUser"

Create a user

POST /Users

Create a new user when providing the following mandatory fields:

Field name	Description	Limit
userName	Primary email of the user (Required if externalId not provided)	Max 255 characters
externalId	The external ID of the user (Required if userName not provided)	Max 255 characters
name.givenName	First name of the user	Max 255 characters
name.familyName	Last name of the user	Max 255 characters

Update a user

PUT /Users/{id}

Use this to update a specific user with data.

Partial update of a user

PATCH /Users/{id}

Makes partial updates to a user. For more information, see the documentation. Example:

{
  "Operations": [
    {
      "op": "replace",
      "path": "userName",
      "value": "firstname.lastname@company.com"
    },
    {
      "op": "replace",
      "path": "externalId",
      "value": "34567"
    },
    {
      "op": "replace",
      "path": "name.familyName",
      "value": "Changed"
    },
    {
      "op": "replace",
      "path": "userType",
      "value": "Users"
    },
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:eletive:2.0:User:NewTestAttributeNumber2",
      "value": 5
    },
    {
      "op": "replace",
      "pat"h: "urn:ietf:params:scim:schemas:extension:eletive:2.0:User:NewTestAttributeNumber3",
      "value": 4
    },
    {
      "op": "remove",
      "path": "urn:ietf:params:scim:schemas:extension:eletive:2.0:User:NewTestAttributeOption3"
    },
    {
      "op": "add",
      "path": "urn:ietf:params:scim:schemas:extension:eletive:2.0:User:manager[attribute eq NewTestAttributeOption].value",
      "value": "test2"
    },
    {
      "op": "remove",
      "path": "urn:ietf:params:scim:schemas:extension:eletive:2.0:User:manager[attribute eq NewTestAttributeOption4 and value eq \"test\"].value"
    },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:eletive:2.0:User:participateInSurvey",
      "value": true
    }
  ]
}

Delete a user

DELETE /Users/{id}

Deletes a specific user.

Get schemas

GET /Schemas

Returns all schemas and fields (including field description) in the organization including attributes created.

There are field dependencies between the following fields: 

userName / emails[primary].value 

When userName is not provided/not an email, there's a fallback on emails[primary].value

particiapteInSurvey / active

When participateInSurvey is not provided, there's a fallback on active

Only one field is required, but if including both fields in your request (e.g. through PUT method), align the values to be equal. 

Role

The user role can be set by utilizing the field userType. Possible values are:

• Administrators
• Analysts
• Superusers
• Users

{
  "userName": "firstname.lastname@company.com",
  ...
  "userType": "Administrators",
  "urn:ietf:params:scim:schemas:extension:eletive:2.0:User": {
    ...
  }
}

Get service provider config

GET /ServiceProviderConfig

Returns the Service Provider configuration of the SCIM 2.0 API containing capabilities and supported features.

Bulk operations

Bulk operations are supported and the documentation can be found here.

Eletive extensions

Eletive has extended the SCIM 2.0 protocol to facilitate more features like Attributes using the format specified here. Use "Get schemas" to fetch more information for your organization.

Attributes

The following input applies depending on the attribute type (see table below). Read more about the different Attribute types here: Types of attributes

Please note that: 1). Attributes and Segments that do not exist will be created. 2). If a user currently belongs to a segment in Eletive but that segment is not listed when updating (when performing/using PUT requests), the user will be removed from that segment.

Attribute type	Input
Choices	A String value (max 255 characters)
Dates	A DateTime string (ISO 8601 format)
Numbers	A Float value
Users	A String value (max 255 characters) Use either email or externalId (both can be used but not necessary). Independent of what selector is used, it should be input as a String value.

Attributes and Segments are provided as a sub-object like this:

{
  ...,
  "urn:ietf:params:scim:schemas:extension:eletive:2.0:User": {
    "ChoicesAttribute": "SegmentName",
    "DatesAttribute": "2019-12-18T16:56:58.000Z",
    "NumbersAttribute": 1.03,
    "UsersAttribute": {
      "email: "firstname.lastname@company.com",
      "externalId": "123456"
    }
  }
}

For Choices type attributes, it is possible to add one SCIM 2.0 alias name for each segment. This is added in Eletive by editing the segment in Eletive, see instructions for editing a segment here: Add, remove and edit attributes and segments under the section "Managing Segments". 

Manager

To set a user as a manager for a specific segment or segments, use our extension. Read more about manager access here: Managers

Please note the difference between:

- "Set a user as a manager for a segment"

vs.

- "Set a user's manager via the Users type attribute" 

The user/manager's segment(s) are provided as an array like this: 

{
  ...,
  "urn:ietf:params:scim:schemas:extension:eletive:2.0:User": {
    "manager": [
      {
        "attribute": "ChoiceAttribute",
        "value": "SegmentName"
      },
      {
        "attribute": "ChoiceAttribute2",
        "value": "SegmentName2"
      }
    ]
  }
}

If a segment is not provided in the array and the user is currently a manager for that segment in Eletive, then the user will be removed as manager. 

Participate in survey

To disable users from participating in surveys use this.

{
  ...,
  "urn:ietf:params:scim:schemas:extension:eletive:2.0:User": {
    "participateInSurvey": false
  }
}