Documentation/Integrations

Hybrid and on-prem AD

Set up a hybrid worker with a PowerShell runbook so ServiceChanger also fills on-prem AD groups, with write-back through Entra Connect.

The idea

ServiceChanger writes cloud-only groups directly through Microsoft Graph. But groups that sync from on-prem AD into Entra are read-only in Entra: Microsoft does not allow membership writes on an on-prem mastered group. So the change has to happen on-prem.

For that, a PowerShell runbook runs on a hybrid worker alongside your cloud connection. That is a Windows host in your own network that can reach your domain controllers. The runbook applies the group memberships in AD. Your existing Entra Connect then syncs that change back to Entra, so the cloud picture matches.

ServiceChanger  ->  hybrid worker (runbook)  ->  Active Directory  ->  Entra Connect  ->  Entra ID

This way you manage cloud and on-prem from the same rule model.

What you need

  • A Windows host (server or VM) that is domain-joined or can reach the domain controllers, with the Active Directory PowerShell module installed.
  • An AD service account with rights to manage only the target groups (add and remove membership). Do not grant more than needed.
  • Outbound network access from the host to ServiceChanger to pick up work and report results.
  • A working Entra Connect sync between your AD and your tenant.

Setup in short

  1. Set up the Windows host and install the AD PowerShell module (RSAT-AD-PowerShell).
  2. Create the AD service account and delegate membership management on the organizational units or groups in scope.
  3. Install the runbook agent and link it to your tenant in ServiceChanger.
  4. Mark in ServiceChanger which groups are managed on-prem.
  5. Test on a small test group of a few users first before you roll it out more broadly.

How a change flows

  1. A rule matches (or the match drops) for a user in an on-prem synced group.
  2. ServiceChanger queues the desired change for the hybrid worker.
  3. The runbook picks up the change and applies it against AD.
  4. Entra Connect syncs the new membership back to Entra on its next cycle.
ServiceChanger recognizes whether a user and a group are on-prem synced. Microsoft cannot add a cloud-only user to an on-prem mastered group; that combination is skipped and reported instead of failing.

Example runbook step

The runbook is idempotent: it checks the current state first and only does what is needed.

Import-Module ActiveDirectory

# Add a user to an on-prem group if they are not a member yet
$group = "Engineering-All"
$userDn = (Get-ADUser -Filter "UserPrincipalName -eq '[email protected]'").DistinguishedName

$members = Get-ADGroupMember -Identity $group | Select-Object -ExpandProperty DistinguishedName
if ($members -notcontains $userDn) {
    Add-ADGroupMember -Identity $group -Members $userDn
}

Removal works similarly with Remove-ADGroupMember, only when the user is actually a member.

Timing

Turnaround depends on two things: how often the runbook picks up work, and the Entra Connect sync interval (30 minutes by default). Expect an on-prem change to be visible in Entra within an Entra Connect cycle, not instantly.

Troubleshooting

Change made in AD but not visible in Entra. Wait for the next Entra Connect cycle or force a sync. Check that the group is actually in Entra Connect's scope.

Runbook cannot change a group. Check the service account's delegated rights on that OU or group.

Combination is skipped. A cloud-only user does not fit in an on-prem mastered group, and vice versa. Decide whether the user and the group belong on the same side.

Related