Provisioning with Microsoft Entra ID

You can connect xMatters to Microsoft Entra ID using the "non-gallery application" feature in the Microsoft Entra application gallery. Once connected, Entra runs a synchronization process every 40 minutes that queries the application's SCIM endpoint for assigned users and groups, and creates or modifies them in xMatters as required.

To configure the synchronization application or modify an existing configuration, you must sign into the Microsoft Entra ID admin center as a user with at least Application Administrator permissions.

Create a new application

The first step in connecting xMatters with Entra is to create a new non-gallery application within Entra and configure the connection settings.

  1. In Microsoft Entra ID, select Enterprise application from the left pane to open a list of configured apps. Click New application > Create your own application.
  2. In the Create your own application window, enter a name for the application (e.g., "xMatters SCIM" ), and select the Integrate any other application you don't find in the gallery (Non-gallery) option.
  3. In the app management screen, select Manage > Provisioning from the left menu.
  4. In the Provisioning settings, under Provisioning Mode, select Automatic, and then expand the Admin Credentials settings.
  5. Provide the Tenant URL and the Secret Token in the respective fields.
    1. Tenant URL: The URL of the xMatters SCIM endpoint. For example: https://hostname.xmatters.com/api/xm/1/scim/v2
    2. Secret Token: Follow these instructions to create an xMatters OAuth token using the SCIM specific endpoint.
  6. Click Test Connection to ensure the URL and token are configured correctly, and then click Save.

Set the attribute mappings

The next step is to define how the attributes of user and group objects match to attributes in xMatters. You will need to customize some of the mappings for the synchronization to work properly.

  1. Expand the Mappings section to review the two sets of attribute mappings; one for user objects and one for group objects.
    1. You can choose to disable syncing of group objects by deselecting the groups mapping. We recommend disabling the groups mapping when performing initial tests or configuring your SCIM integration for the first time.
  2. Remove any attributes that are not supported by xMatters. See the list of supported attributes below.
  3. Edit the remaining attribute mappings to ensure the data format will be accepted by xMatters.
  4. Because Entra is not reading in the xMatters schema, you will need to create some attributes manually. To access, enable the Show advanced options check box at the bottom of the attribute mapping screen, and then go to Edit attribute list for customappsso.
  5. Add the following attributes (see the supported attributes table below for correct formatting):
    1. emails
    2. phoneNumbers
    3. roles
  6. Click Save to commit your changes.

Configure the sync settings

Once you have configured the connection and attribute mappings, you can specify the scope and identify the users and groups you want to sync.

  1. Expand the Settings section.
  2. In the Scope field, select Sync only assigned users and groups.
    1. This will sync only the users and groups that you have specified on the Users and groups tab.
  3. Set the Provisioning Status to On, and then click Save.
  4. Click the Users and groups tab and assign the objects you want to sync.
  5. Once the cycle has started, select Provisioning logs in the left panel to monitor sync progress.
    1. The initial cycle may take longer than subsequent syncs, which occur approximately every 40 minutes while the service is running.

xMatters attributes

The following attributes can be included in the attribute mapping configuration. Any attributes not listed here are not supported by xMatters and including them will result in an error (unless the attribute is simply ignored). For example, the xMatters SCIM does not support "EnterpriseUser".

Some of these attributes do not exist in the default Entra schema and must be created manually (specifically, emails, phoneNumbers, and roles), as shown above.

Attribute Notes
userName Must be a unique value for each user resource.
externalId An immutable ID that uniquely identifies the user in Entra ID.
active Boolean
name.givenName  
name.familyName  
preferredLanguage

Must match available languages configured in xMatters, but can be either the two-character code or full name. The recommended Microsoft Entra ID attribute mapping is:

item(Split([preferredLanguage], "-"), 1)
timezone Must match available time zones configured in xMatters.
password A value that must match the configured password policy in xMatters, if enabled.
roles[type eq "Primary"].value The role must match the name of a role in xMatters. These should be defined before syncing.
emails[type ='Work Email'].value

Must be a valid email format. You can include additional email devices; e.g.:

emails[type ='Home Email'].value
phoneNumbers[type ='Work Phone'].value

Phone numbers should be submitted in E.164 format. You can include additional phone numbers; e.g.:

phoneNumbers[type ='Home Phone'].value

We are currently developing an extension to the user resource for xMatters-specific attributes not supported in SCIM by default. This will provide the ability to support custom user properties.

Known issues

Microsoft has published an article (accessible on the Microsoft site here) related to some issues around their compliance to the SCIM 2.0 protocol. xMatters does not have the same compliance issues, but we have made some updates to be more compatible with Entra ID to make integrations easier.