# Microsoft Entra ID

Sync and manage PagerDuty users with Entra ID using SCIM user provisioning

## Configure the SCIM Integration

1. In Microsoft Entra, follow the instructions in [Microsoft’s documentation](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/use-scim-to-provision-users-and-groups#getting-started) 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](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes#editing-user-attribute-mappings):
   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](https://learn.microsoft.com/en-us/entra/identity/app-provisioning/customize-application-attributes#editing-the-list-of-supported-attributes) 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.

![Attribute mapping in Microsoft Entra](/images/kb/32cee17164a121c84ecb90d667487a62fef4373478cccc00620838e0ea84c776-attribute_mapping.png)
*Attribute Mapping in Entra ID*

## 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](/account-admin/advanced-permissions#roles-in-the-rest-api-and-saml):
   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. 

![Entra ID app role form with Display name and Value text inputs](/images/kb/bf4325393462785443c8bb8c92a2f52e3c91262e7beadf40eda831008275ab7a-app_roles.png)
*Display name and Value Fields in Entra ID*

> **Tip:** Reference our [Knowledge Base](/account-admin/advanced-permissions#roles-in-the-rest-api-and-saml) 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"].value`with: 

```
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 API](/developer/api/reference/rest/licenses/list-licenses) to 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"].value`with:

```
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**.