Skip to content

unifiedrolemanagementpolicyrule-update.md

Latest commit

 

History

History
291 lines (235 loc) · 13.5 KB

unifiedrolemanagementpolicyrule-update.md

File metadata and controls

291 lines (235 loc) · 13.5 KB
title Update unifiedRoleManagementPolicyRule
description Update a rule defined for a role management policy.
author rkarim-ms
ms.localizationpriority medium
ms.subservice entra-id-governance
doc_type apiPageType
ms.date 04/04/2024

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:

[!INCLUDE national-cloud-support]

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

[!INCLUDE rbac-pim-entra-roles-apis]

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

[!INCLUDE table-intro]

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.

HTTP

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": []
    }
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

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.

HTTP

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": []
    }
}

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

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": []
    }
}

Related content