AD LDS 101 – Part 4 – MS-AdamSyncConf.XML: A Detailed Look

I remember the first time I ever tried using ADAM for synchronization with Active Directory; I was utterly confused and really felt that there was not enough information out there describing the low-level details of the synchronization. Over the years, I have been fortunate to find a lot of piecemeal information that has given me a better, more complete picture of how ADAM and AD LDS work. One area in particular, though, caused me a lot of chagrin: The MS-AdamSyncConf.XML file.

MS-AdamSyncConf.XML is the back bone to your entire synchronization effort. Without this file, you simply cannot get synchronized data from your domain controller to your ADAM/AD LDS instance. Unfortunately, there is not a lot of data out there in regard to explaining the file, its constituent parts and how to know whether you have configured it correctly. Today I hope to remedy this by giving you a detailed look at the MS-AdamSyncConf.XML. This will include a break down of the file itself, what each parameter is/means and how to know whether you have configured it correctly. Keep in mind that this will not show you every single way you can configure it. Instead, I hope to give you a foundation of understanding for the MS-AdamSyncConf.XML file that you can then use to create other, more complex configurations.

1. MS-AdamSyncConf.XML Content:

The MS-AdamSyncConf.XML file has the following content in a default installation of ADAM/AD LDS:

<?xml version=”1.0″?>
<doc>
<configuration>
<description>sample Adamsync configuration file</description>
<security-mode>object</security-mode>
<source-ad-name>fabrikam.com</source-ad-name>
<source-ad-partition>dc=fabrikam,dc=com</source-ad-partition>
<source-ad-account></source-ad-account>
<account-domain></account-domain>
<target-dn>dc=fabrikam,dc=com</target-dn>
<query>
<base-dn>dc=fabrikam,dc=com</base-dn>
<object-filter>(objectClass=*)</object-filter>
<attributes>
<include></include>
<exclude>extensionName</exclude>
<exclude>displayNamePrintable</exclude>
<exclude>flags</exclude>
<exclude>isPrivelegeHolder</exclude>
<exclude>msCom-UserLink</exclude>
<exclude>msCom-PartitionSetLink</exclude>
<exclude>reports</exclude>
<exclude>serviceprincipalname</exclude>
<exclude>accountExpires</exclude>
<exclude>adminCount</exclude>
<exclude>primarygroupid</exclude>
<exclude>userAccountControl</exclude>
<exclude>codePage</exclude>
<exclude>countryCode</exclude>
<exclude>logonhours</exclude>
<exclude>lockoutTime</exclude>
</attributes>
</query>
<schedule>
<aging>
<frequency>0</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>

2. Breakdown of the individual sections in MS-AdamSyncConf.XML and what they do:

There are two core sections to MS-AdamSyncConf.XML: Configuration and Synchronizer-State (even though Microsoft calls Synchronizer-state a child element of Configuration). Obviously, the configuration section pertains to the configuration parameters that make this file do its magic. The Synchronizer-State section is relegated to information that is specific to the synchronizer. Apparently you are not to “modify any information in this element“. I will add to the latter notation by saying that I have never had reason to touch this section of the config. If anyone reading this has modified it, let me know about the how and why you did it.

Knowing that the main working parts are found under the configuration hood, we will dig deeper on defining and outlining what each of the constituent parameters do.

1. <description> – This is exactly what you would guess it to be: A description of the ADAM/AD LDS instance config.

2. <security-mode> – This is the security mode of the synchronization. There are two possible values for this parameter: object and partition. By default, the configuration is set to “object” and means that the user account only requires read access to the objects that will be synchronized. If the value is set to “partition”, the user account will need Replicate Directory Changes permissions on the source partition to synchronize objects. For your first sync, I would recommend leaving it as the default.

3. <source-ad-name> – This is the fully-qualified domain name of the source domain controller.

4. <source-ad-partition> – This will be the distinguished name (DN) of the source domain controller that will be used in the sync. An example of this would be “dc=thegeekispeak,dc=com”.

5. <source-ad-account> – This is the account (sAMAccountName) that you would use for authenticating the sync to the source domain controller partition. The synchronization service (adamsync) will prompt for a password when this parameter has a value. The password entered will be encrypted and stored by the service for any subsequent use. If this value is left blank (by default it is blank), then the synchronization service will leverage the credentials of the currently logged-on user.

6. <account-domain> – This is the domain name of the source domain controller from which you will be synchronizing data. This parameter is blank by default. If a value is present, it will concatenate with the <source-ad-account> to create the logon credentials for the sync. An example of how this concatenation would look is, “thegeekispeakdmanger”.

7. <target-dn> – This is the distinguished name (DN) of your ADAM/AD LDS instance. An example of this would be, “dc=testinstance,dc=com”.

8. <query> – This is a child element of Configuration which contains the following child elements of its own: base-dn, object-filter and attributes.

9. <base-dn> – This is the base distinguished name (base dn) of the source domain controller. Usually, this will have the same value as <source-ad-partition>, but there are instances where it could be different. One instance would be a <source-ad-partition> of dc=corp,dc=thegeekispeak,dc=com. The <base-dn> value would be dc=thegeekispeak,dc=com.  You can go to any level you wish in this section to get as broad or narrow a scope as possible.

10. <object-filter> – When you run a synchronization against the domain controller, you need to specify a search filter to designate what data you want to pull. By default, the value for this parameter is “(objectClass=*)”. The default value will pull everything possible over in the sync. Most often, this is not efficient, nor desired. As a result, it is better to specify a search filter that will isolate the sync to the type of data you want. For example, most of my implementations of ADAM/AD LDS are only concerned with the users in Active directory. Knowing this, I could modify the search filter to be, “(ObjectClass=user)”. The sync would then only pull over objects with an objectClass type of “user”. I will go deeper into search filters in another post. For now, this should get you what you need.

11. <attributes> – A child element of <query>, this section will contain values for attributes that you will include or exclude from your sync with the domain controller.

12. <include> – All attributes that you would like to be synchronized into your ADAM/AD LDS instance will be listed individually within the <include></include> tags. Note: In order to pull attributes over, you need to make sure they are in the schema for your ADAM/AD LDS instance prior to running the sync.

13. <exclude> – All attributes that you would not like to be synchronized into your ADAM/AD LDS instance will be listed individually within the <exclude></exclude> tags.

14. <user-proxy> – This parameter is used for object conversion to a userProxy object during the sync. Why would you convert the objects to a userProxy object? The userProxy attribute allows any authentication for a specific user against ADAM/AD LDS to be proxied back to the source domain controller for validation of the credentials. This is helpful in a synchronized instance since you do not want to have password values for a single user in two places. Additionally, it is more secure and makes it easier to expose your ADAM/AD LDS instance without exposing your source domain controller. This child element of Configuration has two child elements: source-object-class and target-object-class.

15. <source-object-class> – This will house the source object class that you would like to be converted during the sync. An example from most of my implementations is, <source-object-class>user</source-object-class>. This parameter can be multivalued if you want to convert multiple attributes during the sync.

16. <target-object-class> – This will house the target object class that will be the result of the sync conversion. In all of my implementations the value for this has been, “userProxy”.

17. <schedule> – Schedule is another child element of Configuration. This element houses the following child elements: aging and schtasks-cmd.

18. <aging> – Aging defines the time frame of how often an aging search is performed against the source domain controller. An aging search looks at the source domain controller to see if any of the objects in your ADAM/AD LDS instance have been removed(deleted). If an object has been deleted, the corresponding object will be deleted in your ADAM/AD LDS instance.

19. <frequency> – By default, the value for <frequency> is “0″. This is the number of times a sync will run before an aging search is performed. If you set this value to “1″, the aging search will be done every time you run a sync. If the value is “2″, the aging search will run after every other sync. For me, a best practice would be to set the value to “1″.

20. <num-objects> – This is a value for the number of object to search for in an aging search. I do not know what the range of possible values is with this tag. I am still researching this and will update this post once I know.

21. <schtasks-cmd> – Microsoft’s official stance on this tag is, “Reserved for future use.” I can only imagine that this will be used in accord with a scheduled task ID that was created to run the sync automatically. I guess we will see.

That does it for the configuration parameters. Now on to the Synchronizer-State parameters. Note that these values are updated by the synchronization service. You will never update these manually.

The Synchronizer-State child elements are updated with every sync that is run for a specific configuration. Not all of the elements will be updated since not all will pertain to the sync that was run. I will outline the elements and when each would be updated during a sync.

1. <dirsync-cookie> – There is not much information on this tag other than what you might find in your sync log. During a normal sync, the message, “Updating the configuration file DirSync cookie with a new value.” This will appear after all of the objects have been synchronized. I can only assume that this cookie is a reference point for the sync. It is updated every time you run the sync, as well. Below is an example of this cookie from one of my configs:

<dirsync-cookie>TVNEUwMAAAAWhiDljBfLAQAAAAAAAAAAQAAAAMXl-AAAAAAAAAAAAAAAAAADF5QAAAAAAAImtQnpl45VGrqIlHp1h6tkBAA-AAAAAAAAIAAAAAAAAAia1CemXjlUauoiUenWHq2anoAAAAAAAApcYY-+nxTtkC0MCDheRVayxu2AQAAAAAA</dirsync-cookie>

Note:  I have created line breaks with “-” in the cookie above for cleanliness.

2. <status> – Sync status? It would be logical if this parameter tracked the status of the configuration instance.

3. <authoritative-adam-instance> – This is the authoritative ADAM/AD LDS instance for the config. Why is this important? If you have replicated instances, this value will tell any of the replicated instances where to go for replication.

4. <configuration-file-guid> – The GUID of the configuration file that is currently installed.

5. <last-sync-attempt-time> – This is the time-stamp of when the last sync was attempted.

6. <last-sync-success-time> – This is the time-stamp for the last successful sync for the specified configuration instance.

7. <last-sync-error-time> – This is the time-stamp for the last sync error received.

8. <last-sync-error-string> – This is the output of the last sync error.  An example of this is as follows:

Extended Info: 0000202B: RefErr: DSID-031007EF, data 0, 1 access points
ref 1: ’2.local’
.
</last-sync-error-string>

9. <consecutive-sync-failures> – This is the numeric value for the how many consecutive sync failures have occurred.

10. <user-credentials> – This value is the password entered when installing the configuration xml with the /passPrompt flag.  The value is hashed and encrypted by the synchronizer service.  An example of this value is as follows:

<user-credentials>AQAAANCMnd8BFdERjHoAwE/Cl+sBAAAADH2b7hnUnUCh -l1vCpvv7kAAAAAACAAAAAAADZgAAwAAAABAAAAAEdRhsfwBly5V5 -yBhGm9pQAAAAAASAAACgAAAAEAAAADV3IBO6KG9wArRFxcwP7pg -YAAAAHeFPeI+PyTQKgr/n6BWN3YTQj3j/FIVgFAAAADu7xJqu/JT9hV -gIn9yljiJU6PVl</user-credentials>

Note: I have added line breaks to the value using “-” for cleanliness.

11. <runs-since-last-object-update> – The numeric value for how many sync events have occurred since the last time an object in ADAM/AD LDS was updated.

12. <runs-since-last-full-sync> – The numeric value for how many sync events have occurred since the last time a full sync has completed.

There you have it. Your details look at the MS-AdamSyncConf.XML config file for ADAM/AD LDS. In future posts, I will focus on specific sections of the config to outline different sync examples. I hope this helped give you a clearer idea of how to configure this file. As always, let me know if you have any questions or comments.

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, Schema, synchronize AD LDS, synchronize ADAM