Configure the SCIM Integration

1. In Microsoft Entra, follow the instructions in Microsoft’s documentation to configure a new Microsoft Entra SCIM integration. Create your SCIM app with any name, according to your preferences. Ensure that you select Integrate any other application you don’t find in the gallery.

📘

Disregard Suggested Apps

You may see suggested apps pop up when typing in the name of your application (e.g., the PagerDuty app). Please disregard these suggested apps.

2. Create a new provisioning configuration by entering the following:
   1. Provisioning Mode: Automatic
   2. Tenant URL: https://api.pagerduty.com/scim/v2
   3. API Token: token=<PagerDuty API KEY>
3. Test the connection to ensure that it works, then click Save.
4. Ensure that you’ve only enabled user provisioning/mapping. We do not currently support provisioning groups, so you should disable group attribute mapping.

Configure Provisioning for Entra ID Users

1. Perform the following to update the user attribute mapping:
   1. Enabled: Select Yes.
   2. Target Object Actions: Check the Create, Update and Delete checkboxes.
   3. Attribute Mappings: Define your attribute mappings:
      1. Important: The userName mapping should match the email your users use in PagerDuty to ensure that Microsoft Entra and PagerDuty users get linked correctly.
      2. Ensure the active attribute mapping has the expression Switch([IsSoftDeleted], "true", "False", "true", "True", "false"). Copy this exactly, as it is case-sensitive.
      3. If you’re setting any of the following optional fields via SCIM, edit the attribute list to include the desired attributes:
         1. PagerDuty role creates an attribute mapping: roles[primary eq "True"].value
         2. PagerDuty license creates an attribute mapping: urn:ietf:params:scim:schemas:core:2.0:User:entitlements[type eq "license"].value
         3. Time zone creates an attribute mapping: timezone

🚧

Note

Remove unused fields in your Attribute Mapping list. Provisioning may fail if you have unnecessary fields.

Map Roles

🚧

Note

The following instructions for assigning roles are for guidance only and should be adapted to your organization’s needs. Please only use one of the options provided when configuring roles.

(Option 1) Configure Group-Based Role Mapping

Step 1: Add PagerDuty Roles

By default, new users will be provisioned with the “Manager” role (or your PagerDuty default role).

1. From the Entra Home Screen, go to Manage Entra Microsoft Entra ID, then click View
2. Under Manage on the sidebar, go to App registrations and select your application.
3. Click App roles
4. Create a PagerDuty role:
   1. Fill in the Display name, Value, and Description. The Display name and Value should match.
   2. Ensure Allowed member types is set to Users/Groups.
   3. Select Do you want to enable this app role?
   4. Click Apply.
5. Repeat for remaining roles.

📘

Tip

Reference our Knowledge Base to see how these values map to PagerDuty Role Names,
e.g. Global Admin -> admin

Step 2: Configure Role Mapping

1. From the Attribute mapping screen for your SCIM Enterprise application, click + Add new mapping.
2. Fill in the configuration details as follows:
   1. Mapping type: Expression
   2. Expression: SingleAppRoleAssignment([appRoleAssignments])
   3. Target attribute: roles[primary eq "True"].value
3. Click Save.

Step 3: Assign the Configured Roles to Users/Groups

1. From the Entra Home Screen, go to Manage Entra Microsoft Entra ID and select View.
2. On the sidebar, click Manage > Enterprise Applications.
3. Select your application.
4. On the sidebar under Manage, click User and groups.
5. Click Add user/group.
6. Assign the correct PagerDuty roles to your users/groups.
   1. Under Users and groups, select all the users and groups that should have a specific role and click Select.
   2. Under Select a role , select a PagerDuty role that you previously configured for the selected users/groups.
   3. Click Assign.

(Option 2) Configure Group-Based License and Role Mapping

Alternatively, if you don't want PagerDuty's default license assignment and prefer to manually allocate licenses, you can use this option to configure users via app roles that correspond to specific PagerDuty role and license combinations.

Step 1: Create App roles

1. From the Entra Home Screen, go to Manage Entra Microsoft Entra ID, then click View.
2. Under Manage on the sidebar, go to App registrations and select your application.
3. Click App roles.
4. Create a unique role in the Display name. In this example we will use: PagerDuty Admins (Enterprise Incident Management Full User).
5. Repeat for remaining roles. For this example, we will also create the role: PagerDuty Stakeholders (Enterprise Incident Management Stakeholder).

Step 2: Map the PagerDuty Licenses to role names

Configure the attributes mappings for urn:ietf:params:scim:schemas:core:2.0:User:entitlements[type eq "license"].valuewith:

Switch(
  SingleAppRoleAssignment([appRoleAssignments]),
  "<default_license_id>"
  "PagerDuty Admins (Enterprise Incident Management Full User)", "<full_user_license_id>",
  "PagerDuty Stakeholders (Enterprise Incident Management Stakeholder)", "<stakeholder_license_id>"
)

📘

Tip

Use the List Licenses APIto list the licenses associated with your account.

Step 3: Map the App Roles to the Role Values

Configure the attribute mappings for roles[primary eq "True"].valuewith:

Switch(
  SingleAppRoleAssignment([appRoleAssignments]),
  "<default_role>"
  "PagerDuty Admins (Enterprise Incident Management Full User)", "admin",
  "PagerDuty Stakeholders (Enterprise Incident Management Stakeholder)", "read_only_user"
)

Step 4: Assign the Configured Roles to Users/Groups

Choose the corresponding app role that represents the role and license you want those users/groups to be provisioned with.

1. From the Entra Home Screen, go to Manage Entra Microsoft Entra ID and select View.
2. On the sidebar, click Manage > Enterprise Applications.
3. Select your application.
4. On the sidebar under Manage, click User and groups.
5. Click Add user/group.
6. Assign the configured app role that corresponds to the desired role/license combo to your users/groups.
   1. Under Users and groups, select all the users and groups that should have a specific role and click Select.
   2. Under Select a role , select the app role that you previously configured for the selected users/groups.
   3. Click Assign.