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.

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 in the organization including attributes created.

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.

Role

The user role can be set by utilizing the 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": {
    ...
  }
}

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. Please note that Attributes and Segments that do not exist will be created. If a user is currently belonging to a segment but that segment is not listed when updating, 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	Depends on the selector. 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 (max 255 characters).

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. If a segment is not listed on a user as a manager and the user is currently a manager for that segment, that user will be removed as manager.

Please note the difference between "setting a user as a manager for a segment" vs.  "setting a user's manager in a Users type attribute".  

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

Participate in survey

To disable users from participating in surveys use this.

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