Initialize-EpsHybridWorkerAd
Documentation out of date
The documentation below was written for a different copy of this script than the one published now. Read the script itself before you run it, or ask support@invardia.com.
- the .doc.json names no sha256 of the script it documents
- the .doc.json is for version 2.0.0, the published script is 2.0.107
The published script's own summary: Delegates the Entra Policy Suite hybrid worker in Active Directory: the right to write EXACTLY the tag attributes you choose on user (and, for device tags, computer) objects - nothing else (DESIGN §6). Run once by a domain admin on a domain machine.
Purpose
Gives the hybrid worker the right to write exactly the tag attributes you choose on user objects (and computer objects for device tags) anywhere in the domain - one inheritable ACE per attribute and object class at the domain root, granted to the group <gMSA>-PermissionGroup (the gMSA its only member), nothing else. Plan first: without -Apply nothing is changed; with -Apply every change is read back.
When to run it
Once before the worker is installed, and again when a tag type moves to another attribute.
Who may run it
| Kind | Role | Scope | Why |
|---|---|---|---|
| other | a domain admin | the domain root (and AdminSDHolder with -IncludeProtectedAccounts) | makes the permission group if missing and adds the ACEs |
What it changes
| Where | Action | What | Permission / role | Scope | Why | Undo |
|---|---|---|---|---|---|---|
| Active Directory | create | <gMSA>-PermissionGroup (when missing), in the gMSA's container, the gMSA its only member | - | one global security group | every AD right of the worker goes to this group, never to the gMSA (framework HYBRID-AD-1) | delete the group after -Remove -Apply |
| Active Directory | grant | <gMSA>-PermissionGroup | WriteProperty on each attribute you list, inherited by descendant user (and with -ObjectClasses computer, computer) objects | the domain root | the worker writes the tags of AD-synced users (and devices) | -Remove -Apply (the same ACEs, removed) |
| Active Directory | grant | <gMSA>-PermissionGroup | WriteProperty on the same attributes, on the object itself | CN=AdminSDHolder,CN=System - only with -IncludeProtectedAccounts | protected admin accounts get their tags too (a Tier 0 decision) | -Remove -IncludeProtectedAccounts -Apply |
What it only reads
- the gMSA, the schema's attribute ids, the OUs' permissions
Parameters
| Parameter | Required | Default | What it does |
|---|---|---|---|
| -Gmsa | yes | the worker's gMSA (name, or DOMAIN\name$) | |
| -Attributes | yes | your tag attributes (extensionAttribute1-15 only) - no default, they differ per customer | |
| -ObjectClasses | no | user | user, and computer for device tags |
| -ProductOu | no | not used by Entra Policy Suite (it owns no AD objects); the shared parameter of the hybrid worker scripts | |
| -IncludeProtectedAccounts | no | false | also protected admin accounts (AdminSDHolder) - makes the worker Tier 0 |
| -Server | no | the domain locator | a domain controller |
| -Apply | no | false | make the changes and read them back |
| -Remove | no | false | remove the ACEs instead (the group stays) |
Preview with -WhatIf
Without -Apply (or with -WhatIf): every ACE it would add or remove and the ones already there.
Undo
Run again with -Remove -Apply.
Network
It connects to: the domain controllers (LDAP)
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/eps/Initialize-EpsHybridWorkerAd.ps1 -OutFile Initialize-EpsHybridWorkerAd.ps1
.\Initialize-EpsHybridWorkerAd.ps1 -Gmsa <Gmsa> -Attributes <Attributes>To check the download first, compare its SHA-256 with the published one:
SHA-256 a1814facb242131b3ce96d823d8ed27e4cb8e4ecc11b397aabf86e630f1d2105
Checksums: SHA256SUMS.txt · Version 2.0.107 · Documentation for version 2.0.0
Before you run it, compare the file's SHA-256 with its line in SHA256SUMS.txt.
Every parameter: Get-Help .\Initialize-EpsHybridWorkerAd.ps1 -Full · Source: Initialize-EpsHybridWorkerAd.ps1
Every script, identity and permission for your security review: Entra Policy Suite