Provision and manage user accounts and groups with the Elimity SCIM API using version 2.0 of the SCIM protocol.

Manage users in your Elimity Insights deployment or tenant

SCIM is an HTTP REST API and protocol used by identity providers to manage the users across a variety of tools, including Elimity Insights. This SCIM implementation targets version 2.0 of the protocol. 

Important: Be aware that the SCIM API allows creating and deleting users at will. Hence, thoroughly protect your API keys to avoid that unauthorized people make themselves admin and access your data. Similarly, thoroughly test your scripts before executing them to avoid deprovisioning all users in your tenant. Of course, our support team is ready to assist you should you run into any trouble.

Accessing the SCIM API 

Like other Elimity Insights APIs, the SCIM methods are accessed over HTTP. 

The base URL for all calls to the Elimity Insights SCIM API is https://<yourdomain>/scim/v2/. All SCIM methods are branches of this base URL.

Configuring authentication for the SCIM API

The SCIM API of Elimity Insights requires authentication using a bearer token (HTTP Bearer Authentication). As such, the client must send this token in the Authorization header when making requests to protected resources:

Authorization: Bearer <token>

The bearer token is configured using the following configuration parameter in your secrets.yml file:

# ScimPassword
# ----------------------------
#
# Data type: string
#
# Status: Required
#
# Description: The bearer token to be used for HTTP authentication for the SCIM interface.
ScimPassword: YourSuperSecureScimBearerToken

If you don't want to use the SCIM API of your Elimity Insights deployment, set the SCIM bearer token to a long and random string.

Elimity Insights roles and access profiles vs SCIM groups

Elimity Insights works with two authorization concepts:

1. Roles like member, editor, connector admin and admin determine the functionality that user can access.
2. Access profiles determine which data sources a user is permitted to see.

A user in Elimity Insights is always assigned to exactly 1 role, to the default access profile and to 0 or more custom access profiles.

SCIM on the other hand works with the concept of groups and Elimity Insights models roles and access profiles as groups in the following manner:

• Roles are modeled as groups with an id in the format of:
  • role:member
  • role:editor 
  • role:connectorAdmin
  • role:admin
• Access profiles are modeled as groups with an id in the format of profile:1 with the number representing the id of the access profile. You can find this id in the URL of the details page of an access profile in Elimity Insights.
• The default access profile is not listed in the SCIM API and cannot be assigned or revoked explicitly.

SCIM API endpoints

Overview

The table below lists the endpoints supported by the SCIM API of Elimity Insights. See the sections below for important remarks regarding creating users, deactivating users and assigning/revoking groups.

All details of these endpoints can be found in the Postman collection attached to this article (see bottom of the page).

The following standard endpoints are intentionally not supported by Elimity Insights:

• DELETE /scim/v2/Users/<id>: Elimity Insights does not support deleting users, only deactivating them. If you want to prohibit a user from logging in to Elimity Insights, you can use the PUT method to set the user to inactive (see below).
• PATCH /scim/v2/Users/<id>
• POST /scim/v2/Groups: Elimity Insights only supports creating new access profiles from the UI, not through the SCIM API.
• DELETE /scim/v2/Groups/<id>: Elimity Insights only supports deleting access profiles from the UI, not through the SCIM API.
• PATCH /scim/v2/Groups/<id>

Creating a new user

Endpoint:

POST /scim/v2/Users

Body: 

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"someone@example.com",
  "emails": [{}]
}

Notes:

• Only the field userName matters, which should be a valid email address. All other fields are ignored.
• The endpoint returns 400 if the given username is taken or not a valid email address.
• The resulting user will still be marked inactive. A user will only become active after the invite has been accepted.

Result: Calling this endpoint behaves similarly to inviting a new user in the admin UI of Elimity Insights. This means that calling this endpoint will result in a new user being invited to Elimity Insights. This user will have the role member. Upon creation, Elimity Insights will send an invite email to this user and the user can complete his or her profile (first name, last name, password in case of password authentication) when he or she first logs in. 

Updating a user

Endpoint:

PUT /scim/v2/Users/<id>

Body: 

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "name":{
    "familyName":"new family name",
    "givenName":"new given name"
  },
  "active": true
}

Notes:

• The only fields of a user that can be update are: givenName, familyName and active.

Result: The given name, family name and active flag of the specified user are updated to the specified values. If active was false, the user will not be able to log in any more.

Deactivating a user

To deactivate a user, update the user as explained above with active set to false.

Changing the members of a group

To add users to groups or to revoke users from groups, you can specify the new members list when updating that group.

Endpoint:

PUT /scim/v2/Group/<id>

Body: 

{
  "displayName": "",
  "id": "",
  "members": [
    {
      "value": "demo@elimity.com"
    }
  ] 
}

Notes:

• The fields displayName and id are required in the body, but are ignored. 

Result: The list of members of the given group will be updated. More specifically:

• If the given group represents a role, that role will be assigned to all users and invites that match one of the given email addresses. All other users and invites that were assigned to this role before are now given the role member.
• If the given group represents an access profile, that access profile will be assigned to all users and invites that match one of the given email addresses. All other users and invites that were assigned to this access profile before are now removed from this access profile.