Dynamic Groups Documentation
DynamicGroups is a Windows service that maintains group membership in your Active Directory. Based on a simple but very powerful configuration file the group membership of selected groups is automagically adjusted according to defined rules.
This page documents the installation, configuration and functionality of DynamicGroups.
DynamicGroups is a free tool sponsored by Easy365Manager – probably the smartest way to manage Office 365 users, licenses and mailboxes.
Installation and Configuration Guide
This is an overview on how to safely install and configure DynamicGroups
The four main steps are detailed in the sections below. Please read them carefully to ensure a smooth installation and operation of DynamicGroups. There are a few details to be mindful of but you’ll love it when DynamicGroups is taking care of business later on:
Simply maintain the proper attributes on your user accounts! Group membership, group policy assignment, share and printer mapping, mail groups, … Everything will be fully automated based on your dynamic groups!
1. Create a Service Account
The DynamicGroups service must run with domain credentials. Observe the following requirements for the service account:
Select Password never expires when creating the service account:
Delegate the right to modify group memberships in your Active Directory by following these steps:
Open AD Users & Computers, right click your domain and select Delegate Control:
Select the service account you created:
Delegate the right to modify group membership:
Note! This does not allow the service account to modify built-in admin groups like Domain Admins or Backup Operators.
This is configured automatically during installation. In case you need to check it or want to set it up manually, follow these instructions:
Open up you local group policy editor (gpedit.msc).
Go to Computer Configuration/Windows Settings/Security Settings/Local Policy/User Rights Assignment.
Select Log on as a service.
Add the newly created service account.
Note! If this setting is controlled by a group policy you must configure the group policy as this overrides local settings.
This is configured automatically during installation. In case you need to check it or want to set it up manually, follow these instructions:
Open up properties of the folder where DynamicGroups is installed. By default this is the folder %programfiles%\Agema\DynamicGroups. Verify that the service account has Modify rights (with inheritance to subfiles and folders):
2. Install DynamicGroups
After downloading the latest version of DynamicGroups, copy the installer to the system where you want it to run.
DynamicGroups takes very little resources from your system so you can install it anywhere – preferably on a highly available system.
On most systems this is not needed due to the high trust associated with our digitally signed applications.
But if your system is blocking the execution, open file properties and select unblock:
The installer will prompt you for the service credentials. Provide the username and password for the service account created in the previous step.
The format of the user name should be [domain]\[username]
Note! The prompt for credentials may appear in the upper left corner of the screen or on your secondary screen.
Once the installation is completed you should check that the service is installed and running. Open Services.msc and locate the DynamicGroups service (refresh the screen with F5 if it’s not there).
The service should be running, set to automatic startup and logging on as the service account created in the previous step:
If the service is not running check the application eventlog for errors and check that your service account is configured according to the previous section.
3. Create AD Groups
The basis for DynamicGroups has been established. Now you just need to tell DynamicGroups “what to do”.
The steps in this section and the next section are part of the configuration and maintenance of DynamicGroups. This means you’ll have to perform these steps every time you want to change existing groups or create new groups.
To avoid creating problems with existing groups it’s better to start out with a new group (once you understand the functionality you can take on conversion of existing groups).
Create a new group and take a note of the sAMAccountName (pre-Windows 2000 name):
You will use this name when configuring the DynamicGroups configuration file in the next section.
Note! DynamicGroups supports all scopes and types of domain groups:
- Domain Local, Global and Universal
- Security and Distribution
4. Modify the Configuration File
Time for some real action: All dynamic group configurations are coming from the DynamicGroups configuration file.
This section covers all details of the configuration file.
The configuration file is named “DynamicGroups.json” and is placed in the DynamicGroups program folder. The default path to the file is:
- c:\Program Files\Agema\DynamicGroups\DynamicGroups.json
- CronSchedule
- Groups
The CronSchedule is a cron expression which determines how often the dynamic group memberships are evaluated and updated. By default the CronShedule is set to “0 0/5 * ? * * *” which causes group membership updates every five minutes.
Cron scheduling is very flexible and can accommodate almost any scedule you can imagine. But a simple configuration will be fine for most scenarios. Here are some examples:
- Run every minute: “0 0/1 * ? * * *”
- Run every ten minutes: “0 0/10 * ? * * *”
- Run every second hour: “0 0 0/2 ? * * *”
Make sure your cron string is well formatted – validate it here before using it. If the syntax is incorrect your groups will stop updating.
In a small environment (less than 1,000 users, less than 100 dynamic groups) you can set the schedule to every minute if you like.
In large environments (more than 10,000 users, more than 1,000 dynamic groups) you should consider running it less frequently.
To fine tune the cron schedule set the DynamicGroups logging level to “Trace” (refer to Troubleshooting in this section). Then review the log files to see exactly how long time the dynamic group membership update takes. If it’s only a few seconds a cron schedule of every minute is considered safe. If it’s longer time consider the impact on your DynamicGroups server as well as domain controllers before deciding.
The Groups section contains an array of groups that should have the group membership updated dynamically.
For each group you have three parameters:
- Name – must match the sAMAccountName (pre-Windows 2000 name) of the group you want to update
- LdapFilter – must be a valid LDAP filter that matches the set of users you want to be member of the group
- Scope – must be a valid DN (path to an OU) that determines what users are in scope for the group
The Name parameter is mandatory – you need to define which group this rule targets.
The LdapFilter and Scope parameters can be used alone or in combination (in which case both conditions must be met for a user to be joined to the group).
LdapFilter
The LdapFilter parameter defines an LDAP filter expressed against user accounts.
LDAP filters are a very flexible and powerful tool. If used properly, DynamicGroups can almost rid you of all group management in Active Directory!
The following are examples of LDAP filters
- All Marketing users: “(department=marketing)”
- All users with country set to United States: “(c=us)”
- All German sales people: “(&(department=sales)(c=de))”
- All Scandinavian users: “(|(c=dk)(c=no)(c=se)(c=fi))
- All users except users whose login starts with “ext-“: (!(sAMAccountName=ext-*))
Notice the use of the AND (&), OR (|) and NOT (!) operators. As you can see, wildcards are also supported.
Always make sure your LDAP filter is well formatted. You can test it in AD Users & Computers using the following procedure:
Right click Saved Queries, select New->Query:
In the query window click Define Query and switch the query type to Custom Search:
Click Advanced and type your query:
Click OK twice to see the result of the query:
Note! Although you may see other types of objects in the query result, DynamicGroups will only search user accounts.
Scope
The Scope must reference a valid DN (Distinguished Name). DynamicGroups will limit the filter to the DN defined in the scope (and any sub OU’s). If no LdapFilter is used, the scope will match all user accounts in the OU (and any sub OU’s).
Open up AD Users & Computers and find the OU DN using the following procedure:
Enable the Advanced Features view:
Then open properties for the OU you want to use as your search base, click the Attribute Editor tab, select the distinguishedName attribute and copy the value:
As the configuration file is placed in the protected Program Files area you need admin rights to modify it. Depending on you UAC settings you may need to follow these steps to make changes to the file:
- Copy the configuration file “DynamicGroups.json” from “%programfiles%\Agema\DynamicGroups” to “My Documents”
- Edit the file with your favorite text editor
- Save the file
- Copy the modified file from My Documents and back to the %programfiles%\Agema\DynamicGroups folder
Alternatively, you can run your text editor as Administrator and then directly open and edit the configuration file.
Make it a standard practice to always consult the eventlog or log file when you make changes to the configuration file! This will ensure that you catch any configuration errors early on.
Note! You don’t need to restart the service to enable the changed configuration file. DynamicGroups will process changes automatically in a matter of seconds.
When DynamicGroups finds that the configuration file has been edited it automatically saves a copy of the new file in the following folder
- %programfiles%\Agema\DynamicGroups\Backup
Backup files are named according to date and time (when the file was created).
In case you regret any changes you can copy a previous version from the Backup folder into the main program folder.
You should include the backup folder (%programfiles%\Agema\DynamicGroups\Backup) in your backup strategy to ensure that you can restore your DynamicGroups configuration in case of a system failure.
DynamicGroups includes extensive logging. By default logging is done against the eventlog and a log file.
In the eventlog you can filter the application log for DynamicGroups as source.
The log file is placed in the %programfiles%\Agema\DynamicGroups\Logs folder.
By default both the log file and eventlog are logging info, warnings and errors. If you need to perform detailed troubleshooting you can change either to “Trace”.
Make it a standard practice to always consult the eventlog or log file when you make changes to the configuration file! This will ensure that you catch any configuration errors early on.
Configure extended logging for troubleshooting issues
To modify the logging open up %programfiles%\Agema\DynamicGroups\NLog.config and change the minlevel in the desired Logger (logFile or eventLog):
If you set it to “Trace” instead of “Info” you will see very detailed information about actions performed by DynamicGroups.