Grant-PimEnginePermissions
Grant the PIM Manager engine identity its missing permissions
Purpose
Give the PIM Manager engine identity the Microsoft Graph (and other API) application permissions and Azure role assignments it is missing.
When to run it
When PIM Manager shows this command (Overview > permission check, or the Get Started step "Engine permissions"), with your environment's values filled in. PIM Manager itself never grants a permission: an identity that could, could give itself anything. Safe to run again: what the engine already holds is reported and left alone.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| entraRole | Privileged Role Administrator | tenant | Granting an application permission (an app role assignment) to a service principal needs a Privileged Role Administrator or a Global Administrator. Only needed for -GraphPermissions / -AppRoles. |
| azureRbac | User Access Administrator | each scope in -AzureRoleAssignments (for the tenant root: the root management group); Owner works too | Creating an Azure role assignment needs User Access Administrator or Owner at that scope. At the tenant root a Global Administrator first turns on 'Access management for Azure resources' (Microsoft Entra ID > Properties). Only needed for -AzureRoleAssignments. |
| other | delegated Microsoft Graph scopes AppRoleAssignment.ReadWrite.All and Application.Read.All | the browser sign-in (first-party public client 'Microsoft Graph Command Line Tools') | What the browser sign-in asks for: read the engine identity and the API's permissions, and create the app role assignment. No PowerShell module, no certificate, no secret. |
| other | delegated Azure Resource Manager access (user_impersonation) | the second browser sign-in (first-party public client 'Microsoft Azure PowerShell'), only for Azure roles | Reads role definitions and the engine's role assignments, and creates the missing assignment as you. |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Microsoft Graph | grant | application permission for the engine identity: an app role assignment (POST servicePrincipals/{API}/appRoleAssignedTo) for each name in -GraphPermissions (Microsoft Graph, e.g. Group.ReadWrite.All) and -AppRoles (another API, as <permission>@<API application id>) | each application permission you pass -- PIM Manager's command names exactly the ones its permission check found missing | tenant (application permissions apply tenant-wide) | The engine applies the access you define in PIM Manager through these APIs; without the permission that part of the engine fails. | Entra admin center > Enterprise applications > the engine identity > Permissions > remove the permission (or DELETE servicePrincipals/{engine}/appRoleAssignments/{id}). |
| Azure Resource Manager | grant | Azure role assignment for the engine identity (Microsoft.Authorization/roleAssignments, principalType ServicePrincipal) for each '<role>@<scope>' in -AzureRoleAssignments | the Azure role you pass, by name or role definition id: Reader (what PIM Manager asks for at the tenant root, so discovery can see Azure), optionally User Access Administrator (only when the engine must assign the Azure resource roles you delegate); Owner, Contributor and Role Based Access Control Administrator are also recognised by name, any other name is looked up at the scope | the scope you pass: the tenant root management group, a management group, a subscription or a resource group | Discovery reads Azure with Reader; assigning delegated Azure resource roles needs User Access Administrator. PIM Manager never asks for Owner or Contributor. | Azure portal > the scope > Access control (IAM) > Role assignments > remove the engine identity's assignment. |
What it only reads
- the engine identity's service principal (name, type) and the application permissions it already holds
- each API's service principal and the application permissions it offers (Microsoft Graph, or the API in -AppRoles)
- Azure role definitions (by name) and the engine identity's role assignments at and above each scope
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -TenantId | no | the tenant you sign in to | Your tenant id; a sign-in that lands in another tenant is refused. |
| -EngineObjectId | yes | Object id of the engine identity's service principal (shown in PIM Manager). | |
| -GraphPermissions | no | Microsoft Graph application permissions to grant, e.g. 'Group.ReadWrite.All','RoleManagement.ReadWrite.Directory'. | |
| -AppRoles | no | Application permissions of other APIs as '<permission>@<API application id>'. | |
| -AzureRoleAssignments | no | Azure roles as '<role name or role definition id>@<scope>'. | |
| -UseEdge | no | $true | $true opens Microsoft Edge for the sign-in; $false the default browser. |
| -GraphAccessToken | no | Automation: a Microsoft Graph token (delegated AppRoleAssignment.ReadWrite.All + Application.Read.All) instead of the browser sign-in. | |
| -ArmAccessToken | no | Automation: an Azure Resource Manager token instead of the second browser sign-in. | |
| -PlanOnly | no | off | Read and report what would be granted; change nothing (as -WhatIf). |
| -PassThru | no | off | Also return the result rows as objects. |
Preview with -WhatIf
Signs in and reads, prints the plan (already there / would grant / refused per permission), then one "What if:" line per grant: the application permission and the API, or the Azure role and its scope. Nothing is granted.
Undo
Remove each app role assignment from the engine identity (Entra admin center > Enterprise applications > the engine identity > Permissions) and each Azure role assignment (Access control (IAM) at the scope). The script creates nothing else.
Network
It connects to: login.microsoftonline.com, graph.microsoft.com, management.azure.com, localhost (the browser returns the sign-in to a local port on this computer)
Download and run
Run these lines in PowerShell: the first downloads the script into the current folder, the second runs it.
Invoke-WebRequest https://invardia.com/support/pim/Grant-PimEnginePermissions.ps1 -OutFile Grant-PimEnginePermissions.ps1
.\Grant-PimEnginePermissions.ps1 -EngineObjectId <EngineObjectId>To check the download first, compare its SHA-256 with the published one:
SHA-256 8d3832e924b73355d63e6cd0a19c40460c0158be1909ef8f2be2b689ec4a430f
Checksums: SHA256SUMS.txt · Version 3.0.70
Before you run it, compare the file's SHA-256 with its line in SHA256SUMS.txt.
Every parameter: Get-Help .\Grant-PimEnginePermissions.ps1 -Full · Source: Grant-PimEnginePermissions.ps1
Every script, identity and permission for your security review: PIM Manager