Manage PIM Role Assignments with the Microsoft Graph PowerShell SDK

Add Eligible and Active PIM Role Assignment Requests

I recently wrote about Microsoft’s recommendation to use the UnifiedRoleDefinition Graph API instead of the older DirectoryRole API. In that article, I show how to use the Microsoft Graph PowerShell SDK to make role assignments to user accounts. Assignments made in this manner are effective immediately. The assignments are permanent and last until an administrator removes them from accounts.

In many Microsoft 365 tenants where a limited set of administrators run operations, permanent role assignments work well. However, in larger tenants, some additional control is often desirable. Microsoft’s answer is Entra ID Privileged Identity Management (PIM), designed to enable administrators “manage, control, and monitor access to important resources in your organization.” PIM assignments can be permanent, but more commonly the assignments are time-limited to allow administrators to perform tasks on a just-in-time basis without their account needing elevated permissions on an ongoing basis. PIM is not part of the basic Entra ID license granted with Microsoft 365 and administrators need a license like Entra ID P2 to use PIM. See this page for more licensing information.

Microsoft’s Recommendation to use Entra Admin Center to Manage PIM Role Assignments

The PIM overview contains the interesting recommendation that tenants should use “PIM to manage active role assignments over using the unifiedRoleAssignment or the directoryRole resource types to manage them directly.” In other words, Microsoft thinks it better to use the GUI built into the Entra admin center to create and manage PIM role assignments. The reason for this might be that the GUI includes guardrails to stop administrators from making mistakes, which is something to avoid when assigning privileged roles.

In any case, PIM organizes role assignments into two categories:

Eligible assignments are roles granted to users, groups, or service principals (apps) that are not active. These assignments must be activated by the holder (principal) before they can perform the privileged tasks enabled by the role. By default, eligible assignments are activated for a maximum of 8 hours, after which the activation can be extended or renewed.
Active assignments are roles that are currently available for use. An active assignment can be permanent, but more often in PIM it is time-limited.

Both categories have a schedule, and Graph APIs and SDK cmdlets are available to add requests to add, update, and remove assignments from the schedules.

Creating an Eligible PIM Role Assignment

Here’s the PowerShell code to create a new eligible assignment schedule request to add a user account to the User administrator role. Before the New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest cmdlet can run, a certain amount of setup is necessary to fetch the identifiers for the account and role and define the period during which the assignment is eligible. You also need to decide whether the assignment is for the entire directory or an administrative unit.

$User = Get-MgUser -UserId Lotte.Vetler@office365itpros.com
[array]$DirectoryRoles = Get-MgRoleManagementDirectoryRoleDefinition | Sort-Object DisplayName
$UserAdminRoleId = $DirectoryRoles | Where-Object {$_.DisplayName -eq "User administrator"} | Select-Object -ExpandProperty Id
[string]$StartAssignmentDate = Get-Date -format "yyyy-MM-ddTHH:mm:ssZ"
[string]$EndAssignmentDate = (Get-Date).AddDays(30).ToString("yyyy-MM-ddTHH:mm:ssZ")

$ScheduleInfo = @{}
$ScheduleInfo.Add("startDateTime", $StartAssignmentDate)

$ExpirationInfo = @{}
$ExpirationInfo.Add("type", "afterDateTime")
$ExpirationInfo.Add("endDateTime", $EndAssignmentDate)

$ScheduleInfo.Add("expiration", $ExpirationInfo)

$AssignmentParameters = @{}
$AssignmentParameters.Add("action", "adminAssign")
$AssignmentParameters.Add("justification", "Assign User administrator role to user")
$AssignmentParameters.Add("roleDefinitionId", $UserAdminRoleId)
$AssignmentParameters.Add("directoryScopeId", "/")
$AssignmentParameters.Add("principalId", $User.Id)
$AssignmentParameters.Add("scheduleInfo", $ScheduleInfo)

$Status = New-MgRoleManagementDirectoryRoleEligibilityScheduleRequest -BodyParameter $AssignmentParameters
If ($Status.Id) {
   Write-Host ("Assignment for user administrator role for {0} added to eligibility schedule" -f $User.displayName)
}

The values in the hash table holding the parameters for the new assignment looks like this:

$AssignmentParameters

Name                           Value
----                           -----
justification                  Assign User administrator role to user
scheduleInfo                   {[startDateTime, 2024-11-12T17:51:03Z], [expiration, System.Collections.Hashtable]}
directoryScopeId               /
roleDefinitionId               fe930be7-5e62-47db-91af-98c3a49a38b1
principalId                    ce0e26f8-da88-4efa-90ad-d16df1d9500d
action                         adminAssign

The result of a successful assignment as seen in the Entra admin center looks like the example shown in Figure 1.

The eligible role assignment created by PowerShellPIM Role assignment — Figure 1: The eligible role assignment created by PowerShell

The assigned user receives email about the assignment and can use the link in the message to activate their assignment (Figure 2). See this article about approval workflows that you might like to use to control activations.

Email informing user that they've received a PIM role assignment — Figure 2: Email informing user that they’ve received a PIM role assignment

Accounts holding the Privileged Role Administrator or Global Administrator role also receive email to inform them about the new assignment.

Creating an Active PIM Role Assignment

The code to create a PIM active role assignment request is like that used for the PIM eligible role assignment request. In this example, we create an active role assignment schedule request for the Groups administrator role and limit the assignment to a six hour period from now. The duration is expressed in ISO8601 duration format, so PT6H means six hours.

$GroupsAdminRoleId = $DirectoryRoles | Where-Object {$_.DisplayName -eq "Groups administrator"} | Select-Object -ExpandProperty Id
[string]$StartAssignmentDate = Get-Date -format "yyyy-MM-ddTHH:mm:ssZ"
$ScheduleInfo = @{}
$ScheduleInfo.Add("startDateTime", $StartAssignmentDate)

$ExpirationInfo = @{}
$ExpirationInfo.Add("type", "afterDuration")
$ExpirationInfo.Add("duration","PT6H")

$ScheduleInfo.Add("expiration", $ExpirationInfo)

$AssignmentParameters = @{}
$AssignmentParameters.Add("action", "adminAssign")
$AssignmentParameters.Add("justification", "Assign Groups administrator role to user")
$AssignmentParameters.Add("roleDefinitionId", $GroupsAdminRoleId)
$AssignmentParameters.Add("directoryScopeId", "/")
$AssignmentParameters.Add("principalId", $User.Id)
$AssignmentParameters.Add("scheduleInfo", $ScheduleInfo)
$Status = New-MgRoleManagementDirectoryRoleAssignmentScheduleRequest -BodyParameter $AssignmentParameters
If ($Status.Id) {
   Write-Host ("Assignment for Groups administrator role for {0} added to active schedule" -f $User.displayName)
}

To remove a role assignment from a schedule, create another role assignment schedule request and state the action to be “adminRemove” rather than “adminAssign.” For example, the request to remove the assignment request created above is:

$AssignmentParameters = @{}
$AssignmentParameters.Add("action", "adminRemove")
$AssignmentParameters.Add("justification", "Remove Groups administrator role to user")
$AssignmentParameters.Add("roleDefinitionId", $GroupsAdminRoleId)
$AssignmentParameters.Add("directoryScopeId", "/")
$AssignmentParameters.Add("principalId", $User.Id)
$Status = New-MgRoleManagementDirectoryRoleAssignmentScheduleRequest -BodyParameter $AssignmentParameters#
If ($Status.Status -eq "Revoked") { Write-Host "Active assignment revoked" }

Required Permissions for PIM

Adding role assignments requires the RoleManagement.ReadWrite.Directory permission. If you’re only reading role information, the RoleManagement.Read.Directory permission is sufficient. In addition, when using delegated permissions, read operations are only possible when the signed-in account holds one of the Global Reader, Security Operator, Security Reader, Security Administrator, or Privileged Role Administrator roles. Write operations, like adding a new role assignment to a schedule, require the signed-in account to hold the Privileged Role Administrator (or Global administrator) role.

Most Will Use the Entra Admin Center

Although it’s straightforward to create and manage PIM role assignment schedule requests with PowerShell, it’s easier to use the Entra admin center. Microsoft has done the work to create and refine the GUI and create the necessary checks to make sure that administrators don’t do something silly. I suspect that most administrators will interact with PIM through the Entra admin center, but it’s nice to know that the option to automate with PowerShell exists too.

Need more advice about how to write PowerShell for Microsoft 365? Get a copy of the Automating Microsoft 365 with PowerShell eBook, available standalone or as part of the Office 365 for IT Pros eBook bundle.

Cart

Cart