On a recent support case we had a customer who was trying to automate Privileged Identity Management (PIM) role assignments for Azure Resources with PowerShell. We could not find any public end to end documentation on the syntax to make this work. After some trial and error we found the following syntax works.

NOTE: PIM can assign both Azure AD roles and Azure resource roles so both scenarios are shown below. Additionally, make sure you have the latest version of AzureADPreview module installed.

Assigning Azure AD roles

For this scenario there is a public doc explaining the syntax which can be found at PowerShell for Azure AD roles in Privileged Identity Management . For roleDefinitionID you can also look these IDs up on Azure AD built-in roles doc

PowerShell code example:

### Azure AD PIM Example
Connect-AzureAD

$tenantID = "91ceb514-5ead-468c-a6ae-048e103d57f0"
$roleDisplayName = "Global Administrator"
$roleDefinitionID = (Get-AzureADMSRoleDefinition -Filter "DisplayName eq '$roleDisplayName'").Id
$targetuserID = (Get-AzureADUser -ObjectId User.Name@jasonfritts.me).ObjectId  # Replace user ID

$schedule = New-Object Microsoft.Open.MSGraph.Model.AzureADMSPrivilegedSchedule
$schedule.Type = "Once"
$schedule.StartDateTime = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
$schedule.EndDateTime =  ((Get-Date).AddDays(1)).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ")

# Create temporary eligible role assignment
Open-AzureADMSPrivilegedRoleAssignmentRequest -ProviderId 'aadRoles' -ResourceId $tenantID -RoleDefinitionId $roleDefinitionID -SubjectId $targetuserID -Type 'adminAdd' -AssignmentState 'Eligible' -schedule $schedule -reason "testing"

# Create temporary active role assignment
Open-AzureADMSPrivilegedRoleAssignmentRequest -ProviderId 'aadRoles' -ResourceId $tenantID -RoleDefinitionId $roleDefinitionID -SubjectId $targetuserID -Type 'adminAdd' -AssignmentState 'Active' -schedule $schedule -reason "testing"

Assigning Azure Resource Roles

For Azure Resource roles I could not find any end to end public doc examples but after trial and error the below steps were confirmed to work.

NOTE: The additional cmds compared to Azure AD role scenario are to convert ARM subscription IDs and ARM role IDs into their PIM resource IDs. For roleDefinitionID you can also look up built-in role IDs on Azure built-in roles doc if you are using custom roles, you can look these up in Azure Portal -> Subscription blade -> Access Control -> Roles

PowerShell code example:

## Azure Resource PIM Example
Connect-AzureAD

$subscriptionID = "ed6a63cc-c71c-4bfa-8bf7-c1510b559c72"
$roleDefinitionID = "b24988ac-6180-42a0-ab88-20f7382dd24c" #Built-in Contributor Role Definition ID example
$targetuserID = (Get-AzureADUser -ObjectId User.Name@jasonfritts.me).ObjectId  # Replace user ID


# Convert IDs to PIM IDs
$SubscriptionPIMID = (Get-AzureADMSPrivilegedResource -ProviderId 'AzureResources' -Filter "ExternalId eq '/subscriptions/$subscriptionID'").Id
$RoleDefinitionPIMID = (Get-AzureADMSPrivilegedRoleDefinition -ProviderId 'AzureResources' -Filter "ExternalId eq '/subscriptions/$subscriptionID/providers/Microsoft.Authorization/roleDefinitions/$roleDefinitionID'" -ResourceId $subscriptionPIMID).Id


$schedule = New-Object Microsoft.Open.MSGraph.Model.AzureADMSPrivilegedSchedule
$schedule.Type = "Once"
$schedule.StartDateTime = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ")
$schedule.EndDateTime =  ((Get-Date).AddDays(1)).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ss.fffZ")

# Create temporary eligible role assignment
Open-AzureADMSPrivilegedRoleAssignmentRequest -ProviderId 'AzureResources' -ResourceId $SubscriptionPIMID -RoleDefinitionId $RoleDefinitionPIMID -SubjectId $targetuserID -Type 'adminAdd' -AssignmentState 'Eligible' -schedule $schedule -reason "testing"

# Create temporary active role assignment
Open-AzureADMSPrivilegedRoleAssignmentRequest -ProviderId 'AzureResources' -ResourceId $SubscriptionPIMID -RoleDefinitionId $RoleDefinitionPIMID -SubjectId $targetuserID -Type 'adminAdd' -AssignmentState 'Active' -schedule $schedule -reason "testing"