OpsMgr AD Integration - how it works

There is a fair amount of documentation about how to enable AD Integration for OpsMgr 2007. Most of what is available is either outdated (pre-RTM) or an incomplete description of all that is involved to properly configure and understand how AD Integration works. This document will pull all of the available information together, add clarity to some of the available information and add additional detail where it has been missing from existing documentation.

Configure AD Integration

As the name suggests, OpsMgr AD Integration makes changes in Active Directory to allow publication of OpsMgr agent assignment data. This data will later be consumed when the OpsMgr agent is installed on systems being monitored. Before we begin any configuration we have a default view of Active Directory Users and Computers

The first step is to create either create a new global domain security group, add the RMS machine account to it and add it to the OpsMgrAdmins Security Group or just add the RMS computer account to the OpsMgr Admins Securiry Group directly. Then, add the OpsMgrAdmins Security Group to the 'Operations Manager Administrators' user role in the operations console. Note that when we run MOMADAdmin (next) you may need to restart the RMS to allow a refresh of the security token.

Next we need to prepare AD using the MOMADAdmin tool. This tool is run from the command line and should be run locally (not from a network share). Below we see a screenshot showing a sample execution of the MOMADAdmin command line. Note that this command line can be run from any domain joined machine but must be executed by a domain administrator. In this case, the command line arguments are as follows 

MOMADAdmin <management group name> <AD Integration Security group created above> <Name of the RMS or appropriate runas account> <domain name>

The MOMADAdmin tool creates the OperationsManager object (if it doesn’t exist), the folder representing the specific management group and two child objects used for establishing the HealthService service connection point. There are several documents that also indicate that the SDK container and related objects should be created here after running MOMADADMIN– that is not the case (it was pre-RTM but not any longer). MOMADAdmin is only responsible for creating the listed objects – other objects are created directly by the Health Service on the RMS. Note that the OperationsManager container (as shown below) is only visible when the ‘advanced features’ view is enabled by selecting View > Users,Groups and Computers as Containers in Active Directory Users and Computers

With the AD portion prepared we are now ready to enable OpsMgr itself for AD Integration. You do this from the Operator Console. Select properties on the management being configured to bring up the auto agent assignment tab. Select the ‘add’ option to launch the wizard (discussed further below) which will allow you to configure agents that should be assigned to the particular management server.

When working through the wizard you will have the option to choose the target domain for the rule. Only a single rule per domain per management server is allowed.

On the inclusion criteria section of the wizard you may either use the ‘configure’ button to specify details about which systems to include or provide the information through manual entry of an LDAP query

How about using an OU or groups of OU’s – or even a domain group to populate the systems for AD Integration. This is very possible as well. For details as to how this can be done, take a look at the AD Integration document available from systemcenterforum.org

https://www.systemcenterforum.org/wp-content/uploads/ADIntegration_final.pdf

A sample LDAP query that would be used to populate AD Integration based on group membership is as follows

(sAMAccountType=805306369)(memberof=CN=<name of AD group>,CN=Users,DC=startreke,DC=com)

The next screen of the wizard allows administrators to specify any computers that were returned as part of the LDAP query that should be excluded from AD integration

The final screen of the wizard allows configuration of agent failover. Even without AD Integration, agents will failover in the event their primary management server is unavailable but, the failover is random. Configuring failover here allows administrators the choice of using random failover or to directly specify which other management server(s) it’s agents will use in the event their primary is unavailable. When configuring failover, bear in mind that the total agent load for any single management server cannot exceed supported limits – even considering the load introduced by failover.

Once configured we can force the management server to attempt to publish it’s information to AD by restarting the Health Service – or this will happen on it’s own schedule when the AD Integration piece hits it’s next polling cycle – hourly by default. Successfully publishing to AD will result in an event similar to the following in the OperationsManager event log of the management server.

Even if you are successful you may see an event similar to the following

Don’t be alarmed. As long as you receive an event similar to the above, AD Integration is configured correctly

An unsuccessful publication attempt will result in an event similar to the following

After seeing the successful event above, we take another look at our AD structure and we see it has been updated with a few more containers as shown

Below is an example of showing the OperationsManager container when more than a single management server in the management group has been configured for AD integration. In this case steveracmisc2 is the RMS and steveracmisc3 is a standard management server.

How it works

Everything is now configured and AD Integration should be operational – all we have to do is install an agent – which will be covered shortly. What if the LDAP query need to be reconfigured? Does that change go into effect right away? When a change is introduced it would be reasonable to review the operationsmanager event log to verify the change actually took place. When we review the information in the event log following a change we only see a single event telling us that the objects we just updated have been deleted from AD, as follows

Before troubleshooting or calling for help – this is normal. The data that was stored in AD previously is removed right away – the new data will be added either on the next polling cycle (every hour by default) or after the health service is restarted – whichever comes first.

A polling cycle has been mentioned twice now. What is this polling cycle? The entire process of executing the configured LDAP queries and posting data to AD is actually handled by the combination of a rule and internal code in OpsMgr 2007. The rule of interested, along with the XML configuration (obtained by reviewing rule properties) is shown below.

As we can see, the rule is configured to post updated data to AD every 3600 seconds, or once an hour. When the rule fires hourly we will execute the configured LDAP query and only take action when changes are detected. Any changes will be reflected in AD but may take time to completely replicate to the complete AD environment.

The test environment used for these examples is very simple – so the XML shown above is very simple. The details of our rule are stored in the default management pack – which is stored in XML. If reviewing the XML more directly is needed, just open up that management pack in your favorite XML editor and find the rule. The management pack, opened in notepad, and the rule are shown below

Agent Installation

OpsMgr agents will make use of the information we have just stored in AD when they are installed either using an appropriately configured command line or when they are installed manually.

Command line
Below is a sample command line that details all of the options that are available for configuration using this option. The one of interest for this example is the USE_SETTINGS_FROM_AD switch.

msiexec.exe /i \\path\Directory\MOMAgent.msi /qn /l*v \logs\MOMAgent_install.log
USE_SETTINGS_FROM_AD=0 MANAGEMENT_GROUP=<MG_Name> MANAGEMENT_SERVER_DNS=<MSDNSName>
ACTIONS_USE_COMPUTER_ACCOUNT=0 ACTIONSUSER=<AccountUser>
ACTIONSDOMAIN=<AccountDomain> ACTIONSPASSWORD=<AccountPassword>

Manual install

The key page of interest in the install wizard is shown below. Remove the check mark from ‘specify management group information’. It is not a needed option when we will be retrieving our choices from AD.

A quick glance at the OperationsManager event log on the agent after install will verify whether or not settings were retrieved from AD as they should have been. If they were there will be an event similar to the following present.

To verify any agent is configured for AD integration, just check it's registry and you will be able to tell. The registry key is of interest is shown below. Note that the default configuration (such as in the case of an agent push) is to have AD integration disabled. Turning it on post-agent install can be done but requires the registry change and a service restart be done either manually or by some automated method (script, policy, etc)

Note: There has been a fair amount of misunderstanding regarding the EnableADIntegration registry key. This key exists on both the agent and management servers but should never be manipulated on the management servers. Early documentation, including the initial release of this document and even the OpsMgr Unleashed book, incorrectly make reference to changing this registry key on management servers.

We previously discussed how polling and changes are handled on the server side - but what about the agent side? Once an agent is installed, how often does it check back in to determine if there are any changes? the same interval holds - once an hour. This can be configured if desired - just edit the following registry key

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\HealthService\Parameters\ConnectorManager

Create a DWORD value named “ADPollIntervalMinutes” and set it to the period you wish for the healthservice to check AD for new config.