Deploy the PIM Manager hybrid worker (PIM for Active Directory) on your own server with Azure Arc

Written by the PIM Manager team for PIM Manager 2.4.581 · 2026-10-11

The hybrid worker brings PIM Manager’s just-in-time model to your on-premises Active Directory. When a person activates a PIM group in Entra ID, the worker puts their AD admin account into the matching AD group for as long as the activation lasts, and takes it out again afterwards. It can also create and maintain the AD admin accounts, mirror PIM groups to AD groups, and make per-server groups local administrators on your servers.

This guide runs the worker on your own Windows server, on your own network, connected to Azure with Azure Arc. The worker is the same as the Azure VM worker in Deploy the hybrid worker: the same jobs, the same scheduled tasks, the same gMSA-only model. Only two things differ: the server’s cloud identity comes from Azure Arc, and nothing is built in Azure for the network.

Status: built and tested offline. It has not yet been proven on a live Arc server. Run the first deployment with -PlanOnly (the worker plans and logs, and writes nothing to AD) and check the results before you switch it on.

Edition: PIM for Active Directory is a Pro feature (On-premises Active Directory). The worker’s jobs do nothing without a Pro licence on the environment.

The one-command way

Deploy-PimHybridWorker.ps1 runs every step of this guide in the right order. It is plan-first: without -Apply it prints what it would do and changes nothing.

# from the PIM Manager release package folder, in Windows PowerShell 5.1 or PowerShell 7
$w = @{
    Target               = 'Arc'
    SubscriptionId       = '<subscription-id>'
    TenantId             = '<tenant-id>'
    ArcMachineResourceId = '/subscriptions/<sub>/resourceGroups/rg-servers/providers/Microsoft.HybridCompute/machines/SRV-PIMWRK01'
    SqlServerId          = '/subscriptions/<sub>/resourceGroups/rg-pim/providers/Microsoft.Sql/servers/sql-pim-contoso'
    SourceContainerId    = '/subscriptions/<sub>/resourceGroups/rg-pim/providers/Microsoft.Storage/storageAccounts/stpimcontoso/blobServices/default/containers/pim-src'
    Ring                 = '3'                                               # the same ring as your PIM environment
    AdDomain             = 'CONTOSO'                                         # NetBIOS name
    ComputerOu           = 'OU=Tier0 Servers,DC=contoso,DC=local'            # where SRV-PIMWRK01 is today
    GmsaOu               = 'OU=Service Accounts,OU=Tier0,DC=contoso,DC=local'
    GroupsOu             = 'OU=PIM Groups,OU=Tier0,DC=contoso,DC=local'
    AdminAccountsOu      = @('OU=Admin Accounts,OU=Tier0,DC=contoso,DC=local')
    PlanOnly             = $true                                             # first run: the worker plans only
}
.\tools\pim-hybrid-worker\Deploy-PimHybridWorker.ps1 @w            # 1. the plan
.\tools\pim-hybrid-worker\Deploy-PimHybridWorker.ps1 @w -Apply     # 2. runs until the AD step, then stops (exit 10)

At the AD step it stops and prints the exact Initialize-PimHybridWorkerAd.ps1 command, filled in with your values. Your AD administrator runs it on a domain controller (Step 3). Then continue:

.\tools\pim-hybrid-worker\Deploy-PimHybridWorker.ps1 -Resume -Apply
# if the AD step created a NEW KDS root key, it printed the time; pass it:
.\tools\pim-hybrid-worker\Deploy-PimHybridWorker.ps1 -Resume -Apply -KdsRootKeyCreatedUtc '2026-10-10T08:00:00Z'

The state is kept in %LOCALAPPDATA%\pim\hybrid\deploy-arc-<server>.json. It holds the values you gave and which steps are done, never a secret. -Resume picks the newest state file, or name one with -StatePath.

The rest of this guide explains each step, for when you want to run them yourself or understand what the command does.

What you get

How the identity works on an Arc server

A plain on-premises server has no managed identity. Azure Arc gives it one: the Arc agent on the server hands out tokens for the machine’s identity on localhost. To get one, a program must prove it is allowed to: the agent answers the first request with the path of a one-time key file, and the program must read that file and ask again with its content. Only local Administrators and members of the local group Hybrid agent extension applications (created by the Arc agent) can read it.

The worker’s scheduled tasks run as its gMSAs, so the install adds each worker gMSA to Hybrid agent extension applications (never to Administrators). PIM Manager checks the key file path the agent names before it reads it, and ignores any proxy for this local call.

The security model in one paragraph

The worker can change membership of your Tier-0 groups, so treat the server as a Tier-0 machine, like a domain controller. PIM Manager cannot enforce your on-premises hardening; these are the expectations:

• nothing inbound beyond what your Tier-0 model allows for domain controllers; no internet-facing service on it;
• only Tier-0 administrators are local administrators, and only they hold any Azure right that allows run-command on the Arc machine (Azure Connected Machine Resource Administrator, Contributor or Owner on it): run-command executes as SYSTEM on the server;
• keep it out of the servers OU whose GPO makes the Tier-1 server identity (gMSA-PIM-L2-T1) a local administrator. The AD step warns when the worker is below a -ServerOu;
• patch it like a domain controller; no other workloads on it.

Never put a worker identity (its gMSAs, their PermissionGroups, or the worker computer account) into a PIM just-in-time group. The members of those groups are the people with an active elevation, and the membership sync removes anyone else. The AD setup script never does this.

Modules and tools

• Azure side: REST only. Every Azure step calls Azure Resource Manager, Microsoft Graph and Azure SQL over REST with your browser sign-in (authorization code with PKCE, never device code) or an Invardia support session. No Azure CLI, no Az or Microsoft Graph PowerShell modules.
• On the server: no downloaded PowerShell module. The installer uses only the modules built into Windows (ScheduledTasks for its scheduled tasks, CimCmdlets for the domain-join check) and installs and tests the gMSAs through the Windows Netlogon API (no ActiveDirectory module).
• AD side: LDAP through .NET. The only PowerShell modules used are the two approved for the AD side: the Windows GroupPolicy module (only to create the servers GPO the first time) and Add-KdsRootKey (only with -CreateKdsRootKey).

Who runs what

Where the scripts come from. All scripts are in the PIM Manager release package under .\tools\pim-hybrid-worker\ (Pro / trial: the signed package Install-Invardia downloaded for your installation). Run the Azure-side scripts from the package folder (they load the engine’s REST libraries). Initialize-PimHybridWorkerAd.ps1 and Install-PimHybridWorker.ps1 run on a machine without the package (a domain controller, the worker): each is also published as one self-contained file at https://invardia.com/support/pim/<Script>.ps1; the run-command helper sends the installer self-contained by itself. Every script has its documentation page at https://invardia.com/docs/pim/scripts/<Script>/ and supports -WhatIf.

Step 0: Decide, collect and onboard

The server. A Windows Server you control, joined to the domain whose AD the worker manages, in a Tier-0 OU, with about 4 GiB of free memory. Onboard it to Azure Arc the way you onboard any server (Azure portal > Azure Arc > Machines > Add). Check on the server: azcmagent show reports Connected. The Arc machine has a system-assigned managed identity by default.

Outbound from the server (HTTPS 443 unless noted), nothing inbound:

Proxy. If the server reaches the internet only through a proxy, the Arc agent’s own proxy setting (azcmagent config set proxy.url) does not apply to other programs. Make sure SYSTEM and the gMSAs can reach the destinations above (a machine-wide WinHTTP proxy or a transparent proxy). The worker never sends its call to the local Arc agent through a proxy.

Step 1: Check the Arc machine

.\tools\pim-hybrid-worker\New-PimHybridWorkerInfra.ps1 -SubscriptionId <sub> -TenantId <tenant> `
    -ArcMachineResourceId /subscriptions/<sub>/resourceGroups/rg-servers/providers/Microsoft.HybridCompute/machines/SRV-PIMWRK01 `
    -SqlServerId /subscriptions/<sub>/resourceGroups/rg-pim/providers/Microsoft.Sql/servers/sql-pim-contoso `
    -SqlAllowedPublicIp 203.0.113.10      # only for the public SQL endpoint

It builds nothing in Azure. It checks that the machine is Connected, runs Windows and has a system-assigned identity, creates the SQL firewall rule(s) when you gave -SqlAllowedPublicIp, prints the outbound list above, and returns the machine’s identity (principalId). A disconnected machine is refused with what to check.

A private-only PIM database (private endpoint over VPN / ExpressRoute). The server asks your on-premises DNS servers (normally the DCs) for <server>.database.windows.net, and they must answer with the private endpoint’s address. Add -PrivateSql (or -PrivateSqlDnsZoneId <your privatelink.database.windows.net zone id> -PrivateDnsLinkVnetId <resolver-vnet-id> to also link the zone to the resolver’s VNet): the script prints the one conditional forwarder your DNS administrator adds. PIM never writes your DNS:

Add-DnsServerConditionalForwarderZone -Name 'privatelink.database.windows.net' -MasterServers <inbound endpoint IP> -ReplicationScope Forest

168.63.129.16 (Azure DNS) does not answer on-premises. The target is an Azure DNS Private Resolver inbound endpoint, reachable over your VPN / ExpressRoute, in a VNet the zone is linked to (-DnsForwarderIp <ip> puts its address into the printed command). Only the standard zone name is accepted; PIM never creates or links a zone named after your domain. Check on the server: Resolve-DnsName <server>.database.windows.net returns the privatelink alias and a private address.

Step 2: Grant the worker’s cloud access

powershell.exe -File .\tools\pim-hybrid-worker\Grant-PimHybridWorkerAccess.ps1 -SubscriptionId <sub> -TenantId <tenant> `
    -ArcMachineResourceId /subscriptions/<sub>/resourceGroups/rg-servers/providers/Microsoft.HybridCompute/machines/SRV-PIMWRK01 `
    -SqlServer sql-pim-contoso.database.windows.net -SqlDatabase PimPlatform `
    -SourceContainerId /subscriptions/<sub>/resourceGroups/rg-pim/providers/Microsoft.Storage/storageAccounts/stpimcontoso/blobServices/default/containers/pim-src

It reads the Arc machine’s identity from Azure and grants it exactly what the Azure VM worker’s identity gets:

A new Graph grant takes about 25 minutes to reach the identity’s tokens. Run this step before Step 4: the install fetches the PIM code with the identity.

Step 3: Prepare Active Directory (AD administrator)

The same script and the same identities as for the Azure VM worker; see [Deploy the hybrid worker, Step 4](/docs/pim/guides/deploy-hybrid-worker/) for what it creates. Two differences for an Arc server:

• No -ProvisionOdj. The server is already domain-joined; the script finds its computer account and adds it to each gMSA’s -PrincipalsAllowedAccess group.
• -WorkerComputerName is the server’s computer name.

.\Initialize-PimHybridWorkerAd.ps1 -WorkerComputerName SRV-PIMWRK01 -ComputerOu 'OU=Tier0 Servers,DC=contoso,DC=local' `
    -GmsaOu 'OU=Service Accounts,OU=Tier0,DC=contoso,DC=local' -GroupsOu 'OU=PIM Groups,OU=Tier0,DC=contoso,DC=local' `
    -AdminAccountsOu 'OU=Admin Accounts,OU=Tier0,DC=contoso,DC=local' -WhatIf

Then run it without -WhatIf. The one-command way prints this command with your values.

The KDS root key. A gMSA needs a KDS root key in the forest. With -CreateKdsRootKey the script creates one and prints the time: domain controllers use it only about 10 hours later. Wait; do not backdate the key (that is a single-DC lab shortcut only). If a key exists but is younger than 10 hours, the script says so too.

After the script: the server sees its new group membership (the -PrincipalsAllowedAccess groups) only after a reboot or a Kerberos ticket purge. The install purges the machine’s tickets itself; if the gMSA test in Step 4 still fails, reboot the server once and run Step 4 again.

Step 4: Install and configure the worker (run-command)

.\tools\pim-hybrid-worker\Invoke-PimHybridWorkerRunCommand.ps1 -SubscriptionId <sub> -TenantId <tenant> `
    -MachineResourceId /subscriptions/<sub>/resourceGroups/rg-servers/providers/Microsoft.HybridCompute/machines/SRV-PIMWRK01 `
    -Phase Configure -InstallParameters @{
        HostType           = 'Arc'
        GmsaName           = 'CONTOSO\gMSA-PIM-L1-T0'
        ServerGmsaName     = 'CONTOSO\gMSA-PIM-L2-T1'      # only with server onboarding
        SqlServer          = 'sql-pim-contoso.database.windows.net'
        SqlDatabase        = 'PimPlatform'
        TenantId           = '<tenant-id>'
        SourceContainerUrl = 'https://stpimcontoso.blob.core.windows.net/pim-src'
        Ring               = '3'
        PlanOnly           = $true                          # first run: plan and log only
    }

It sends Install-PimHybridWorker.ps1 to the server through run-command on the Arc machine (Microsoft.HybridCompute/machines/<server>/runCommands), runs it as SYSTEM, prints its output and deletes the run-command resource afterwards. If run-command cannot be used (an older Arc agent, the extension blocked by policy), it writes the same self-contained script to a file instead and tells you; the server’s administrator then runs it locally: powershell.exe -ExecutionPolicy Bypass -File .\pim-hybrid-worker-configure-srv-pimwrk01.ps1. -PrintOnly writes the file without trying run-command.

On the server the install:

1. checks that the server is domain-joined and that the Arc identity answers;
2. installs PowerShell 7 (Microsoft signature checked);
3. installs and tests each gMSA (a worker that cannot use its gMSA fails here, not at night);
4. adds each gMSA to the local group Hybrid agent extension applications (so the tasks can use the Arc identity);
5. grants log on as a batch job to the gMSAs only and locks C:\PIM down (only SYSTEM and Administrators can change the code the gMSAs run);
6. fetches the PIM code for your ring with the Arc identity and registers the six scheduled tasks:

When the plan-only run looks right, run Step 4 again without PlanOnly.

Step 5: Naming and switch-on in PIM Manager (SuperAdmin)

Exactly as for the Azure VM worker: [Deploy the hybrid worker, Step 8](/docs/pim/guides/deploy-hybrid-worker/). Set OU for new AD groups to -GroupsOu from Step 3.

Step 6: Verify end to end

1. Jobs view in PIM Manager: hybrid-ad-sync, hybrid-ad-apply, hybrid-ad-groups (and hybrid-ad-servers) show the worker as live (or plan-only).
2. On the server: Get-Content C:\PIM\logs\sync-<yyyyMMdd>.log -Tail 40. A line [mi] token via the Azure Arc agent shows the identity works.
3. If the logs say the key file cannot be read: the gMSA is not (yet) in Hybrid agent extension applications. Check with net localgroup "Hybrid agent extension applications"; the task picks up a new membership at its next start.
4. A real activation: activate a mirrored PIM group for a test admin; within seconds their AD admin account is a member of the AD group; when the activation ends, it is removed.

Rollback and removal

Remove the worker

.\tools\pim-hybrid-worker\Remove-PimHybridWorker.ps1 -Target Arc -SubscriptionId <sub> -TenantId <tenant> `
    -ArcMachineResourceId /subscriptions/<sub>/resourceGroups/rg-servers/providers/Microsoft.HybridCompute/machines/SRV-PIMWRK01 `
    -SqlServerId <sql-server-id> -SourceContainerId <source-container-id> -AdDomain CONTOSO -GmsaOu '<gMSA OU>' -GroupsOu '<groups OU>'
# plan first (nothing changes); then the same with -Apply. -StatePath <deploy state file> reuses the deploy values.

With -Apply it removes the Arc identity’s Graph read permissions (only the ones PIM grants), its Storage Blob Data Reader assignment, its database user (only when it carries the identity’s id) and this server’s pimhybridwrk-arc-<server>-<n> SQL firewall rules. Then, through run-command, it runs Install-PimHybridWorker.ps1 -Phase Remove on the server: the worker’s six scheduled tasks are unregistered, the gMSAs leave Hybrid agent extension applications and log on as a batch job, and C:\PIM\app + C:\PIM\bin are deleted (C:\PIM\logs stays). When run-command is not available (or with -PrintOnly) it writes that step as a self-contained script for the server’s administrator. The Arc machine, its agent and its identity are never removed, and nothing on the server outside the worker is touched. It never changes Active Directory: it prints the AD administrator’s clean-up (rights taken back with dsacls /R, the servers GPO unlinked and deleted, the gMSAs and their groups deleted with dsrm; your server’s computer account stays).

The KDS root key is forest-wide; leave it.