Update unifiedRoleManagementPolicyRule

Namespace: microsoft.graph

Update a rule defined for a role management policy. The rule can be one of the following types that are derived from the unifiedRoleManagementPolicyRule object:

For more information about rules for Microsoft Entra roles and examples of updating rules, see the following articles:

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

Permissions

One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

For PIM for Microsoft Entra roles

Permission type Permissions (from least to most privileged)
Delegated (work or school account) RoleManagementPolicy.ReadWrite.Directory, RoleManagement.ReadWrite.Directory
Delegated (personal Microsoft account) Not supported.
Application RoleManagementPolicy.ReadWrite.Directory, RoleManagement.ReadWrite.Directory

In delegated scenarios with work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role with a supported role permission. The following least privileged roles are supported for this operation.

  • For read operations: Global Reader, Security Operator, Security Reader, Security Administrator, or Privileged Role Administrator
  • For write operations: Privileged Role Administrator

For PIM for groups

Permission type Permissions (from least to most privileged)
Delegated (work or school account) RoleManagementPolicy.ReadWrite.AzureADGroup
Delegated (personal Microsoft account) Not supported.
Application RoleManagementPolicy.ReadWrite.AzureADGroup

HTTP request

To update a rule defined for a policy for either Microsoft Entra roles or groups in PIM:

PATCH /policies/roleManagementPolicies/{unifiedRoleManagementPolicyId}/rules/{unifiedRoleManagementPolicyRuleId}

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

In the request body, supply only the values for properties to update. Existing properties that aren't included in the request body maintain their previous values or are recalculated based on changes to other property values.

The following table specifies the properties that can be updated.

Property Type Description
claimValue String The value of the authentication context claim.

Can be updated for the unifiedRoleManagementPolicyAuthenticationContextRule rule type.
enabledRules String collection The collection of rules that are enabled for this policy rule. For example, MultiFactorAuthentication, Ticketing, and Justification.

Can be updated for the unifiedRoleManagementPolicyEnablementRule rule type.
isDefaultRecipientsEnabled Boolean Indicates whether a default recipient will receive the notification email.

Can be updated for the unifiedRoleManagementPolicyNotificationRule rule type.
isEnabled Boolean Whether this rule is enabled.

Can be updated for the unifiedRoleManagementPolicyAuthenticationContextRule rule type.
isExpirationRequired Boolean Indicates whether expiration is required or if it's a permanently active assignment or eligibility.

Can be updated for the unifiedRoleManagementPolicyExpirationRule rule type.
maximumDuration Duration The maximum duration allowed for eligibility or assignment which is not permanent. Required when isExpirationRequired is true.

Can be updated for the unifiedRoleManagementPolicyExpirationRule rule type.
notificationLevel String The level of notification. The possible values are None, Critical, All.

Can be updated for the unifiedRoleManagementPolicyNotificationRule rule type.
notificationRecipients String collection The list of recipients of the email notifications.

Can be updated for the unifiedRoleManagementPolicyNotificationRule rule type.
notificationType String The type of notification. Only Email is supported.

Can be updated for the unifiedRoleManagementPolicyNotificationRule rule type.
recipientType String The type of recipient of the notification. The possible values are Requestor, Approver, Admin.
Can be updated for the unifiedRoleManagementPolicyNotificationRule rule type.
setting approvalSettings The settings for approval of the role assignment.

Can be updated for the unifiedRoleManagementPolicyApprovalRule rule type.
target unifiedRoleManagementPolicyRuleTarget Defines details of the scope that's targeted by role management policy rule. The details can include the principal type, the role assignment type, and actions affecting a role.

Can be updated for all rule types.

Note: The @odata.type property with a value of the specific rule type must be included in the body. For example, "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyApprovalRule".

Response

If successful, this method returns a 200 OK response code and an unifiedRoleManagementPolicyRule object in the response body.

Examples

Example 1: Update a rule defined for a policy in PIM for Microsoft Entra roles

Request

The following example updates a role management policy rule of type unifiedRoleManagementPolicyExpirationRule and with ID is Expiration_EndUser_Assignment.

PATCH https://graph.microsoft.com/v1.0/policies/roleManagementPolicies/DirectoryRole_84841066-274d-4ec0-a5c1-276be684bdd3_200ec19a-09e7-4e7a-9515-cf1ee64b96f9/rules/Expiration_EndUser_Assignment
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyExpirationRule",
    "id": "Expiration_EndUser_Assignment",
    "isExpirationRequired": true,
    "maximumDuration": "PT1H45M",
    "target": {
        "@odata.type": "microsoft.graph.unifiedRoleManagementPolicyRuleTarget",
        "caller": "EndUser",
        "operations": [
            "All"
        ],
        "level": "Assignment",
        "inheritableSettings": [],
        "enforcedSettings": []
    }
}

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/roleManagementPolicies('DirectoryRole_84841066-274d-4ec0-a5c1-276be684bdd3_200ec19a-09e7-4e7a-9515-cf1ee64b96f9')/rules/$entity",
    "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyExpirationRule",
    "id": "Expiration_EndUser_Assignment",
    "isExpirationRequired": true,
    "maximumDuration": "PT1H45M",
    "target": {
        "caller": "EndUser",
        "operations": [
            "All"
        ],
        "level": "Assignment",
        "inheritableSettings": [],
        "enforcedSettings": []
    }
}

Example 2: Update a rule defined for a policy in PIM for groups

Request

The following example updates a role management policy rule with ID Expiration_EndUser_Assignment.

PATCH https://graph.microsoft.com/v1.0/policies/roleManagementPolicies/Group_60bba733-f09d-49b7-8445-32369aa066b3_f21b26d9-9ff9-4af1-b1d4-bddf28591369/rules/Expiration_EndUser_Assignment
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyExpirationRule",
    "id": "Expiration_EndUser_Assignment",
    "isExpirationRequired": true,
    "maximumDuration": "PT1H45M",
    "target": {
        "caller": "EndUser",
        "operations": [
            "All"
        ],
        "level": "Assignment",
        "inheritableSettings": [],
        "enforcedSettings": []
    }
}

Response

The following example shows the response.

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/roleManagementPolicies('Group_60bba733-f09d-49b7-8445-32369aa066b3_f21b26d9-9ff9-4af1-b1d4-bddf28591369')/rules/$entity",
    "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyExpirationRule",
    "id": "Expiration_EndUser_Assignment",
    "isExpirationRequired": true,
    "maximumDuration": "PT1H45M",
    "target": {
        "caller": "EndUser",
        "operations": [
            "All"
        ],
        "level": "Assignment",
        "inheritableSettings": [],
        "enforcedSettings": []
    }
}