AD LDS 101 – Part 5 – MS-AdamSyncConf.XML: A Real-World Example

Although my detailed look at MS-AdamSyncConf.XML post was likely helpful in seeing the config for all of its constituent parts, it may still elude some as to how it might be used in the real world. I know that when I first started out with ADAM years ago, a simple walk-through like this would have been really helpful. Below is an example of a real-world config that I regularly use when setting up ADAM/AD LDS at a customer site.

<?xml version=”1.0″?>
<doc>
<configuration>
<description>Test</description>
<security-mode>object</security-mode>
<source-ad-name>WIN-S42LED0VPT8.x.local</source-ad-name>
<source-ad-partition>dc=x,dc=local</source-ad-partition>
<source-ad-account></source-ad-account>
<account-domain></account-domain>
<target-dn>dc=idg,dc=local</target-dn>
<query>
<base-dn>dc=x,dc=local</base-dn>
<object-filter>(|(objectClass=user)(objectClass=group))</object-filter>
<attributes>
<include>objectSID</include>
<include>sourceObjectGuid</include>
<include>sAMAccountName</include>
<include>member</include>
<include>lastAgedChange</include>
<exclude></exclude>
</attributes>
</query>
<user-proxy>
<source-object-class>user</source-object-class>
<target-object-class>userProxy</target-object-class>
</user-proxy>
<schedule>
<aging>
<frequency>1</frequency>
<num-objects>0</num-objects>
</aging>
<schtasks-cmd></schtasks-cmd>
</schedule>
</configuration>
<synchronizer-state>
<dirsync-cookie></dirsync-cookie>
<status></status>
<authoritative-adam-instance></authoritative-adam-instance>
<configuration-file-guid></configuration-file-guid>
<last-sync-attempt-time></last-sync-attempt-time>
<last-sync-success-time></last-sync-success-time>
<last-sync-error-time></last-sync-error-time>
<last-sync-error-string></last-sync-error-string>
<consecutive-sync-failures></consecutive-sync-failures>
<user-credentials></user-credentials>
<runs-since-last-object-update></runs-since-last-object-update>
<runs-since-last-full-sync></runs-since-last-full-sync>
</synchronizer-state>
</doc>

So, you have a real-world config but are probable wondering what to do with it. Like my last post in this AD LDS 101 series, I will take you through the pertinent sections to show you what needs to be changed and how other sections could be useful for your needs. I will start with the connection directives since, if you have no directory with which to connect, the rest is just moot.

Connection-specific parameters:

<description>Test</description>
<security-mode>object</security-mode>
<source-ad-name>WIN-S42LED0VPT8.x.local</source-ad-name>
<source-ad-partition>dc=x,dc=local</source-ad-partition>
<source-ad-account></source-ad-account>
<account-domain></account-domain>
<target-dn>dc=idg,dc=local</target-dn>

As <description> and <security-mode> are not connection-specific, I will leave my previous post to detail their importance to the config.

My <source-ad-name> value is the actual FQDN (fully-qualified domain name) for Active Directory domain controller from which my AD LDS instance will synchronize. DNS is key for name resolution of the FQDN you provide for this element. When in doubt, use the IP address.

The <source-ad-partition> is the base DN (distinguished name) of my domain controller. Here I used the root DN of my domain controller. In larger environments, you might have a need to sync a particular domain controller lower down in the hierarchy. An example of this could be, “dc=lab1,dc=idg,dc=local”.

I have left <source-ad-account> and <account-domain> blank since I am either using the currently logged on user or have passed the “/passPrompt” flag when installing the config file.

My <target-dn> value is the partition name/DN I created when installing the AD LDS instance. In my example, the value is “dc=idg,dc=local”.

Query-specific parameters:

The values for the following elements will help identify where your synchronization will begin, what types of objects to allow and what attributes will be populated.

<query>
<base-dn>dc=x,dc=local</base-dn>
<object-filter>(|(objectClass=user)(objectClass=group))</object-filter>
<attributes>
<include>objectSID</include>
<include>sourceObjectGuid</include>
<include>sAMAccountName</include>
<include>member</include>
<include>lastAgedChange</include>
<exclude></exclude>
</attributes>
</query>

Your <base-dn> is very similar to your <source-ad-partition>. In my example, the value is equal to that of my <source-ad-partition>. If, however, I only wanted the users from a specific sub-tree of the domain controller, I could enter a value of “ou=VPN Users,dc=idg,dc=local”. It is important to note that this is where your query will being for the sync, so make sure that it fits the needed scope.

My <object-filter> is fairly specific compared to the very open filter found in the default MS-AdamSyncConfig.XML. It is a regular occurrence in my installs where group membership is needed to isolate authorized users. Although I could always get this with the default (objectClass=*), I prefer a more specific and succinct filter that will only pull objects of class “user” or “group” from the source domain controller.

Note: Some info sources for this part of the config will cite “objectCategory” for the filter since it is indexed and single-valued (based upon the default value of the objectCategory), thus more efficient. Be weary, though, as objectCategory in the filter could end up giving you an AD LDS instance full of objects that no longer have its equivalent in the domain controller (aka, if an object is deleted from the domain controller, objectCategory will not remove the corresponding object from your AD LDS instance). It is for this reason “objectClass” is preferred for the filter as it will allow for removal of the object in AD LDS after its constituent removal from the domain controller.

The <include> values are those attributes I want to be populated during my sync. There are some important attributes to take note of in my example since I will be making a conversion of all synchronized user objects to userProxy objects.

objectSID and sourceObjectGuid are required when you are doing a transformation of specific objects to userProxy objects. The reason for this is that the userProxy object actually proxies authentication requests back to the corresponding user object source domain controller. In order for the userProxy object to maintain a connection with the corresponding user object in the source domain controller, it must have the object’s SID (Security Identifier) and its GUID (Globally unique identifier). These two attributes are then stored in AD LDS for each userProxy object as identifiers for the corresponding user object in the source domain controller, thus required if you are doing a transformation.

I have sAMAccountName included since the multi-factor authentication platform with which I work leverages this attribute to query users in AD LDS. This attribute is easier for my application to use in lieu of UPN (userPrincipalName) since I do not have to deal with the “@domain” suffix. In order to user sAMAccountName, however, I do need to add it to the AD LDS schema. This is yet another topic I will cover in a future post.

In order to get group membership information for the synchronized user accounts, I have included the member attribute. This will pull both the multi-valued member list for any groups that have been synchronized, but also the multi-valued memberOf information for each user object and their associated groups. This is very key if you want to check group membership for authorization.

The lastAgedChange attribute keeps track of the latest aging information for the object that has been synchronized. This is helpful for troubleshooting if any objects do not appear to be getting updates during a sync.

This is a bare-bones list of what you could potentially include for your sync. Hopefully you can see where other objects could be of use, but also see why the userProxy transformation is also helpful.

Transformation-specific parameters:

I have already mentioned object transformation in the section preceding this. I wanted to illustrate the syntax in the config and some possible ideas on what to transform.

<user-proxy>
<source-object-class>user</source-object-class>
<target-object-class>userProxy</target-object-class>
</user-proxy>

The standard and logical configuration I use is to transform the “user” object class to the “userProxy” object class. This is simple to follow with the config since all you have to supply is the source object that will be transformed to the target object. Note that there can be multiple <source-object-class> elements. This means you can specify a number of different objects to be transformed. An example of this would be as follows:

<user-proxy>
<source-object-class>user</source-object-class>
<source-object-class>inetOrgPerson</source-object-class>
<target-object-class>userProxy</target-object-class>
</user-proxy>

This would transform both user and inetOrgPerson objects to userProxy objects.

My hope is that this detailed explanation of a real-world MS-AdamSyncConf.XML configuration is helpful and can assist you in getting a good foundation for setting up your AD LDS instance. If you have any questions or comments, let me know.

Tagged as: Active Directory, Active Directory Application Mode, Active Directory Lightweight Directory Services, AD LDS, AD LDS 101, ad lds primer, ADAM, adamsync, configuration, content, Doug Manger, LDAP, MS-AdamSyncConf.XML, real world example, Schema, synchronize AD LDS, synchronize ADAM