Initialize-PimHybridWorkerAd
PIM for Active Directory: prepare Active Directory for the hybrid worker
Purpose
Prepares Active Directory for the PIM for Active Directory hybrid worker: its group managed service accounts, their least-privilege rights, the servers GPO and, for an Azure VM, the offline domain-join blob.
When to run it
Once per worker, by the AD administrator on a domain controller (or a domain-joined admin host with dsacls.exe and the Group Policy Management tools), after the infrastructure step. Re-run safely after changing OUs or adding server onboarding.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| other | Domain Admins | the domain | creates gMSAs, groups and the servers GPO, and delegates OU rights (dsacls) |
| other | Enterprise Admins (only with -CreateKdsRootKey) | the forest | creates the forest's KDS root key |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Active Directory (-GmsaOu) | create | per identity: the gMSA (AES256), <name>-PermissionGroup (the gMSA its only member) and <name>-PrincipalsAllowedAccess (the worker computer) | AD is written only by gMSAs, one per privilege tier; every right goes to the PermissionGroup | delete the gMSAs and their two groups | ||
| Active Directory OUs | update | ACEs for <GmsaName>-PermissionGroup: -GroupsOu read + create groups + write member/displayName/description (+ delete groups only with -AllowGroupCleanup); each -AdminAccountsOu create users + full control below; AdminSDHolder write member only with -GrantProtectedGroupMembership (Tier 0) | least privilege per OU | dsacls <dn> /R <DOMAIN>\<GmsaName>-PermissionGroup | ||
| Group Policy (only with -ServerGmsaName + -ServerOu) | create | a GPO (Restricted Groups: <ServerGmsaName>-PermissionGroup member of BUILTIN\Administrators, adds only) linked to each -ServerOu | server onboarding by the Tier-1 identity | unlink and delete the GPO | ||
| Active Directory (-ProvisionOdj, Azure VM) | create | the worker's computer account in -ComputerOu and the offline domain-join blob (printed) | joins the Azure VM without line of sight; an Azure Arc server is already joined | delete the computer account | ||
| the forest (-CreateKdsRootKey) | create | a KDS root key (Add-KdsRootKey), usable about 10 hours later | no gMSA exists without one | none (forest-wide; leave it) |
What it only reads
- the domain (RootDSE, partitions), the OUs, existing gMSAs / groups / computer, the KDS root keys and their age, the AD Privileged Access Management feature (detected, never enabled), the GPO and its links
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -WorkerComputerName | yes | The worker's computer name (Azure VM name or the Arc server's name). | |
| -ComputerOu | yes | The OU of the worker's computer account. | |
| -GmsaName | no | gMSA-PIM-L1-T0 | The Tier-0 worker identity. |
| -GmsaOu | yes | Where the gMSAs and their groups are created. | |
| -GroupsOu | yes | Where PIM creates and maintains AD groups. | |
| -AdminAccountsOu | no | OU(s) of the AD admin accounts PIM creates. | |
| -GrantProtectedGroupMembership | no | false | Write member on AdminSDHolder (protected groups) -- the worker becomes Tier 0. |
| -AllowGroupCleanup | no | false | Also grant 'Delete Group objects' on -GroupsOu, for the reviewed clean-up of old PIM groups (a SuperAdmin approves the exact list in PIM Manager). |
| -ServerGmsaName | no | The Tier-1 server onboarding identity; needs -ServerOu. | |
| -ServerOu | no | The servers OU(s) for the GPO. Keep the worker out of them (the script warns). | |
| -ServerAdminGpoName | no | PIM for AD: <ServerGmsaName>-PermissionGroup is local administrator (servers) | The GPO name. |
| -UsedBy | no | PIM Manager hybrid worker | Text written into the gMSA descriptions. |
| -ProvisionOdj | no | false | Azure VM: create the computer account and print the offline domain-join blob. |
| -ReuseComputer | no | false | With -ProvisionOdj: re-provision an existing computer account (resets its password). |
| -CreateKdsRootKey | no | false | Create the forest's KDS root key when there is none (usable ~10 hours later; the script prints when). |
| -TriggerSdProp | no | false | Apply AdminSDHolder on the PDC emulator now instead of within the hour. |
Preview with -WhatIf
Prints every object, right, GPO setting and link it would create; creates nothing.
Undo
Unlink and delete the servers GPO, remove the ACEs (dsacls <dn> /R <DOMAIN>\<GmsaName>-PermissionGroup) on -GroupsOu, each -AdminAccountsOu and AdminSDHolder, then delete the gMSAs, their groups and (for an Azure VM) the computer account.
Network
It connects to: the domain controllers only (LDAP through .NET System.DirectoryServices, dsacls.exe, djoin.exe, SYSVOL); no internet. Modules: only the owner-approved Windows GroupPolicy module (to create the GPO) and Add-KdsRootKey (with -CreateKdsRootKey), framework 12.17
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/Initialize-PimHybridWorkerAd.ps1 -OutFile Initialize-PimHybridWorkerAd.ps1
.\Initialize-PimHybridWorkerAd.ps1 -WorkerComputerName <WorkerComputerName> -ComputerOu <ComputerOu> -GmsaOu <GmsaOu> -GroupsOu <GroupsOu>To check the download first, compare its SHA-256 with the published one:
SHA-256 bf9d009f1fcf1d22c60dd6c0ee38cc2663f3b8d5f48a736c31d6f355d341e525
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 .\Initialize-PimHybridWorkerAd.ps1 -Full · Source: Initialize-PimHybridWorkerAd.ps1
Every script, identity and permission for your security review: PIM Manager