SCIM integration

🔗 SCIM (System for Cross-domain Identity Management) is an open standard for automating the exchange of user identity information between identity domains and IT systems. It defines a common schema for users and groups, and a REST protocol for managing them:

• 🔗 RFC7643 - SCIM: Core Schema
• 🔗 RFC7644 - SCIM: Protocol

Drillster SCIM integration

Drillster supports SCIM 2.0 and you can reach the server via the URL https://www.drillster.com/connector/scim/v2/. The SCIM server allows only authenticated calls, and you cannot use the same credentials for it as for the rest of the Drillster REST API. See the next section for more information about requesting server access.

Currently, Drillster supports only the SCIM user resource, so no groups. It allows all the CRUD operations on users, including updates via PATCH. In addition, a client can also request a paginated list of users with optional filtering by working email, externalId, or userName.

Our server also exposes the standard SCIM discovery endpoints where a client can check details of our implementation:

• Supported resource types
• Supported schemas
• Supported SCIM features

Prerequisites

Client configuration

To connect to the Drillster SCIM server, you should use a SCIM 2.0-compatible client. The main configuration items for the client are the server's URL and the credentials.

URL

The base URL should be set to https://www.drillster.com/connector/scim/v2/

Credentials

The Drillster SCIM server supports authentication via a long-lived bearer token. Please be aware that if you already have another integration with Drillster, you cannot reuse its credentials for the SCIM server. The opposite is also true: you can use the bearer token only for SCIM requests.

You can obtain a bearer token by contacting Drillster.

Other client configurations

The other configuration items could be attribute mapping, scope, capabilities, etc. These are all client-specific, and you should reference the documentation of your client for configuring them. Often, a big chunk of the configuration can be done automatically by utilizing the SCIM discovery endpoints. For instance, a SCIM client can define the scope of supported attributes by checking the user schema on the server (the /v2/Schemas endpoint), and suggest mapping options only for the attributes defined in the schema.

Third parties and existing user migration

The SCIM user schema contains two attributes that are mapped to third-party IDs on the Drillster side:

• userName - a mandatory attribute, usually represents a login name.
• externalId - an optional attribute, usually an ID in your system.

When you create a new user via SCIM, the resulting Drillster account will contain third party IDs for these two attributes. Then on a retrieval of this user, the third party IDs will be mapped back to the attributes. However, it will be impossible to retrieve the old existing users created not via SCIM because they lack of a third party ID derived from mandatory userName.

Therefore, you need to make a choice about supporting the existing users via SCIM:

• We don't make them available via SCIM. At this case, no additional actions needed.
• We make them available via SCIM. At this case, Drillster should extend the existing accounts with the third party IDs using either values provided by you or the existing account's properties.

Server configuration

On the server side, Drillster will do the following:

• Configure the bearer token for the SCIM server.
• Register a service account with admin rights for your organization. This server account will perform user management operations requested via SCIM.
• Register the third parties for userName and externalId.
• Extend the existing accounts with third party IDs for userName and externalId, if it's necessary.

Frequently asked questions

Does Drillster perform a soft-delete on users?

No, Drillster permanently deletes users. So deleted users cannot appear in the paginated user list, and they also cannot be restored.

How can you specify the admin role for a user?

You can make a user your organization's admin in Drillster via the roles attribute of the SCIM user schema. This is a multi-valued attribute (i.e. an array) with objects as the elements. To grant the admin role, a client should add to this array an object with a single attribute-value pair value: ADMIN. To remove a user from admins, make the array empty.