Active Directory

Setting up the Active Directory synchronization agent

Overview synchronizes Active Directory users with users in both directions. You can create or delete users in Active Directory or, whichever is more convenient for you.

To make this work, we need to run a small service somewhere on your domain, typically on the domain controller itself.

Getting Started

In the console create a new Active Directory app.

Then following the directions given, install the software, replacing $YOUR_HOST with the name hostname you use to sign in to, e.g.

Invoke-Expression $((Invoke-WebRequest https://$YOUR_HOST/get.ps1).content)

Next, run a simple test to see what will happen when you enable the service. Replace $TOKEN with the value given in the console:

Invoke-WebRequest -Uri -OutFile psexec.exe
& ".\psexec.exe" -s "$Env:ProgramFiles\\grooveid.exe" ad --dry-run -t $TOKEN

If that looks good, set up the service, again, replacing $TOKEN with the value from the console:

& "$Env:ProgramFiles\\grooveid.exe" ad --install -t $TOKEN

The service must run as an account with sufficient privileges to create and delete users, which usually means Domain Admin.

Note: We use psexec to run the dry run as the same account as the service because the service token is usable by exactly one Windows user account.

Filtering Users

You can specify the -user-search-base command line option to synchronize only users within a given Active Directory path:

& "$Env:ProgramFiles\\grooveid.exe" ad --install -t $TOKEN -user-search-base "OU=Accounts,OU=RootOU,DC=ChildDomain,DC=RootDomain,DC=com"

One-way Synchronization

By default, grooveid ad synchronizes users in both directions. If you create a user in, it will be created in ActiveDirectory. If you delete a user it Active Directory, it will be deleted in In other words, it doesn’t matter whether Active Directory or is the master.

In some cases, you may want to have Active Directory be the master. For this, add the -read-only flag. With this flag specified, grooveid ad will never create, modify or delete AD users.

& "$Env:ProgramFiles\\grooveid.exe" ad --install -t $TOKEN -read-only

Note: the example shows giving the flag while installing the service. If the service is already installed, you can edit it’s configuration in HKEY_LOCAL_MACHINE\CurrentControlSet\Services\grooveid-ad-sync and add the flag there.


The grooveid ad command logs to the Windows event log. Look for events named AD Sync.

Command Line Options

The grooveid ad command accepts the following options:

  • -t token – The service token. This value associates your active directory instance with Get the value from the app settings in the console.
  • -install – create or update the Windows service registration.
  • -dry-run – don’t make any changes, but print to the console what would have been done.
  • -once – Don’t monitor for changes, but rather run a single synchronization cycle and exit.
  • -read-only – Do not make any changes to any Active Directory users, only create or delete users as needed.
  • -user-search-base – Only users under this Active Directory path will be considered for synchronization. All others are ignored.
  • -service – This is an internal flag which is specified when the service being invoked by the service control manager.

Synchronization Internals

Note: This section is for your information. It describes internals that are subject to change. If you end up relying on any of the details described here, please let us know. We wouldn’t want to break your stuff.

To track synchronization, we add a custom property grooveIdSyncState to each user in active directory. This property takes the form of a URL query string whose parameters include:

  • s - the canonical server.
  • gv - a hash of the user properties in
  • ad - a hash of the user properties in Active Directory.

On the side, we add a custom item to the user’s ExternalIDs collection. The CustomType property is of the form ad-domain:{DOMAIN_SID} where DOMAIN_SID is the security ID for the AD domain. The Value property is the user SID.

To perform synchronization, we first collect all the eligible AD users and all the users. The first step is to try and match up and AD users we’ve synchronized before. We check each users’ ExternalID. If we encounter a user that is missing from AD, but it was formerly synchronized, it means that the user was deleted from AD, so we delete it from If the user exists in both places then we synchronize the user’s properties.

Next we check AD users for the custom property grooveIdSyncState. A user that has been synchronized before but is no longer present in means that the user has been deleted from, so they are deleted from Active Directory as well.

We try to match up the remaining users by email address. Failing that, we look for users whose Active Directory logon name matches a username (the bit before the @ in their primary email address). When we find a match, we merge the user accounts, setting the grooveIdSyncState in AD and ExternalID property in

For the remaining AD users that do not exist in, we create accounts. Similarly, for the remaining users that do not exist in AD, we create AD user accounts.

Last modified May 12, 2020: refactor docs (d7a7a5c1d)