Bewerken

Delen via


Update rules in PIM using Microsoft Graph

The following article provides examples for using Microsoft Graph APIs to update different rules that are assigned to Microsoft Entra roles or groups through Privileged Identity Management (PIM). To understand the structure of rules in PIM, see Working with rules in PIM using Microsoft Graph.

When updating the rules, you must include the @odata.type for the derived type in the request body. For example, to update an activation rule of ID Enablement_EndUser_Assignment, you must include "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyEnablementRule".

If successful, all requests return 204 No Content response codes.

Note

PIM for groups APIs are currently available on the beta endpoint only.

Prerequisites

How to find the settings for a Microsoft Entra role

Consider a Microsoft Entra role like Application Administrator. The permanent immutable template ID for the role in Microsoft Entra ID is 9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3.

To use the PIM APIs to discover the settings for the Application Administrator role, query the role management policy that Microsoft Entra ID has assigned to the role by using the unifiedRoleManagementPolicyAssignment resource type as follows:

GET https://graph.microsoft.com/v1.0/policies/roleManagementPolicyAssignments?$filter=scopeId eq '/' and scopeType eq 'DirectoryRole' and roleDefinitionId eq '9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3'

The response returns an object similar to the following response that contains a policy assignment ID and a policy ID.

Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/roleManagementPolicyAssignments",
    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET policies/roleManagementPolicyAssignments?$select=policyId,roleDefinitionId",
    "value": [
        {
            "id": "DirectoryRole_714a5b9b-97d1-45af-937f-6a998297bc52_0653a6f0-2dca-4655-88fe-b43a086fb66a_9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3",
            "policyId": "DirectoryRole_714a5b9b-97d1-45af-937f-6a998297bc52_0653a6f0-2dca-4655-88fe-b43a086fb66a",
            "scopeId": "/",
            "scopeType": "DirectoryRole",
            "roleDefinitionId": "9b895d92-2cd3-44c7-9d02-a6ac2d5ea5c3"
        }
    ]
}

Use the policyId object to query and manage the corresponding rules for the role.

Example 1: Update the activation maximum duration

PATCH https://graph.microsoft.com/v1.0/policies/roleManagementPolicies/DirectoryRole_38d49456-54d4-455d-a8d6-c383c71e0a6d_59d351b1-e819-4262-b298-236f5f9b1a67/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": []
    }
}

Example 2: Update the justification, MFA, and ticketing rules required on activation

PATCH https://graph.microsoft.com/v1.0/policies/roleManagementPolicies/DirectoryRole_38d49456-54d4-455d-a8d6-c383c71e0a6d_59d351b1-e819-4262-b298-236f5f9b1a67/rules/Enablement_EndUser_Assignment
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyEnablementRule",
    "id": "Enablement_EndUser_Assignment",
    "enabledRules": [
        "Justification",
        "MultiFactorAuthentication",
        "Ticketing"
    ],
    "target": {
        "@odata.type": "microsoft.graph.unifiedRoleManagementPolicyRuleTarget",
        "caller": "EndUser",
        "operations": [
            "All"
        ],
        "level": "Assignment",
        "inheritableSettings": [],
        "enforcedSettings": []
    }
}

Example 3: Require approval to activate

PATCH https://graph.microsoft.com/v1.0/policies/roleManagementPolicies/DirectoryRole_38d49456-54d4-455d-a8d6-c383c71e0a6d_59d351b1-e819-4262-b298-236f5f9b1a67/rules/Approval_EndUser_Assignment
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyApprovalRule",
    "id": "Approval_EndUser_Assignment",
    "target": {
        "@odata.type": "microsoft.graph.unifiedRoleManagementPolicyRuleTarget",
        "caller": "EndUser",
        "operations": [
            "All"
        ],
        "level": "Assignment",
        "inheritableSettings": [],
        "enforcedSettings": []
    },
    "setting": {
        "@odata.type": "microsoft.graph.approvalSettings",
        "isApprovalRequired": true,
        "isApprovalRequiredForExtension": false,
        "isRequestorJustificationRequired": true,
        "approvalMode": "SingleStage",
        "approvalStages": [
            {
                "@odata.type": "microsoft.graph.unifiedApprovalStage",
                "approvalStageTimeOutInDays": 1,
                "isApproverJustificationRequired": true,
                "escalationTimeInMinutes": 0,
                "primaryApprovers": [
                    {
                        "@odata.type": "#microsoft.graph.singleUser",
                        "userId": "10a08e2e-3ea2-4ce0-80cb-d5fdd4b05ea6"
                    },
                    {
                        "@odata.type": "#microsoft.graph.groupMembers",
                        "groupId": "14f2746d-7d6f-4ac6-acd8-8cac318b041b"
                    }
                ],
                "isEscalationEnabled": false,
                "escalationApprovers": []
            }
        ]
    }
}

Example 4: Set expiration of eligible assignment

PATCH https://graph.microsoft.com/v1.0/policies/roleManagementPolicies/DirectoryRole_38d49456-54d4-455d-a8d6-c383c71e0a6d_59d351b1-e819-4262-b298-236f5f9b1a67/rules/Expiration_Admin_Eligibility
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyExpirationRule",
    "id": "Expiration_Admin_Eligibility",
    "isExpirationRequired": true,
    "maximumDuration": "P90D",
    "target": {
        "@odata.type": "microsoft.graph.unifiedRoleManagementPolicyRuleTarget",
        "caller": "Admin",
        "operations": [
            "All"
        ],
        "level": "Eligibility",
        "inheritableSettings": [],
        "enforcedSettings": []
    }
}

Example 5: Set expiration of active assignment

PATCH https://graph.microsoft.com/v1.0/policies/roleManagementPolicies/DirectoryRole_38d49456-54d4-455d-a8d6-c383c71e0a6d_59d351b1-e819-4262-b298-236f5f9b1a67/rules/Expiration_Admin_Assignment
Content-Type: application/json

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

Example 6: Set the justification and MFA requirements for active assignment

PATCH https://graph.microsoft.com/v1.0/policies/roleManagementPolicies/DirectoryRole_38d49456-54d4-455d-a8d6-c383c71e0a6d_59d351b1-e819-4262-b298-236f5f9b1a67/rules/Enablement_Admin_Assignment
Content-Type: application/json

{
    "@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyEnablementRule",
    "id": "Enablement_Admin_Assignment",
    "enabledRules": [
        "Justification",
        "MultiFactorAuthentication"
    ],
    "target": {
        "@odata.type": "microsoft.graph.unifiedRoleManagementPolicyRuleTarget",
        "caller": "Admin",
        "operations": [
            "All"
        ],
        "level": "Assignment",
        "inheritableSettings": [],
        "enforcedSettings": []
    }
}