Require approval for a PIM role

This lab uses User Administrator, whose template ID is fe930be7-5e62-47db-91af-98c3a49a38b1 in every tenant. It's privileged enough to deserve approval but won't lock anyone out if you get a setting wrong. You need a requester (pim.requester) and an approver (pim.approver). The approver doesn't need any admin role, and nobody can approve their own request.

1
2
3
4Connect-MgGraph -Scopes "RoleEligibilitySchedule.ReadWrite.Directory","RoleManagementPolicy.Read.Directory","User.Read.All"
$roleId    = "fe930be7-5e62-47db-91af-98c3a49a38b1"
$requester = Get-MgUser -UserId "pim.requester@contoso.com"
$approver  = Get-MgUser -UserId "pim.approver@contoso.com"

In the Microsoft Entra admin center, go to ID Governance → Privileged Identity Management → Microsoft Entra roles → Roles, select Add assignments, pick the role and the requester, and select Next. Set Assignment type to Eligible, give it an end date, and select Assign.

Or with Graph PowerShell, which creates an eligibility schedule request with the action adminAssign:

1
2
3
4
5
6
7
8
9
10
11
12$params = @{
  Action           = "adminAssign"
  Justification    = "PIM approval lab"
  RoleDefinitionId = $roleId
  DirectoryScopeId = "/"
  PrincipalId      = $requester.Id
  ScheduleInfo     = @{
    StartDateTime = Get-Date
    Expiration    = @{ Type = "AfterDuration"; Duration = "P90D" }
  }
}
New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest -BodyParameter $params

The duration has to fit the role's Assignment settings. By default eligible assignments can't run longer than a year, so a request for longer is rejected.

Go to Microsoft Entra roles → Roles, select User Administrator, then Role settings → Edit. On the Activation tab:

Activation maximum duration: 2 hours. The range is 1 to 24.

On activation, require: multifactor authentication, or a Conditional Access authentication context if you've set one up.

Require justification on activation: ticked. Tick Require ticket information on activation too if you want a change or incident number, though PIM doesn't check it against your ticketing system.

Require approval to activate: ticked, then select approvers and add pim.approver. Microsoft recommends at least two approvers in production so one person's leave doesn't block everyone.

Select Update.

If you require approval without naming approvers, active Privileged Role Administrators and Global Administrators become the approvers. Do that on Global Administrator while every admin is only eligible and you can lock yourself out, which is why the break-glass accounts matter.

Graph calls role settings "rules", grouped in a policy that's attached to each role. Reading the approval rule back is a quick way to confirm the change, and it's the same structure you'd write with Update-MgPolicyRoleManagementPolicyRule to automate this.

1
2
3
4$pa = Get-MgPolicyRoleManagementPolicyAssignment -Filter "scopeId eq '/' and scopeType eq 'DirectoryRole' and roleDefinitionId eq '$roleId'"
Get-MgPolicyRoleManagementPolicyRule -UnifiedRoleManagementPolicyId $pa.PolicyId `
  -UnifiedRoleManagementPolicyRuleId "Approval_EndUser_Assignment" |
  Select-Object -ExpandProperty AdditionalProperties | ConvertTo-Json -Depth 8

Look for isApprovalRequired set to true and the approver's ID under primaryApprovers. The justification and MFA requirements are in the rule Enablement_EndUser_Assignment.

In a private browser window, sign in as the requester and go to ID Governance → Privileged Identity Management → My roles → Microsoft Entra roles. Select Activate next to User Administrator, complete MFA if asked, set a duration, enter a Reason and select Activate. A notification says the request is pending approval.

The same request from PowerShell, signed in as the requester, is an assignment schedule request with the action selfActivate. The status that comes back should be PendingApproval:

1
2
3
4
5
6
7
8
9
10Connect-MgGraph -Scopes "RoleAssignmentSchedule.ReadWrite.Directory"
$me = Get-MgUser -UserId (Get-MgContext).Account
New-MgRoleManagementDirectoryRoleAssignmentScheduleRequest -BodyParameter @{
  Action           = "selfActivate"
  PrincipalId      = $me.Id
  RoleDefinitionId = "fe930be7-5e62-47db-91af-98c3a49a38b1"
  DirectoryScopeId = "/"
  Justification    = "Lab: reset a test user's password"
  ScheduleInfo     = @{ StartDateTime = Get-Date; Expiration = @{ Type = "AfterDuration"; Duration = "PT1H" } }
} | Select-Object Status, CreatedDateTime

Only send one of the two. A second request for the same role while one is pending is likely to be rejected.

The approver gets an email. Signed in as the approver, go to ID Governance → Privileged Identity Management → Approve requests. Under Requests for role activations, select the request, read the requester's reason, enter your own justification and approve it. Approvers have 24 hours; after that the request expires and the requester has to ask again. The 24 hours can't be changed.

Approving through Graph uses the roleAssignmentApprovals API, which is only on the beta endpoint, so stick to the portal for now.

Back as the requester, the role now shows on the Active assignments tab of My roles. From PowerShell:

1
2Get-MgRoleManagementDirectoryRoleAssignmentScheduleInstance -Filter "principalId eq '$($me.Id)'" |
  Select-Object RoleDefinitionId, AssignmentType, StartDateTime, EndDateTime

AssignmentType is Activated for a PIM activation. When you're done, select Deactivate in My roles, or send the same request with the action selfDeactivate. You can't deactivate in the first five minutes after activation.

Go to Privileged Identity Management → Microsoft Entra roles → Resource audit to see the eligibility you created, the settings change, the request, the approval and the activation. My audit shows just your own actions. PIM keeps 30 days here; to keep longer, send the Entra audit logs to Log Analytics with a diagnostic setting and query them:

1
2
3
4
5
6
7AuditLogs
| where TimeGenerated > ago(7d)
| where OperationName has "Add member to role"
| project TimeGenerated, OperationName, Result,
          By = tostring(InitiatedBy.user.userPrincipalName),
          Role = tostring(TargetResources[0].displayName)
| order by TimeGenerated desc

One activation produces several events, and they don't always share a correlation ID. To tie them together, use the roleAssignmentRequestId in each event's additional details.

Sign back in as the administrator from step 1 and remove the eligibility with the action adminRemove. An assignment can't be removed in the first five minutes after it was created. Then turn approval back off in the role settings if this was a production tenant you were testing in.

1
2
3
4
5
6
7Connect-MgGraph -Scopes "RoleEligibilitySchedule.ReadWrite.Directory"
New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest -BodyParameter @{
  Action           = "adminRemove"
  RoleDefinitionId = "fe930be7-5e62-47db-91af-98c3a49a38b1"
  DirectoryScopeId = "/"
  PrincipalId      = $requester.Id
}

For real roles, write down who approves each one and review that list when people change jobs. An approver who has left is the most common reason PIM requests sit unanswered.