Automated provisioning with SCIM

The System for Cross-Domain Identity Management (SCIM) is a specification designed to automate the management of user identities across cloud-based applications and services. It reduces the cost and complexity of managing users by providing a common user schema and binding documents to provide patterns that allow systems to synchronize data. In short: it makes it fast, cheap, and easy to sync users and groups from your existing management or HR system into xMatters.

SCIM integrations remove the operational and maintenance costs of running custom ETL processes as part of the xMatters EPIC data sync and provide a self-service option to automate provisioning of user identities and group information in xMatters. Unlike the EPIC sync process, these integrations are built specifically for a single identity management system.

  • Microsoft Entra ID (formerly known as Azure Active Directory)
  • Okta

Preparing for a SCIM integration

Provisioning consists of a set of actions between a service provider , such as Entra ID or Okta, and the cloud-based SCIM client, which communicates data about users or groups using REST style architecture and JSON objects to the target system (xMatters). Application developers define the use cases required and build the corresponding SCIM actions into their integrations.

Before configuring your system to integrate with your chosen identify management provider, it's important to plan out your process. The following sections outline some best practices for planning a SCIM integration and cover some basic tasks within xMatters that are required for all deployments that intend to use SCIM auto-provisioning.

Terminology

Throughout our SCIM documentation, we use the following terms and definitions.

  • Source system: The repository of users or identity management system that you're provisioning from. For example Microsoft Entra ID or Okta.
  • Target system: The repository of users that you are syncing to. In this case, the target system is xMatters.
  • CRUD operations: Specific operations that can be taken on users or groups, namely Create, Read, Update, and Delete.

The four CRUD (Create, Read, Update, Delete) operations are the building blocks that combine to provision end-to-end use cases:

  • Create: Creates new users in the target system based on the values of the user profile and group assignments in the source system .
  • Read: Queries information about user and group resources on the target system to match them against existing resources in the source system.
  • Update: Modifies resources in the target system based on changes to data in the source system.
  • Delete: Removes a resource in the target system when the corresponding resource is removed from the source system.

Identify your data requirements

The first task is to understand and document your data requirements. Rarely is a synchronization process as straightforward as "take all of the users in this system and sync them with this system". It's much more likely that you'll want to sync only a subset of users from your source system into xMatters, so start by defining what that subset is, and what properties or attributes exist in the source system that you can use to flag them for inclusion. If you're provisioning the users into groups, you'll also need to understand the group structure within your source system and how it compares to the group structure within xMatters.

Most provisioning services can be deployed in both "green field" scenarios, where users don't exist in the target system, and "brown field" scenarios, where the users are already configured in the target system. To support both scenarios, provisioning services use the concept of matching attributes, which allow you to determine how to uniquely identify a user or group in the source system and match them to their corresponding records in the target system. As part of planning your deployment, identify the attribute that can uniquely identify a user in both the source and target systems.

Scope users or groups for provisioning

You can use scoping filters to prevent objects in applications from being provisioned if an object doesn't satisfy your business requirements. A scoping filter allows you to include or exclude any users or groups that have an attribute that matches a specific value. For example, when provisioning users from a source system to a SaaS application used by an operations team, you can specify that only users with a "Department" attribute of "Ops" should be in scope for provisioning.

The more users and groups that you have in scope for provisioning, the longer the synchronization process can take. Setting the scope to sync only specific users and groups, limiting the number of groups assigned to the app, and limiting the size of the groups will reduce the time it takes to sync data across the systems.

Some source systems offer additional methods of determining which users are in scope. For example, Microsoft Entra ID allows you to assign specific users and groups to a synchronization list and only those assignments will be synchronized, eliminating the need for filters.

To prevent users from changing specific values or modifying their user profiles after the sync, you can specify external ownership using the External Data page.

Create a SCIM user and any necessary tokens

We recommend creating a specific set of integration or synchronization user credentials for this process. If you use a regular user and that user leaves the company, you will need to reconfigure all of your Basic authentication or OAuth settings within your provisioning configuration.

To ensure secure synchronization processes, some SCIM integrations with xMatters use OAuth authentication and SCIM-specific secret tokens. The process for creating these tokens is the same as the steps used to create a normal OAuth token in xMatters, but targets a different endpoint reserved for SCIM implementations.

To generate a SCIM OAuth token:
  1. Log into your xMatters instance using the credentials you want to use when generating the token.
  2. Navigate to Workflows > OAuth.
  3. In the Obtain an access token and refresh token section, copy the cURL command to a text editor and replace the URL at the end of the command with the SCIM specific endpoint.
    1. I.e., replace 'https://<hostname>.xmatters.com/api/xm/1/oauth2/token' with 'https://<hostname>.xmatters.com/api/xm/1/scim/v2/tokens'
  4. Use the modified cURL command when obtaining or refreshing your OAuth token for all SCIM operations.

Note that the SCIM endpoint ends in tokens — with an "s" — not token.

Run a pilot

Always test your implementation using a test environment or a sandbox before attempting to run it against production. Running a pilot also allows you to start small: try synchronizing a subset of users or a single focus group first, and then expand slowly.