Setting up the domain controller

Vertex runs every directory request on one domain controller of the customer's domain, through the Entrosity Axis site connector installed there. This page lists what that domain controller (called DC1 below) needs, in the order to set it up.

Requirements at a glance

What	Why
The Axis site connector on DC1, a version that announces the vertex capability	Runs Vertex's jobs.
Windows PowerShell 5.1 with the ActiveDirectory and GroupPolicy modules	Every operation is a PowerShell script using these modules.
WinRM enabled on DC1	The script opens a PowerShell session to DC1 itself as the AD account.
A dedicated AD account with delegated rights	Vertex acts as this account; Active Directory refuses what it was not given.
Membership of Remote Management Users	Lets the account open that PowerShell session.
Group Policy Creator Owners, GPO and OU link rights	Only if Vertex manages GPOs.
Rights on the Password Settings Container	Only if Vertex manages password policies.
The folder %ProgramData%\Entrosity\Vertex GPO Backups	GPO backups before every GPO change.
A local administrator who accepts the local guard	Without it the connector writes nothing.

DC1 needs no inbound port from the Internet: the connector connects out to Axis over HTTPS (443).

1. Install the Axis connector on DC1

Install the site connector on DC1 as described in Site connector. Vertex jobs need its Windows build; the connector then announces the vertex capability, and Vertex offers it in the directory settings (supports_vertex). If you already have a connector on another server, install a second one on a domain controller for Vertex; a connector on a member server cannot run Vertex jobs.

The connector service can keep running as LocalSystem: Vertex's scripts do not use the service's identity for directory access, they run as the AD account you configure in Vertex.

2. PowerShell and its modules

The connector starts %SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe (Windows PowerShell 5.1, not PowerShell 7). On a domain controller the ActiveDirectory module is normally installed with the AD DS role. The GroupPolicy module comes with the Group Policy Management Console. Check, in PowerShell on DC1:

Get-Module -ListAvailable ActiveDirectory, GroupPolicy

If one is missing, install it:

Install-WindowsFeature RSAT-AD-PowerShell   # ActiveDirectory
Install-WindowsFeature GPMC                 # GroupPolicy

Without ActiveDirectory every operation fails with missing_module; without GroupPolicy only the GPO operations (and the GPO part of a sync) do.

3. WinRM (the loopback session)

The ActiveDirectory and GroupPolicy cmdlets cannot take a credential for everything they do, so the connector opens a PowerShell session to DC1 itself (New-PSSession -ComputerName <DC1>) as the AD account, and runs the operation inside it. That needs WinRM, which Windows Server enables by default. If it was turned off, enable it from an elevated PowerShell:

Enable-PSRemoting -Force
Test-WSMan -ComputerName $env:COMPUTERNAME

The session stays on the machine (loopback); nothing else has to reach DC1's WinRM port for Vertex.

4. The AD account

Create a dedicated user account for Vertex, for example SCHOOL\svc-vertex, with a long random password that does not expire (or that you change in Vertex's settings when it does). Do not make it a domain admin: give it only what Vertex should be able to do.

Remote Management Users

Add the account to the built-in domain local group Remote Management Users (on domain controllers this group applies to every DC). Without it, opening the session fails with access_denied and the hint add it to Remote Management Users.

Rights on the managed OUs

On each OU that Vertex will manage, delegate to the account what it should do there. With Active Directory Users and Computers → Delegate Control on the OU:

• Create, delete, and manage user accounts;
• Reset user passwords and force password change at next logon;
• Read all user information;
• Create, delete and manage groups and Modify the membership of a group;
• as a custom task, Organizational Unit objects: create and delete, and Write all properties on user, group and OU objects (needed to change any attribute, to unlock users by clearing lockoutTime, and to rename and move objects).

Moving an object needs the right to delete it in its OU and to create it in the target OU, so delegate on every managed OU. The effective result for one object is visible in Vertex: a live read of the object lists the attributes the account may write.

Vertex itself never changes objects outside the managed OUs or protected objects, even if the account could; the delegation is the limit Active Directory enforces in addition.

Group Policy rights (only for GPOs)

• Add the account to Group Policy Creator Owners so it can create GPOs. It becomes the owner of the GPOs it creates and can edit and delete them.
• To edit or delete existing GPOs, give the account Edit settings, delete, modify security on them in the Group Policy Management Console (Delegation tab).
• To link GPOs, give it Link GPOs on the managed OUs (Group Policy Management Console, the OU's Delegation tab). Vertex only links GPOs to managed OUs or below.

Password policy rights (only for PSOs)

Fine-grained password policies live in CN=Password Settings Container,CN=System,DC=…, which by default only domain admins can read and change. Give the account full control of password settings objects there, for example:

dsacls "CN=Password Settings Container,CN=System,DC=school,DC=local" /G "SCHOOL\svc-vertex:CCDC;msDS-PasswordSettings"
dsacls "CN=Password Settings Container,CN=System,DC=school,DC=local" /I:S /G "SCHOOL\svc-vertex:GA;;msDS-PasswordSettings"

Applying a policy to a user or group writes the policy's msDS-PSOAppliesTo, which the second line covers. Vertex only applies policies to users and groups below the managed OUs.

5. The GPO backup folder

Before every GPO change and before deleting a GPO, Vertex backs the GPO up on DC1 into %ProgramData%\Entrosity\Vertex GPO Backups (Backup-GPO, run as the AD account). Create the folder and let the account write to it; keep other users out, since backups contain the GPOs' settings:

$dir = Join-Path $env:ProgramData 'Entrosity\Vertex GPO Backups'
New-Item -ItemType Directory -Force -Path $dir | Out-Null
icacls $dir /inheritance:r /grant:r 'SYSTEM:(OI)(CI)F' 'Administrators:(OI)(CI)F' 'SCHOOL\svc-vertex:(OI)(CI)M'

If the backup before a change fails, the change still goes ahead and the operation's result has an empty backup_id; a failed backup before a delete, or a failed manual backup, fails the operation. Restore a backup with the Group Policy Management Console (Manage Backups) or Restore-GPO/Import-GPO.

6. Configure Vertex and accept the guard

1. Enter the connector, the account and the managed OUs in Vertex's directory settings (Getting started).

2. On DC1, from an elevated command prompt, accept the managed OUs and switch on what Vertex may do:

   cd "C:\Program Files\RMM Connector"
   rmm-connector vertex guard accept --ou "OU=Students,OU=School,DC=school,DC=local" --ou "OU=Staff,OU=School,DC=school,DC=local"
   rmm-connector vertex guard set --gpo on --pso on --deletes on

   Give one --ou per managed OU, exactly the list in Vertex's settings (all of them, no others); otherwise changes are refused with guard_pending. accept shows the OUs and asks you to type yes. set switches on GPO changes, password policy changes and deletes, which are off in a new guard; leave off what Vertex should not do. The default cap of 1,000 writes per minute already fits bulk imports and large membership changes.

3. Run Vertex's test and a sync, then switch on the changes Vertex should make and make a first change.

Everything about the guard: The connector's local guard.

Checklist

• The connector on DC1 is online and offered for Vertex.
• Get-Module -ListAvailable ActiveDirectory, GroupPolicy lists both.
• Test-WSMan answers on DC1.
• The AD account exists, is in Remote Management Users and has the delegated rights on the managed OUs (and, if needed, GPO and PSO rights).
• The GPO backup folder exists and the account can write to it.
• Vertex's test reports both modules and no missing managed OUs.
• rmm-connector vertex guard show says state: accepted.