Tag: .NET

For simplicity, we will refer to the technology as ADAM in this article for brevity, regardless of which operating system we are targeting.

ADAM allows instances of all or part of an Active Directory schema to be hosted separately from the domain controller to off-load tasks such as reading security group memberships or looking information about users (such as email address.) This helps to reduce the load on domain controllers for application-specific operations but ADAM effectively hosts a separate collection of the schema and this can be modified or extended as required for particular programming tasks. For example, additional application-specific security groups can be added to an ADAM schema to control access to an application.

ADAM can be synchronised to the main Active Directory schema to ensure any changes that have been made are captured and updated on the local instance. Although ADAM doesn’t provide scheduled synchronisation out of the box, a simple Windows Service (or scheduled script task) could be developed to call the synchronisation routine on a regular basis.

ADAM also includes a feature where it can still be used for authentication, by proxy. This effectively means that ADAM will service requests for schema information but pass authentication requests on to the domain controller and return the outcomes.

Initial Installation

• If you are installing ADAM on a client operating system prior to Windows 8 (i.e. Windows XP, Vista or Windows 7) or on Windows Server 2003 then you will need to download ADAM / AD LDS, as appropriate to your target environment, from the Microsoft website.
• If you are using a client operating system or Windows Server 2003 install the ADAM product first.
• If you are using Windows 7 / Server 2008 or later, then you can enable ADAM via the ‘Turn Windows features on or off’ option in Control Panel – Programs. You need to launch the Add Features Wizard (on server operating systems you need to click the Features node in Server Manager and then select the Add Features option in the right hand pane first) and then find the Remote Server Administration Tools option.
• Expand Remote Server Administation Tools and then expand the Role Administration Tools option beneath it. Find the AD DS and AD LDS Tools entry and tick it. Then install the feature by clicking Next and then Install.

Creating an ADAM Instance

• Once ADAM has been installed, there should be additional application shortcuts in the Administrative Tools folder of Control Panel. The new options include an ADAM setup wizard – on Server 2008 R2 the shortcut is called ‘Active Directory Lightweight Directory Services Setup Wizard’ but it could have a slightly different name on earlier operating system versions.
• Run the setup wizard and select a unique instance as the type of instance being installed.
• Specify a suitable name for the instance (this might be company based or application based. For example: MyCompanyAdam or MyAppAdam.)
• It is a good idea to provide a meaningful description for the purpose of the ADAM instance since multiple instances can be hosted on a single machine.
• Use the default port numbers provided unless these are already in use, in which case specify free port numbers. Either way note the port numbers down for use later on.
• Choose ‘Yes, create an application directory partition’ and give it a suitable name. (For example: DC=myapps,DC=mycompany,DC=com. (Future instructions will use this distinguished name so substitute it where appropriate in your implementation.))
• Leave the file locations as their defaults. Run the ADAM instance as a domain service account. This is required for access when synchronising with the domain controller – otherwise a password propmt may be displayed when attempting to sync.
• I would recommend using a suitable domain security group as the ADAM instance’s administrators rather than an individual user account to ensure access is possible by all users who will be expected to administer the instance.
• Do not select any of the LDIF files for import at this point in the process. The exact schema will be set up later via the command line.
• Skip through the remaining pages of the wizard and wait for the ADAM instance to be created.
• At this point you can check if the instance is running by launching a command line prompt and running ‘dsdbutil’. Enter ‘List Instances’ to display all the ADAM instances running on the machine. Enter ‘quit’ to exit dsdbutil when you are finished.

Configuring an ADAM Instance

These instructions assume you are using the default port of 389 and that you have installed your ADAM instance at the default location of %WINDIR%\Adam. If you are using a different port number to host ADAM then please replace 389 with your chosen port number in the commands below and replace the folder.

• Open a command line prompt as an Administrator (right-click the application shortcut and choose ‘Run as Administrator’.)
• Navigate to the %WINDIR%\ADAM folder in the command prompt window.
• The root Active Directory schema can be imported using a command line call. The schema is operating system version specific, so use the correct schema for your domain controller.

For Windows Server 2003:

ldifde -i -u -f ms-adamschemaw2k3.ldf -s localhost:389 -c "CN=Configuration,DC=X" #ConfigurationNamingContext

For Windows Server 2008:

ldifde -i -u -f ms-adamschemaw2k8.ldf -s localhost:389 -j . -c "CN=Configuration,DC=X" #ConfigurationNamingContextCode language: plaintext (plaintext)

• If you want to use ADAM for authentication then you need to configure it with the user-proxy schema. To do this execute the following command:

ldifde -i -s localhost:389 -c "CN=Configuration,DC=X" #ConfigurationNamingContext -f ms-userproxy.ldfCode language: plaintext (plaintext)

• Next we need the ADAM sync definitions:

ldifde -i -s localhost:389 -c "CN=Configuration,DC=X" #ConfigurationNamingContext -f ms-adamsyncmetadata.ldfCode language: plaintext (plaintext)

• ADAM can be used to host other schema content but we are concentrating on user-based content here so we’ll leave it at that. ADAM is now configured with the schema details required to synchronise with the domain controller – and to do this we need to edit an XML file with the domain controller details. A default file will have been created at %WINDIR%\Adam\ms-adamsyncconf.xml (or wherever your instance is located) as a starting point.
• Edit the XML sync configuration file, making changes as follows (ignore anything in brackets, apart from the object-filter line, or that says <leave blank> – they are just hints):

source-ad-name domain-controller-hostname
source-ad-partition distinguished-name-of-the-domain (e.g. DC=mycompany,DC=com.)
source-ad-account <leave blank> (unless you want to be prompted for a password!)
account-domain <leave blank> (the domain for the source-ad-account if you specify it.)
target-dn the-distinguished-name-of-ADAM (e.g. DC=myapps,DC=mycompany,DC=com.)
base-dn the-distinguished-name-of-the-domain-controller-root-node.
object-filter (objectCategory=person) (this specifies the scope of data that will be synchronised.)Code language: plaintext (plaintext)

• If you leave all properties being synchronised it is quite likely that it will fail. Instead, synchronise only those properties you are interested in. For example, below is a list of those that are most likely to be required for a user:

<include>objectSID</include>
<include>givenName</include>
<include>sn</include>
<include>cn</include>
<include>description</include>
<include>title</include>
<include>company</include>
<include>department</include>
<include>manager</include>
<include>mail</include>
<include>physicalDeliveryOfficeName</include>
<include>telephoneNumber</include>
<include>sAMAcountName</include>
<include>distinguishedName</include>
<include>userPrincipalName</include>Code language: HTML, XML (xml)

• Add the following immediately below the tag region:

<user-proxy>
 <source-object-class>user</source-object-class>
 <target-object-class>userProxy</target-object-class>
</user-proxy>Code language: HTML, XML (xml)

• Save the changes to the XML file and close the editor.
• Install the sync setting on the ADAM instance using the following command:

adamsync /install localhost:389 ms-adamsyncconf.xmlCode language: plaintext (plaintext)

• Before the ADAM instance can sync with the domain controller, the user-proxy object needs to be configured. By default the user proxy object only maps the userPrincipalName property so we need to using the Active Directory schema editor snap-in for Microsoft Management Console (MMC) to edit the user-proxy object. First, we need to register the snap-in:

regsvr32 schmmgmt.dllCode language: plaintext (plaintext)

• Now run mmc.exe and from the Start Menu – Run… prompt. When the console is displayed, select File – Add/Remove Snap-in… and then select the Active Directory Schema option on the left-hand pane of the window that is shown. Click the > arrow and then click OK.
• MMC will automatically load the default directory services instance (usually your main Active Directory domain), so right-click on the Active Directory Schema node in the left-hand pane of MMC and choose the ‘Change Active Directory Domain Controller…’ so you can select your ADAM instance. In the window that is shown, click on the ‘<Type a Directory Server name[:port] here>’ and enter localhost and hit return. (If you aren’t using the default port, then you will need to add the :port suffix.) Click OK to confirm the change, and if you are prompted for further confirmation just click Yes.
• In the left-hand pane in MMC, expand the Classes node and locate the userProxy object. Right click on the object name and choose the Properties option on the pop-up menu. Select the Attributes tab.
• On the Attributes tab, you should notice that userPrincipalName is already present. We now need to add all those additional properties that we specified in our ADAM sync config file. For each one, click the Add button associated with the optional attributes region of the Properties window and choose the matching attribute name from the list that is displayed.

Synchronising with a Domain Controller

• The ADAM instance can be synchronised with the domain controller via a command line prompt execution. Open a command line prompt as an Administrator and run the following:

adamsync /sync localhost:389 DC=myapps,DC=mycompany,DC=comCode language: plaintext (plaintext)

• The above command is acceptable on the command line but you may want to use something more comprehensive when executing ADAM synchronisation via a scheduled process. The following alternative command forces synchronisation to continue if an error occurs, and it writes any output from the command to a log file in the ADAM instance’s folder:

adamsync /force -1 /sync localhost:389 DC=myapps,DC=mycompany,DC=com /log mysync.logCode language: plaintext (plaintext)

Working with ADAM

One big problem of using ADAM out of the box is that the feature-rich ‘Active Directory Users and Computers’ MMC snap-in doesn’t work with it. Instead, less user-friendly tools like ADSI Edit must be employed. This section will explain basic use of ADSI Edit but if you are going to be adminstering ADAM on a regular basis I’d recommend developing your own UI or using existing 3rd Party tools such as the excellent Apache Directory Studio.

• ADSI Edit should’ve been installed as part of the ADAM installation. Goto Control Panel – Administrative Tools and run ADSI Edit from there.
• When the editor is displayed it will most likely have bound to the default LDAP provider (your company domain.) If present, remove this entry and then right click the ADSI Edit node in the left-hand pane and choose ‘Connect to…’ from the pop-up menu.
• In the ‘Computer’ section of the Connection Settings window that is displayed, enter localhost (or localhost:yourportnumber if you aren’t using the default port) in the domain or server box.
• Further up in the Connection Point section of the window, enter your ADAM instance’s distinguished name (e.g. DC=myapps,DC=mycompany,DC=com) in the distinguished name or naming context box and then click OK.
• You can now edit the Directory Services catalogue as required. (Creating new entries such as user-groups, editing group membership, etc.) by right-clicking the object and selecting the appropriate option from the pop-up menu.

Accessing Your ADAM Instance in Code

ADAM instances can be accessed in exactly the same way that you communicate with the main domain controller – via the .NET System.DirectoryServices classes.

using (DirectoryEntry schema = new DirectoryEntry(this.ServerTextBox.Text))
{
    using (DirectorySearcher searcher = new DirectorySearcher(schema))
    {
        if (userToFind.Contains("\\"))
        {
            // Trim off domain prefix
            userToFind = userToFind.Substring(userToFind.IndexOf("\\") + 1);
        }

        searcher.Filter = string.Format(
            "(&(objectClass=userProxy)(anr={0}))", userToFind);
        searcher.SearchScope = SearchScope.Subtree;

        SearchResultCollection results = searcher.FindAll();

        if (results.Count > 0)
        {
            string sam = null;

            foreach (SearchResult result in results)
            {
                if ((result.Properties.Contains("samaccountname") &&
                    string.Compare(
                        result.Properties["samaccountname"][0].ToString(), 
                        userToFind,
                        true) == 0) ||
                    (result.Properties.Contains("cn") &&
                    string.Compare(result.Properties["cn"][0].ToString(), 
                        userToFind, 
                        true) == 0))
                {
                    if (result.Properties.Contains("samaccountname"))
                    {
                        sam = result.Properties["samaccountname"][0].ToString();
                    }

                    // Get other result properties using well-known 
                    // Active Directory field names

                    // TODO: do something with the properties you've retrieved.
                }
            }
        }
    }
}Code language: C# (cs)

Issues Accessing an ADAM Instance

If you are unable to access your ADAM instance, it might be because the user account you are connecting with doesn’t have the required permissions. You can add/amend permissions via ADSI Edit:

• Open ADSI Edit and right-click on the root node (named ADSI Edit.)
• When the context menu is displayed, choose the Connect to… option.
• In the Computer region of the Connection Settings window that is displayed, enter localhost:389 in the Select or type a domain or server text-box.
• In the Connection Point region (further up the window) select a distinguished name based Naming Context, enter the distinguished name of your ADAM instance, and click OK.
  Once the schema has loaded, expand the CN=Roles node.
• You can now right-click any of the roles (e.g. CN=Administrators) and select the Properties option from the context menu.
• Find the ‘member’ attribute and edit it (double-click the property or select the property and click the Edit button.) This is a multi-value property so add those users who need access. Once you’ve finished adding/amending your members, click the OK button on the window(s) to confirm the changes.
• Close ADSI Edit when done.
• Your user accounts should now have the required access to your ADAM instance.