Get unifiedRoleManagementPolicyAssignment
Namespace: microsoft.graph
Get the details of a policy assignment in PIM that's assigned to Microsoft Entra roles or group membership or ownership.
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.Read.Directory, RoleManagement.Read.Directory, RoleManagement.Read.All, RoleManagementPolicy.ReadWrite.Directory, RoleManagement.ReadWrite.Directory |
Delegated (personal Microsoft account) | Not supported. |
Application | RoleManagementPolicy.Read.Directory, RoleManagement.Read.Directory, RoleManagement.Read.All, RoleManagementPolicy.ReadWrite.Directory, RoleManagement.ReadWrite.Directory |
Important
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.Read.AzureADGroup, RoleManagementPolicy.ReadWrite.AzureADGroup |
Delegated (personal Microsoft account) | Not supported. |
Application | RoleManagementPolicy.Read.AzureADGroup, RoleManagementPolicy.ReadWrite.AzureADGroup |
HTTP request
To retrieve the details of a policy assignment made in PIM for Microsoft Entra roles or PIM for groups membership and ownership:
GET /policies/roleManagementPolicyAssignments/{unifiedRoleManagementPolicyAssignmentId}
Optional query parameters
This method supports the $select
and $expand
OData query parameters to help customize the response. You can also specify the wildcard value *
to expand all supported relationships, that is, ?$expand=*
. For general information, see OData query parameters.
Request headers
Name | Description |
---|---|
Authorization | Bearer {token}. Required. Learn more about authentication and authorization. |
Request body
Don't supply a request body for this method.
Response
If successful, this method returns a 200 OK
response code and an unifiedRoleManagementPolicyAssignment object in the response body.
Examples
Example 1: RRetrieve the details of a policy assignment for PIM for Microsoft Entra roles
Request
GET https://graph.microsoft.com/v1.0/policies/roleManagementPolicyAssignments/Directory_cab01047-8ad9-4792-8e42-569340767f1b_70c808b5-0d35-4863-a0ba-07888e99d448_62e90394-69f5-4237-9190-012177145e10
Response
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/roleManagementPolicyAssignments/$entity",
"id": "Directory_cab01047-8ad9-4792-8e42-569340767f1b_70c808b5-0d35-4863-a0ba-07888e99d448_62e90394-69f5-4237-9190-012177145e10",
"policyId": "Directory_cab01047-8ad9-4792-8e42-569340767f1b_70c808b5-0d35-4863-a0ba-07888e99d448",
"scopeId": "/",
"scopeType": "Directory",
"roleDefinitionId": "62e90394-69f5-4237-9190-012177145e10"
}
Example 2: Retrieve the details of a policy assignment for PIM for Microsoft Entra roles and expand the policy and its associated rules
Request
GET https://graph.microsoft.com/v1.0/policies/roleManagementPolicyAssignments/Directory_cab01047-8ad9-4792-8e42-569340767f1b_70c808b5-0d35-4863-a0ba-07888e99d448_62e90394-69f5-4237-9190-012177145e10?$expand=policy($expand=rules)
Response
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/roleManagementPolicyAssignments(policy(rules()))/$entity",
"id": "Directory_cab01047-8ad9-4792-8e42-569340767f1b_70c808b5-0d35-4863-a0ba-07888e99d448_62e90394-69f5-4237-9190-012177145e10",
"policyId": "Directory_cab01047-8ad9-4792-8e42-569340767f1b_70c808b5-0d35-4863-a0ba-07888e99d448",
"scopeId": "/",
"scopeType": "Directory",
"roleDefinitionId": "62e90394-69f5-4237-9190-012177145e10",
"policy": {
"id": "Directory_cab01047-8ad9-4792-8e42-569340767f1b_70c808b5-0d35-4863-a0ba-07888e99d448",
"displayName": "Directory",
"description": "Directory",
"isOrganizationDefault": false,
"scopeId": "/",
"scopeType": "Directory",
"lastModifiedDateTime": null,
"lastModifiedBy": {
"displayName": null,
"id": null
},
"rules": [
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyExpirationRule",
"id": "Expiration_Admin_Eligibility",
"isExpirationRequired": false,
"maximumDuration": "P365D",
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Eligibility",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyEnablementRule",
"id": "Enablement_Admin_Eligibility",
"enabledRules": [],
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Eligibility",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Admin_Admin_Eligibility",
"notificationType": "Email",
"recipientType": "Admin",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Eligibility",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Requestor_Admin_Eligibility",
"notificationType": "Email",
"recipientType": "Requestor",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Eligibility",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Approver_Admin_Eligibility",
"notificationType": "Email",
"recipientType": "Approver",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Eligibility",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyExpirationRule",
"id": "Expiration_Admin_Assignment",
"isExpirationRequired": false,
"maximumDuration": "P180D",
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyEnablementRule",
"id": "Enablement_Admin_Assignment",
"enabledRules": [
"Justification"
],
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Admin_Admin_Assignment",
"notificationType": "Email",
"recipientType": "Admin",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Requestor_Admin_Assignment",
"notificationType": "Email",
"recipientType": "Requestor",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Approver_Admin_Assignment",
"notificationType": "Email",
"recipientType": "Approver",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "Admin",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyExpirationRule",
"id": "Expiration_EndUser_Assignment",
"isExpirationRequired": true,
"maximumDuration": "PT8H",
"target": {
"caller": "EndUser",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyEnablementRule",
"id": "Enablement_EndUser_Assignment",
"enabledRules": [
"MultiFactorAuthentication",
"Justification"
],
"target": {
"caller": "EndUser",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyApprovalRule",
"id": "Approval_EndUser_Assignment",
"target": {
"caller": "EndUser",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
},
"setting": {
"isApprovalRequired": false,
"isApprovalRequiredForExtension": false,
"isRequestorJustificationRequired": true,
"approvalMode": "SingleStage",
"approvalStages": [
{
"approvalStageTimeOutInDays": 1,
"isApproverJustificationRequired": true,
"escalationTimeInMinutes": 0,
"isEscalationEnabled": false,
"primaryApprovers": [],
"escalationApprovers": []
}
]
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyAuthenticationContextRule",
"id": "AuthenticationContext_EndUser_Assignment",
"isEnabled": false,
"claimValue": null,
"target": {
"caller": "EndUser",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Admin_EndUser_Assignment",
"notificationType": "Email",
"recipientType": "Admin",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "EndUser",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Requestor_EndUser_Assignment",
"notificationType": "Email",
"recipientType": "Requestor",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "EndUser",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
},
{
"@odata.type": "#microsoft.graph.unifiedRoleManagementPolicyNotificationRule",
"id": "Notification_Approver_EndUser_Assignment",
"notificationType": "Email",
"recipientType": "Approver",
"notificationLevel": "All",
"isDefaultRecipientsEnabled": true,
"notificationRecipients": [],
"target": {
"caller": "EndUser",
"operations": [
"all"
],
"level": "Assignment",
"inheritableSettings": [],
"enforcedSettings": []
}
}
]
}
}
Example 3: Retrieve the details of a policy assignment for PIM for groups
Request
The following example shows a request.
GET https://graph.microsoft.com/beta/policies/roleManagementPolicyAssignments/Group_60bba733-f09d-49b7-8445-32369aa066b3_f21b26d9-9ff9-4af1-b1d4-bddf28591369_member
Response
The following example shows the response.
Note: The response object shown here might be shortened for readability.
HTTP/1.1 200 OK
Content-Type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#policies/roleManagementPolicyAssignments/$entity",
"id": "Group_60bba733-f09d-49b7-8445-32369aa066b3_f21b26d9-9ff9-4af1-b1d4-bddf28591369_member",
"policyId": "Group_60bba733-f09d-49b7-8445-32369aa066b3_f21b26d9-9ff9-4af1-b1d4-bddf28591369",
"scopeId": "60bba733-f09d-49b7-8445-32369aa066b3",
"scopeType": "Group",
"roleDefinitionId": "member"
}