Active Directory

Overview

Groove.id synchronizes Active Directory users with Groove.id users in both directions. You can create or delete users in Active Directory or Groove.id, 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 Groove.id, e.g. signin.example.com.

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 https://live.sysinternals.com/psexec.exe -OutFile psexec.exe
& ".\psexec.exe" -s "$Env:ProgramFiles\Groove.id\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\Groove.id\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 Groove.id 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\Groove.id\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 Groove.id, it will be created in ActiveDirectory. If you delete a user it Active Directory, it will be deleted in Groove.id. In other words, it doesn’t matter whether Active Directory or Groove.id 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\Groove.id\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.

Logs

The grooveid ad command logs to the Windows event log. Look for events named Groove.id 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 Groove.id. Get the value from the app settings in the Groove.id 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 Groove.id 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 Groove.id server.
  • gv - a hash of the user properties in Groove.id.
  • ad - a hash of the user properties in Active Directory.

On the Groove.id 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 Groove.id users. The first step is to try and match up Groove.id and AD users we’ve synchronized before. We check each Groove.id 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 Groove.id. 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 Groove.id means that the user has been deleted from Groove.id, 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 Groove.id 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 Groove.id.

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