Install-PimHybridWorker
PIM for Active Directory: install and configure the hybrid worker on the worker machine
Purpose
Installs and configures the PIM for Active Directory hybrid worker on the worker machine itself (an Azure VM or an Azure Arc-enabled on-premises server): the gMSAs, the PIM code for its update ring and the scheduled tasks.
When to run it
On the worker, as SYSTEM or a local administrator -- normally delivered through run-command by Invoke-PimHybridWorkerRunCommand.ps1: -Phase Join (Azure VM, then it reboots), -Phase Configure after the grants (with -PlanOnly first if you like). The daily task runs -Phase Update by itself.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| other | Local Administrator / SYSTEM on the worker (run-command runs it as SYSTEM) | the worker machine | installs PowerShell 7, the gMSAs, user rights, the C:\PIM folder and scheduled tasks |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| the worker machine (-Phase Join, Azure VM) | update | offline domain join from the blob, then a reboot | the Azure VM joins the domain without line of sight | unjoin the machine | ||
| the worker machine (-Phase Configure) | create | PowerShell 7 (Microsoft-signed MSI from github.com); the gMSA(s) installed and tested; 'log on as a batch job' for them; C:\PIM (inheritance removed: SYSTEM + Administrators write, the gMSAs read); the PIM code for the ring; the run wrapper; six scheduled tasks (PIM Hybrid Worker, PIM Hybrid AD Sync, PIM Hybrid AD Sync Servers, PIM Hybrid AD Changes, PIM Hybrid Servers with -ServerGmsaName, PIM Hybrid Worker Update) | the worker itself; no password, secret or certificate is stored | delete the 'PIM Hybrid *' scheduled tasks and C:\PIM; remove the gMSAs from 'log on as a batch job' | ||
| the worker machine (Azure Arc) | update | the gMSA(s) added to the local group 'Hybrid agent extension applications' (never Administrators) | the tasks run as the gMSAs and must answer the Arc agent's key-file challenge for the machine identity | remove them from that group | ||
| the worker machine (Azure VM, -Phase Configure) | update | the machine account password is changed once (nltest /sc_change_pwd) | makes the offline-join blob worthless | none needed | ||
| the worker machine (Azure VM: -Phase Configure, Layout, Update and MetadataAccess) | create | one outbound Windows Firewall rule, 'PIM Hybrid Worker - metadata service access': the instance metadata service (169.254.169.254, TCP 80) answers only SYSTEM (the Azure VM agent and its extensions), the worker's gMSAs and the gMSA of each product registered on the machine (C:\ProgramData\HybridWorkerHost\guests); every other account is blocked. Replaced on each run; the accounts are printed with their SIDs, and a warning names any account that cannot be resolved. Not on an Azure Arc server | only the accounts that need the machine's managed identities can ask for their tokens | -Phase Remove, or delete the rule | ||
| the worker machine (-Phase Remove) | remove | the six scheduled tasks, the gMSA(s) from 'Hybrid agent extension applications' (Arc) and from 'log on as a batch job', the metadata-service firewall rule, C:\PIM\app and C:\PIM\bin (logs kept); the machine, its agent, PowerShell 7 and the domain membership stay | retiring the worker (Remove-PimHybridWorker.ps1) | -Phase Configure |
What it only reads
- the domain-join state, the host type (the himds service / the Arc variables), the installation's licence and install key from the PIM database with the machine identity (with -UpdateSource Blob: channel.json for the ring instead), the installed version, the registered guests (C:\ProgramData\HybridWorkerHost\guests\*.json) and the account names they and worker.json give
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -Phase | yes | Join (Azure VM), Configure, Update, Layout, Remove (unregister the worker's tasks and rights on this machine; Remove-PimHybridWorker.ps1 -Target Arc runs it), Guests (read only: lists the other products registered on this machine; Remove-PimHybridWorker.ps1 runs it before it removes a VM), or MetadataAccess (Azure VM: re-applies only the metadata-service rule; a product that registers on or leaves this machine runs C:\PIM\bin\Install-PimHybridWorker.ps1 -Phase MetadataAccess as SYSTEM right after). | |
| -OdjBlob | no | -Phase Join: the offline domain-join blob (gz:...). | |
| -GmsaName | no | -Phase Configure (required): DOMAIN\gMSA-PIM-L1-T0. | |
| -ServerGmsaName | no | DOMAIN\gMSA-PIM-L2-T1 for server onboarding in its own task. | |
| -SqlServer | no | -Phase Configure (required): the PIM SQL server FQDN. | |
| -SqlDatabase | no | PimPlatform | The PIM database. |
| -TenantId | no | -Phase Configure (required): the tenant. | |
| -SourceContainerUrl | no | -Phase Configure with -UpdateSource Blob (required there): https://<store>.blob.core.windows.net/<container> with the PIM code and channel.json. | |
| -UpdateSource | no | Invardia | -Phase Configure: where the worker's code comes from, for the first install and every daily update. Invardia (the default): the signed release of the worker's own release ring from the Invardia update service -- its signature, ring and the archive's SHA-256 and size are checked before anything is unpacked, and nothing is installed when a check fails. Blob: the source container above, for an installation that does not use Invardia. |
| -Ring | no | The update ring the worker follows (the environment's). | |
| -Version | no | Pin a version instead of a ring. | |
| -AdServer | no | A specific domain controller for the worker's AD calls. | |
| -Root | no | C:\PIM | The worker's folder. |
| -IntervalMinutes | no | 5 | The safety-net task's interval. |
| -NoReboot | no | false | -Phase Join: do not reboot (reboot yourself). |
| -PlanOnly | no | false | Every run plans and logs, nothing is written to AD until Configure is re-run without it. |
| -HostType | no | Auto | Auto, AzureVm (IMDS identity) or Arc (the Azure Arc agent's identity). |
Preview with -WhatIf
Prints what the phase would do on this host (join, gMSAs, Arc group, the code, the six tasks and the metadata-service rule with the accounts it lets through) and changes nothing.
Undo
Delete the 'PIM Hybrid *' scheduled tasks, the firewall rule 'PIM Hybrid Worker - metadata service access' and C:\PIM; on Arc remove the gMSAs from 'Hybrid agent extension applications'.
Network
It connects to: the Invardia update service (invardia.com) for the signed release and the PIM SQL database, with the machine identity (with -UpdateSource Blob: the source store, <store>.blob.core.windows.net, instead); api.github.com / github.com / objects.githubusercontent.com once (PowerShell 7); the identity endpoint on the machine (IMDS on an Azure VM, the Arc agent on localhost:40342). Modules: only the owner-approved in-box Windows ScheduledTasks, CimCmdlets and NetSecurity (Windows Firewall) (framework 12.17); no ActiveDirectory module
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/Install-PimHybridWorker.ps1 -OutFile Install-PimHybridWorker.ps1
.\Install-PimHybridWorker.ps1 -Phase <Phase>To check the download first, compare its SHA-256 with the published one:
SHA-256 056ad3124e6c82876424222679fa49fc05b0b1c34a2c59b176e69bc5e2292a6c
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 .\Install-PimHybridWorker.ps1 -Full · Source: Install-PimHybridWorker.ps1
Every script, identity and permission for your security review: PIM Manager