Configure the Local Active Directory connector

In Windows

Install RSAT, picking the command for the host OS. The connector host must also reach a DC on TCP 9389 (AD Web Services).

In Windows

On the connector host, confirm the ActiveDirectory module is available and AD Web Services is reachable.

Get-Module -ListAvailable ActiveDirectory   # module is listed
Get-ADDomain                                # confirms ADWS connectivity

Now in Dex

The connector enrolls with a tenant enrollment token, the same as any Dex Device Agent. Sign in to the Dex console, go to Settings → Devices, and under Enrollment tokens generate (or reveal) a token. You'll put this value in the connector config as enrollment_token.

Open the Dex console

Now in Windows

gMSAs require a Key Distribution Service (KDS) root key. Skip this if a usable key already exists — check first. A new key isn't usable until 10 hours after its effective time (to allow replication across DCs); -EffectiveImmediately does not bypass this wait.

In Windows

Run on a Domain Controller (or any host with AD admin rights). -PrincipalsAllowedToRetrieveManagedPassword must be the computer account of the host that will run the connector — its machine name with a trailing $. This is not a literal placeholder; substitute your real host name.

# On the connector host, get its name:
$env:COMPUTERNAME

# Confirm the computer object exists in AD (use the name from above):
Get-ADComputer <CONNECTOR_HOSTNAME>

# Create the gMSA, authorizing that host (trailing $ is required):
New-ADServiceAccount -Name dexgmsa `
  -DNSHostName dexgmsa.<corp.example.com> `
  -PrincipalsAllowedToRetrieveManagedPassword "<CONNECTOR_HOSTNAME>$"

In Windows

On the connector host (elevated PowerShell), install the gMSA and confirm it. Install-ADServiceAccount copies no password — it verifies the host is authorized and lets the LSA fetch the rotating password from AD on demand. Test-ADServiceAccount must return True before continuing.

Install-ADServiceAccount -Identity dexgmsa
Test-ADServiceAccount    -Identity dexgmsa   # must return True
Get-ADServiceAccount     dexgmsa             # confirms the account exists

In Windows

Pick (or create) the OU(s) the connector will manage and note each Distinguished Name — these go into the connector config's allowed_ous later, and you delegate rights on exactly these OUs.

New-ADOrganizationalUnit -Name "Staff" -Path "DC=corp,DC=example,DC=com"
# DN: OU=Staff,DC=corp,DC=example,DC=com

In Windows

Run in an elevated PowerShell on a DC (or host with AD admin rights). Do not add the gMSA to Domain Admins. Set $ou to your target OU's DN and $gmsa to your <DOMAIN>\dexgmsa$, then run the complete grant block — it covers every supported connector action. Repeat for each OU by changing $ou and re-running.

$ou   = "OU=Staff,DC=corp,DC=example,DC=com"
$gmsa = "<DOMAIN>\dexgmsa$"

# READ — user_exists, get_user, find_users_in_ou,
#        get_group_members, list_user_groups, find_groups
dsacls $ou /I:T /G "${gmsa}:GR"

# USER create + delete — create_user, delete_user
dsacls $ou /I:T /G "${gmsa}:CCDC;user"

# USER property writes — update_user, enable_user, disable_user,
#   unlock_user, set_account_expiration, force-change-at-logon
#   (covers userAccountControl, lockoutTime, accountExpires, pwdLastSet, etc.)
dsacls $ou /I:S /G "${gmsa}:WP;;user"

# Reset password — reset_password (+ initial password on create_user)
dsacls $ou /I:S /G "${gmsa}:CA;Reset Password;user"

# GROUP create + delete — create_group, delete_group
dsacls $ou /I:T /G "${gmsa}:CCDC;group"

# GROUP membership — add_group_member, remove_group_member
dsacls $ou /I:S /G "${gmsa}:RPWP;member;group"

# OU create + delete — create_ou, delete_ou
dsacls $ou /I:T /G "${gmsa}:CCDC;organizationalUnit"

In Windows

Create C:\ProgramData\DexDeviceAgent\config.yaml (the installer creates the directory). Both enabled: true and the ad-connector profile are required before the agent will accept AD commands. List your real OU DNs in allowed_ous, matching exactly what you delegated.

cloud_service:
  base_url: "https://dex365.ai"
  enrollment_token: "<TENANT_ENROLLMENT_TOKEN>"
connector:
  profile: "ad-connector"
  service_account: "<DOMAIN>\\dexgmsa$"   # informational
  ad:
    enabled: true                           # master switch — required
    allowed_ous:                            # empty = deny ALL writes (safe default)
      - "OU=Staff,DC=corp,DC=example,DC=com"
    allow_raw_powershell: false             # leave OFF unless you truly need it

In Windows

The connector is the same MSI as the regular Dex agent — the AD profile is selected by an install-time property. Pre-flight the gMSA first, then install. With no PROFILE property the MSI installs the ordinary endpoint agent unchanged.

msiexec /i DexDeviceAgent.msi /qn `
  PROFILE=ad-connector AD_SERVICE_ACCOUNT="<DOMAIN>\dexgmsa$"

Install-DexAgent.ps1 -Token <TENANT_ENROLLMENT_TOKEN> `
  -Profile ad-connector -ServiceAccount "<DOMAIN>\dexgmsa$"

In Windows

Re-running the installer (e.g. to upgrade) re-registers the Windows service and resets its logon identity back to LocalSystem — silently undoing the gMSA assignment. LocalSystem has no rights in AD, so every AD operation then fails with ACCESS_DENIED even though your OU delegation is perfectly intact. This looks exactly like a permissions problem but is not. Make re-pointing the service a standard post-upgrade check. The PowerShell-native method handles the empty gMSA password correctly; the sc.exe alternative needs single quotes around the account and no password argument. If the custom action never ran (e.g. the MSI was interrupted), also re-grant "Log on as a service" via secpol.msc → Local Policies → User Rights Assignment (type the gMSA name in directly — the picker won't resolve it cleanly) and ensure the profile policy key exists.

Stop-Service DexDeviceAgent
$svc = Get-CimInstance Win32_Service -Filter "Name='DexDeviceAgent'"
$svc | Invoke-CimMethod -MethodName Change -Arguments @{
  StartName     = '<DOMAIN>\dexgmsa$'
  StartPassword = $null
}   # ReturnValue 0 = success
Start-Service DexDeviceAgent

sc.exe config DexDeviceAgent obj= '<DOMAIN>\dexgmsa$'
Restart-Service DexDeviceAgent
sc.exe qc DexDeviceAgent   # SERVICE_START_NAME must read <DOMAIN>\dexgmsa$

Get-ItemProperty "HKLM:\SOFTWARE\Policies\DexDeviceAgent"
# If Profile is missing or not "ad-connector", the agent is idle and rejects AD commands.

In Windows

Confirm the service runs as the gMSA, then from the Dex console send AD_CAPABILITIES to the device — expect module_available: true, the correct deployment_mode, and adws_reachable: true. Logs are at C:\ProgramData\DexDeviceAgent\logs\DexDeviceAgent.log (passwords are redacted).

sc.exe qc DexDeviceAgent      # SERVICE_START_NAME should be <DOMAIN>\dexgmsa$
Get-Service DexDeviceAgent    # Status: Running

Now in Dex

Once AD_CAPABILITIES reports adws_reachable: true, approve the device as an AD operator in the Dex console, then enable the Local Active Directory app so Dex routes AD commands to it. Until the app is enabled, Dex has the connector but no tools, skills, or actions to act with.

Open the App Store

Now in Windows

Common symptoms, their cause, and the fix. Most "permissions" failures after an upgrade are actually the service reverting to LocalSystem — check the service identity first.