Deploy-PimActivatorBackend
PIM Activator: create the sign-in app registration
Purpose
Creates or updates the PIM Activator app registration in your tenant (the sign-in app of the PIM Activator browser extension): its SPA redirect URIs, its delegated Microsoft Graph and Azure permissions, and tenant-wide admin consent for them. Every user of the tenant can sign in to the app ("Assignment required" is off); what a person can activate is decided by their PIM eligibility, not by this app.
When to run it
Once per tenant before the PIM Activator browser extension is rolled out (PIM Manager > Operations > Client onboarding, step 1, shows the command with your values), and again when the extension needs a new permission. Re-runnable: an existing app with the same display name is updated in place. Run it once more if an earlier version of this script set "Assignment required" on the app: it switches it off again.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| entraRole | Application Administrator | tenant (active, not only eligible) | creates / updates the app registration and its service principal, including its 'Assignment required' setting. Cloud Application Administrator or Global Administrator also work. |
| entraRole | Privileged Role Administrator | tenant (active, not only eligible) | only with -GrantConsent (the default): tenant-wide admin consent that includes the protected RoleManagement.ReadWrite.Directory permission. Global Administrator also works; -GrantConsent:$false skips it. |
| other | Delegated sign-in: Application.ReadWrite.All, DelegatedPermissionGrant.ReadWrite.All | Microsoft Graph, for the first-party app Microsoft Graph Command Line Tools | the browser sign-in (auth code + PKCE, no extra app) asks for exactly these delegated permissions; they act only within your own roles above. Automation alternatives: -AccessToken with the same scopes, or -AppId + -CertificateThumbprint of an app holding the equivalent application permissions. |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Microsoft Entra ID | create | service principals of the Microsoft first-party APIs Microsoft Graph and Azure Service Management -- only when the tenant does not have them yet | the delegated permission ids are read from these service principals; a fresh tenant may not have instantiated them | none needed -- Microsoft first-party service principals; leave them | ||
| Microsoft Entra ID | create | app registration 'PIM Activator' (-DisplayName), single tenant (AzureADMyOrg); updated in place when it exists | the extension signs users in with it | delete the app registration (Entra admin center > App registrations > PIM Activator > Delete) | ||
| app registration 'PIM Activator' | update | SPA redirect URIs https://<extension id>.chromiumapp.org/ and chrome-extension://<extension id>/ (merged with the URIs already there; public-client URIs cleared). -Channel Both / Test also adds the TEST build's id (internal tenants only) | launchWebAuthFlow returns to the chromiumapp.org URI; Entra validates the extension origin on token redemption | remove the URIs under Authentication, or delete the app registration | ||
| app registration 'PIM Activator' | update | required permissions (delegated): Microsoft Graph PrivilegedAccess.ReadWrite.AzureADGroup, Group.Read.All, User.Read, RoleManagement.Read.Directory, RoleManagement.ReadWrite.Directory, AdministrativeUnit.Read.All, Application.Read.All; Azure Service Management user_impersonation | what the extension needs to list and activate PIM eligibilities (groups, Entra roles, Azure roles) and to find this app in its setup wizard. PrivilegedAccess.Read.AzureADGroup is not enough: activation needs ReadWrite. | remove them under API permissions, or delete the app registration | ||
| Microsoft Entra ID | create | service principal (enterprise application) of 'PIM Activator' | the tenant's instance of the app: the consent and the 'Assignment required' setting live on it | deleted with the app registration | ||
| enterprise application 'PIM Activator' | update | 'Assignment required' = No (appRoleAssignmentRequired = false) -- only written when it is Yes today, for example because an earlier version of this script set it | every user of the tenant can sign in to the PIM Activator. The app is only how the extension signs in: what a person can activate is decided by their PIM eligibility. Nobody is assigned by this script, and users and groups already assigned to the enterprise application are left as they are -- with assignment not required they change nothing. | Enterprise applications > PIM Activator > Properties > Assignment required = Yes (then assign who may sign in under Users and groups; the next run of this script switches it off again) | ||
| Microsoft Graph | grant | tenant-wide admin consent (oauth2PermissionGrant, consentType AllPrincipals) from 'PIM Activator' to Microsoft Graph | delegated: PrivilegedAccess.ReadWrite.AzureADGroup Group.Read.All User.Read RoleManagement.Read.Directory RoleManagement.ReadWrite.Directory AdministrativeUnit.Read.All Application.Read.All openid profile offline_access | all users of the tenant; a delegated permission acts only within the signed-in user's own rights | users are not asked to consent one by one (with -GrantConsent, the default) | Enterprise applications > PIM Activator > Permissions > revoke, or delete the oauth2PermissionGrant |
| Azure Service Management | grant | tenant-wide admin consent (oauth2PermissionGrant, AllPrincipals) from 'PIM Activator' to Azure Service Management | delegated: user_impersonation | all users of the tenant; acts only within the user's own Azure rights | the extension lists and activates the user's Azure role eligibilities | Enterprise applications > PIM Activator > Permissions > revoke |
What it only reads
- your own sign-in (/me) and your active Entra roles (from the token, or /me/memberOf)
- the published permission ids of the Microsoft Graph and Azure Service Management service principals
- app registrations named -DisplayName, and the enterprise application's 'Assignment required' setting
- existing admin-consent grants of the app
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -TenantId | no | the home tenant of the account you sign in with | Your tenant id; the sign-in is refused when it lands in another tenant. Required for app-only sign-in. |
| -Channel | no | Released | Released registers only the released extension id. Both / Test also register the TEST build (internal tenants only). |
| -DisplayName | no | PIM Activator | Display name of the app registration (also how an existing one is found). |
| -ExtensionId | no | eheocihmlppcophaeakmdenhgcookkab | The extension id; change it only for a fork of the extension. |
| -GrantConsent | no | true | Grant tenant-wide admin consent. -GrantConsent:$false skips it (users or an approver consent later). |
| -UseEdge | no | true | Open the sign-in in Microsoft Edge (the default browser when Edge is missing). -UseEdge:$false uses the default browser. |
| -AccessToken | no | Automation: a Microsoft Graph token you already have, with the delegated scopes above. Skips the browser sign-in. | |
| -AppId | no | Automation, app-only: client id of an app holding Application.ReadWrite.All (+ DelegatedPermissionGrant.ReadWrite.All for consent) as application permissions. Use with -CertificateThumbprint and -TenantId. Not used by the command PIM Manager shows. | |
| -CertificateThumbprint | no | Automation, app-only: thumbprint of that app's certificate in the local certificate store. Not used by the command PIM Manager shows. | |
| -AssignToGroupId | no | No longer used. Earlier versions assigned this group to the app and set 'Assignment required'. Still accepted so a command copied from an earlier PIM Manager page keeps working: the script says it is ignored and assigns nobody. |
Preview with -WhatIf
Signs in, reads the tenant, and prints a 'What if:' line for every change: the app registration it would create or update (with its redirect URIs and permissions), the service principal it would create, 'Assignment required' = No when it is Yes today, and the two admin-consent grants. Nothing is written.
Undo
Delete the app registration 'PIM Activator' in the Entra admin center (App registrations > PIM Activator > Delete): that removes its service principal and its consent grants with it. The PIM Activator extension can then no longer sign in.
Network
It connects to: login.microsoftonline.com, graph.microsoft.com
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/Deploy-PimActivatorBackend.ps1 -OutFile Deploy-PimActivatorBackend.ps1
.\Deploy-PimActivatorBackend.ps1To check the download first, compare its SHA-256 with the published one:
SHA-256 0b105a62f44d33a5ca6443c942c6c54727276e215560fd55672440f26996f9c3
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 .\Deploy-PimActivatorBackend.ps1 -Full · Source: Deploy-PimActivatorBackend.ps1
Every script, identity and permission for your security review: PIM Manager