ust about everyone implements a roll-your-own security mechanism for his or her software applications. I’ve done it, many software companies have done it, and I am sure you have as well. But guess what: you don’t have to! With the release of Windows Server 2003, Microsoft introduced a portable, scalable, and secure Lightweight Directory Access Protocol (LDAP) database based on their Network Operating System (NOS) Active Directory (AD). This service is called Active Directory [surprise, surprise] Application Mode, or ADAM for short.

Although ADAM and AD share the same code base (and general purposes) and even are developed by the same MS development team, a couple of major differences allow ADAM the flexibility to be used in online architectures that just can’t be afforded to a full blown NOS.

This article demonstrates the ADAM installation process. It isn’t intended to be a features list or sales pitch for ADAM, but without an understanding of the reasons to implement it, you wouldn’t have much incentive to go any further. So it begins with a brief?and I mean brief?introduction to ADAM.

Why Use ADAM?
ADAM is a LDAP database that is primarily used to store users, groups, and other objects that represent organizations or other associations. It allows you to easily implement security within your applications, without having to write a huge amount of validation or user management code.

ADAM provides the following capabilities, which separate it from AD:

• Simple backup and recovery ? ADAM uses a single .dit file, which contains all the database information.
• Easy installation and clean uninstall ? It doesn’t require you to have DNS working nor to install additional components on a server.
• Extended support for X.500 directory naming rather than just DNS directory-style naming.
• Effortless schema extensions without impacting on production Active Directory environments.
• Free download from Microsoft ? ADAM itself does not have a license cost associated with it.
• Can run multiple instances on the same machine (similar in concept to multiple instances of SQL Server 2000).

ADAM has a number of great features that make it perfect for an online authentication system:

• Password Policies ? ADAM provides the ability to ensure that a user’s password meets certain complexity requirements (e.g., number of characters, case, alpha-numeric, etc.). Have you ever tried to write that code? What a pain!
• Encrypted password store ? ADAM uses the same password encryption store as Active Directory, and as such, passwords cannot be reverse-engineered (unless you store them in reversible encryption).
• Ability to use Active Directory authentication for internal users ? ADAM can pass off the authentication to Active Directory, allowing AD to authorize internal users to use the online application.

ADAM has the ability to scale out in proportions similar to Active Directory.So given all the great things about ADAM, what are its limitations?

• ADAM installs only on Windows XP (SP1 or above), Windows Server 2003 Standard, Enterprise, and Data Center Editions, but not on Windows 2000 (any edition) or Windows Server 2003 Web Edition.
• For Windows XP, the ADAM install is a limited release. You are limited to 10,000 objects within the ADAM instance.
• ADAM currently does not have complete integration with Microsoft’s Authentication Manager (nick-named AZMan). However, this is reportedly cleaned up in SP1 for Windows 2003 (no promises though!).
• ADAM has no capabilities for Kerberos. If you wish to use Kerberos, you need to implement Active Directory (and probably not over the Web!).
• Pass-through (or user-proxy) authentication requires domain membership.

Which Version of ADAM?
ADAM comes in six different flavors. When you download ADAM, be sure to select the correct version for your requirements.

ADAM provides support for both 32- and 64-bit Windows platforms, as well as providing the following specific download versions:

• Retail: This is the most common version for use within a business environment. It is subject to the standard Retail End User Licence Agreement (EULA). Use the ADAMretailIA64.exe and ADAMretailX86.exe files.
• Redistributable: Application developers use this version to package ADAM with their applications for redistribution to their users. These versions are subject to the Redistribution EULA. Use the ADAMredistIA64.exe and ADAMredistX86.exe files.
• MUI: The Multilingual User Interface (MUI) pack for ADAM allows for multiple-language support. Before installing the ADAM MUI pack, the Windows MUI pack and a retail or redistributable version of ADAM must be installed on the computer. Additionally, Hotfix 828745 must be installed. Use the AdamMUIia64.msi and AdamMUIx86.msi files.

Table 1 shows the file packages that are available for download.

You can review the information about the individual downloads from the Microsoft ADAM download site.

This article does not demonstrate redistributing an application and uses the ADAMretailX86.exe version. Ensure that you select the correct version for the OS you are running.

Install ADAM
OK, enough of the sales pitch!! Let’s have some fun.

If you have ever attempted to install Active Directory for your applications, you know that it can be a complex and daunting task, especially ensuring that all your dependencies are in place and working well. With ADAM, you simply download the .exe, provide a path to extract the files to, and then run a wizard with your specific information to install. There is no DNS to set up, no IP address ranges, sites, or any of the other fun stuff you have with AD. In fact, your machine doesn’t even need to have a fixed IP address.

	?
Figure 1. Run the ADAMretailX86.exe Package

This section walks through the install, but feel free to skip as far ahead as you feel comfortable doing.

Once the download has finished, run the ADAMretailX86.exe package (or the package you downloaded). This will provide a screen similar to that shown in Figure 1.

	?
Figure 2. Browse to the Path and Run the “adamsetup.exe” File

Specify a directory for the path that you want to run ADAM from, in my case C:ADAMInstall. The rest of this article refers to this directory (actually using %SYSTEMDRIVE%ADAMInstall).

Once the package extracts the files, you need to browse to the path and run the “adamsetup.exe” file. This will give you a screen similar to that shown in Figure 2.

Click Next, and the EULA screen appears (as shown in Figure 3).

	?
Figure 3. The EULA Screen

If you are at all like me, you probably just accepted the agreement. Though, the responsible side of me has to warn you that you should thoroughly read the EULA.

Next, you have the option of installing just the Administration tools or ADAM and the Administration tools (see Figure 4). Ensure you select “ADAM and ADAM administration tools”. Otherwise, you will get just the tools for managing ADAM without the LDAP database.

Now you can begin the ADAM-specific installation procedures.

	?
Figure 4. Install the Administration Tools Only or ADAM and the Administration Tools

In Figure 5, you see two options:

• A unique instance ? This is the option for this tutorial. It allows you to perform a brand-new installation of ADAM.
• A replica of an existing instance ? This is the option for a more complex ADAM configuration, including object replication among ADAM instances (see, it is like Active Directory).

	?
Figure 5. ADAM-specific Install: Unique Instance or Replica Existing Instance

Click Next after selecting “A unique instance.”

The next screen allows you to name your installation (see Figure 6). For this article, I use “DevX”.

You will see the Service name at the bottom of the screen prefixed with “ADAM_” (ADAM will install as a single service on your machine).

Note: When you install the service, it installs as DevX (you will see this in Figure 17 a little later) without the prefix. Not until you look at the properties of the service, will the service name have the prefix. It’s just one of those lovely little quirks.

	?
Figure 6. Name Your Installation

Next, you specify the ports that ADAM will use (see Figure 7). By default, the ports are:

• 389 ? Standard LDAP port non-encrypted. Most connections will be established over this port.
• 636 ? Standard LDAP SSL encrypted port. This port allows for secure connections to encrypt data sent to and from the ADAM instance.

If 389 and 636 are not options on your screen, don’t worry. This just means that you have another service listening on those ports, for example Active Directory (a domain controller) or another instance of ADAM.

	?
Figure 7. Specify the Ports That ADAM Will Use

Note: If ports 389 and 636 are not available, ADAM will use ports within the 50,000 range. You can change these port numbers, but if any other services are being used on the port numbers you choose, you could have a conflict. Also, don’t forget the port numbers you set your ADAM instance to, as you will need them shortly.

In the next screen (see Figure 8), you define an Application Partition (in AD this is known as a name space). You can install ADAM without defining an Application Partition, but this would give you an empty ADAM shell, which would be a bit useless when getting ADAM ready for an app.

	?
Figure 8. Define an Application Partition

In the Application Partition, type “CN=Corp,DC=DevX,DC=COM”. This will be the name of your application partition. ADAM supports not only DNS naming styles but also X.500 directory partition naming styles. X.500 naming styles take the form of organization, country (e.g., o=DevX,c=US).

In case you were wondering, “CN” stands for Common Name, and “DC” stands for Domain Component. The combination of these naming parts forms the entire name for the directory partition.

ADAM has three directory partitions (or naming contexts), which are part of the installation process:

• Schema ? This partition contains the schema definition for the LDAP database. It is very similar to the table definitions inside a SQL database, which do not contain data per-say but the description of the type of data they can hold.
• Configuration ? This directory partition contains the information for sites, services, and partitions within the ADAM instance. For example, it provides the information to allow ADAM to replicate data among other ADAM directories.
• Application ? This directory partition holds the specific data for your application (e.g., the users and groups). It is the only optional partition at installation time.

	?
Figure 9. Specify Where to Store the Data and Data Recovery Files

In the next screen (see Figure 9), you can specify the file paths for where to store the Data and Data Recovery files for the instance:

• Data Files ? These files, which finish with a .dit extension, are for the core data and schema definitions written to the directory.
• Data Recovery Files ? These files, which finish with a .edb extension, are used in a similar way as the log file in SQL Server, allowing transactions to be rolled back.

You will notice that the path also contains the name of the instance from Figure 6. This allows you to locate, back up, and restore the files very simply (no complex or conflicting paths).

Note: If you have a high-volume ADAM instance (lots of writes to the database), you may want to separate the .dit and .edb files onto separate physical spindles, as you would for SQL Server.

Once you have specified the path (the defaults are fine for this example), you need to specify the credentials that the ADAM service will run under, as shown in Figure 10. I created a local user (non-administrator) on my machine called ServiceADAM.

	?
Figure 10. Specify the Credentials That ADAM Service Will Run Under

You can run ADAM under a specified account or the restrictive Network Service account. If you do not require access outside of the local machine, create a local user account (as I did). If you require access to other machines, as in a DMZ environment, you can use either a domain user account or, of course, the Network Service account.

Note: The Network Service account is a special account used for accessing resources across your network. However, the service on the remote machine (i.e., ADAM) must also run under the Network Service account so that the resources can be accessed as that user. This is a great way of getting access to resources on remote machines, especially in a WorkGroup scenario where no domain credentials are available.

If you created a local user account, you may be prompted with a dialog as shown in Figure 11. For an account to run as a service, it needs certain rights (e.g., the “Log on as a service” right).

	?
Figure 11. Account Needs Certain Rights to Run as a Service

Note: You can see the specific permissions given to any service account by using the Local Computer Policy MMC console (gpedit.msc). Once you have loaded the console, navigate to Computer Configuration -> Windows Settings -> Security Settings -> Local Policy -> User Rights Assignment.

Select Yes and the installer will configure any rights that the service account needs for you.

In the earlier screen (Figure 10), you configured the account that the ADAM service is run as, and in this screen (Figure 12) you configure the levels of access within the ADAM instance for a specific user or group.

	?
Figure 12. Configure the Levels of Access Within the ADAM Instance

By default, the ADAM installer assigns the logged-on user administrative privileges within the ADAM instance. However, I generally assign the local Administrators group (as indicated) full administrative privileges within the ADAM instance. This allows anyone within that group access to the ADAM instance. If you are in a domain, you should take into consideration that Domain Admins (and any members of that group) will gain administrator access into your ADAM instance.

Figure 13 shows where you can extend your default ADAM schema with pre-configured schema extensions, which ship with ADAM. In this example, I import the MS-InetOrgPerson and MS-User schema extensions, which allow you to replicate users from a domain directly into your ADAM instance.

	?
Figure 13. Extend Your Default ADAM Schema

By the way, MS-AZMan is used for Authentication Manager (AZMan) and MS-UserProxy is used for passing authentication attempts off to a domain controller. At this point, ADAM and AZMan have limited integration, that is, until Service Pack 1 for Windows 2003.

You can download additional LDAP Data Interchange Format (LDIF) files or use the additional files that ship with the ADAM installer to extend your schema. But in this instance, you don’t need any additional LDIF structures.

	?
Figure 14. Summary of the Choices You Have Made

Hint: You can open the LDIF or LDF files with your favourite text editor to see what they contain.

In the screen shown in Figure 14, the installer provides a summary of the choices you have made. If you need to modify any of the installation parameters, go back and edit them before clicking Next.

Once you have clicked Next, you will see an installation screen similar to that shown in Figure 15.

	?
Figure 15. Installation Screen

Finally, you will see the screen in Figure 16, which provides a summary of the tasks completed, along with any warnings. Notice that you don’t even need a reboot after installing ADAM, which is not at all like AD!

	?
Figure 16. A Summary of the Tasks Completed

	?
Figure 17. Ensure the Service Is Running

There you are, your ADAM instance is complete. You should perform a couple of minor checks to make sure all has gone well. For example, ensure the service is running (as shown in Figure 17). Notice that the service name is the name you entered for the ADAM service in Figure 6. If you view the properties of the service, you will see the service name prefixed with “ADAM_”.

Additionally, ensure that the .dit and .edb files are in the correct path, as specified in Figure 9.

Install ADAM Using an Unattended Method
While installing ADAM is easy via the UI, you don’t have to do it all the time. You can actually install ADAM using an unattended file, similar to installing SQL Server or Windows.

The following code configures your ADAM instance in exactly the same way as you did with the manual install:

[ADAMInstall]; Specifies to install a unique ADAM instance.InstallType=Unique; If Show then ADAM setup displays progress information during installation.ShowOrHideProgressGUI=Show; Specifies the name to be assigned to the new instance.InstanceName=DevX; Specifies the communications port to use for LDAP.LocalLDAPPortToListenOn=389; Specifies the SSL communications port to use for LDAP.LocalSSLPortToListenOn=636; Specifies the application partition to create.NewApplicationPartitionToCreate="CN=Corp,DC=DevX,DC=COM"; Specifies the directory to use for ADAM data files.DataFilesPath=C:Program FilesMicrosoft ADAMDevXdata; Specifies the directory to use for ADAM log files.LogFilesPath=C:Program FilesMicrosoft ADAMDevXdata; Specifies the Service Account that ADAM runs under.ServiceAccount=WGTN-ROBHAWTH-PServiceADAM; Attempts to add the specific privileges that the ADAM service account needs to run.AddPermissionsToServiceAccount=Yes; Specifies the password for the service that ADAM runs under.ServicePassword=Password; Specifies the Administrators within the ADAM instance.Administrator=WGTN-ROBHAWTH-PAdministrators; Specifies whether to show ADAM in the Add Remove programs in Control Panel.ShowInAddRemovePrograms=Show; The following line specifies the .ldf files to import into the ADAM schema.ImportLDIFFiles="MS-InetOrgPerson.ldf" "MS-User.ldf"

Save this code as a .txt file, such as DevXADAM.txt, in the %SYSTEMDRIVE%ADAMInstall directory (I use this path in an upcoming code sample).

Now, you just launch your installation, which you can do from either a batch file (if you want a repeatable installation method) or as a once off from the command line with the following code:

://Change to the directory where our installation and unattend files areCD %SYSTEMDRIVE%ADAMInstall://Launch our ADAM installationadamsetup /c:"adaminstall.exe /answer:%SYSTEMDRIVE%ADAMInstallDevXADAM.txt"

The command line parameters for ADAMSetup.exe are:

• /Q ? Quite Mode (no UI)
• /C ? Extract files only; must use /T with this command
• /T: ? Temporary working directory to extract the files to
• /C: ? Command to execute specified by user (This is how you launch your installation.)

For the ADAMInstall.exe (embedded within the command shown) the parameters are:

• /answer: ? The filename (and path) to the unattend file
• /adv ? Used to set up ADAM replicas between instances
• /strict ? Causes all warnings to be treated as errors (This will cause your installation to fail if a warning is returned.)

The sample install code shows the progress of the installation (with the ShowOrHideProgressGUI option) to highlight when the installation process launches and completes. However, if you have any problems with your installation (for example, the progress of the installation never shows), the ADAM installer will write to one or more of the following six registry keys:

• HKEY_LOCAL_MACHINESOFTWAREMicrosoftWindowsCurrentVersionADAM_Installer_ResultsADAMInstallErrorCode
• HKEY_LOCAL_MACHINESOFTWAREMicrosoftWindowsCurrentVersionADAM_Installer_ResultsADAMInstallErrorMessage
• HKEY_LOCAL_MACHINESOFTWAREMicrosoftWindowsCurrentVersionADAM_Installer_ResultsADAMInstallWarnings
• HKEY_LOCAL_MACHINESOFTWAREMicrosoftWindowsCurrentVersionADAM_Installer_ResultsADAMUninstallErrorCode
• HKEY_LOCAL_MACHINESOFTWAREMicrosoftWindowsCurrentVersionADAM_Installer_ResultsADAMUninstallErrorMessage
• HKEY_LOCAL_MACHINESOFTWAREMicrosoftWindowsCurrentVersionADAM_Installer_ResultsADAMUninstallWarnings

The keys generated will probably be only a subset of the keys presented here. For example, when I first ran the script, I found that my password was incorrect, so the only keys I had in the registry were ADAMInstallErrorCode and ADAMInstallErrorMessage.

So it’s up to you how you install ADAM, but my recommendation is to use the GUI first, so you know how the installer works. Then when you are comfortable use the unattended method, as it is very slick!

Connect to Your Instance
It’s all well and good having an LDAP database, but what good is it if you can’t manage it? Well, for exactly that purpose, ADAM ships with some tools for connecting to the ADAM instance. The tools allow for basic tasks such as creating users, groups, organizational units, etc.

You can access these tools in a number of ways, but by far the most common is through the start menu, as shown in Figure 18.

	?
Figure 18. Access Tools Through The Start Menu

Additionally, you can go to the path, “%SYSTEMDRIVE%WindowsADAM”, which has all the tools, most of which are command line-based tools. Notice that the tools installed into a different directory than your data files. This is so that the tools are not replicated each time you install a new instance of ADAM on your machine (i.e., each instance of ADAM shares the same tools).

I use ADSIEdit, but not the version that ships with Windows. The ADAM-ADSIEdit.msc is specifically designed for ADAM, and the use of the standard ADSIEdit.msc is not supported for maintaining an ADAM instance.

When you launch ADAM-ADSIEdit.msc, you are presented with a blank MMC console. Right click on “ADAM ADSI Edit” and select “Connect to…”, which will present a dialog window similar to Figure 19.

	?
Figure 19. “Connect to…” Dialog Window

Fill out the fields with the following information:

• Connection Name ? DevX (or another name with which you wish to recognize your DevX ADAM instance)
• Server Name ? localhost (or the name of the machine on which you installed ADAM)
• Port ? 389 (or whichever port you set the install to in Figure 7)
• Connect to the following node ? Select “Distinguished Name (DN)” and enter the full name of the DevX ADAM instance (i.e., CN=Corp, DC=DevX, DC=COM)Connect using these credentials ? The account of the currently logged on user; alternatively, specify another account that has administrative privileges within the ADAM instance

When done, click Ok. You will see a screen similar to that shown in Figure 20.

	?
Figure 20. ADAM Instance Has Been Installed

The ADAM instance that you have installed has a very basic structure, without any Organizational Units, Groups, or Users. This is very similar to when you have created a new database within SQL Server; you have to fill in the blanks.

Have a look around, but perhaps the most interesting component of your ADAM instance is the Roles container (CN=Roles). If you expand this container you will see three roles defined:

• CN=Administrators. This role has full administrative privileges within your ADAM instance. The role members can create users, containers, groups, modify the password policy, etc.
• CN=Readers. This role has read-only access to the objects within your ADAM instance. Role members can read certain attributes of users, groups, and containers.
• CN=Users. This role has limited write access to the objects within your ADAM instance. Role members can update their own attributes, read certain attributes from other objects, and change their passwords.

If you take a look (double-click) at the CN=Administrators role, you should see a screen similar to that shown in Figure 21.

	?
Figure 21. The CN=Administrators Role

Scroll to the “member” attribute and click the “edit” button. You should see a screen similar to that shown in Figure 22.

	?
Figure 22. Click the “Edit” Button on the “Member” Attribute

This is actually a pointer to the Administrators role within the Configuration Partition for your ADAM instance. To see the members of that role, you need to establish a connection to the Configuration Partition (done via the ADAM-ADSIEdit.msc tool). It will contain the Security Identifier (SID) of the Administrators group that you added in Figure 12.

In case you are wondering how you resolve external users (known as foreign security principals within ADAM) to the security identifiers (SIDs) shown in ADAM, the following snippet of code will help:

'Change the strComputer name for your machinestrComputer = "WGTN-ROBHAWTH-P"'Change the strUser for the user SID you wish to retrievestrUser="ServiceADAM"'Establish a connection to the WMI objectSet objWMIService = GetObject("winmgmts:\" & strComputer & "
ootcimv2")'Retrieve the values from the WMI serviceSet objAccount = objWMIService.Get _    ("Win32_UserAccount.Name='" & strUser & "',Domain='" & strComputer & "'")Wscript.Echo objAccount.SID

This code returns the SID of the user, which is a specific value for each machine.

Save this code as a .vbs file, such as GetUserSID.vbs, in the %SYSTEMDRIVE%ADAMInstall directory. Then simply launch the script from the command prompt, and you should see the user SID returned.

Author Note: A big thank you to the Scripting Guy for his help in solving this little problem.

Uninstall ADAM
I guess a lesson on installing ADAM wouldn’t be complete without a section on uninstalling ADAM. Well I can’t really justify a whole section, but a short paragraph or two should suffice.

You can uninstall ADAM in two easy:

• Via the AddRemove Programs ? If you use the unattended method for installing ADAM ensure that the “ShowInAddRemovePrograms” option is set to “Show”.
• Using the adamuninstall.exe tool from the %SYSTEMDRIVE%WindowsADAM folder. This tool has the following command line switches:
  • /Q ? Runs quietly (no UI)
  • /answer ? Uses an unattended file
  • /force ? Ignores all warnings and forces a dismount on files in use
  • /i ? Removes the instance with a specific name (i.e., DevX)
  • /tools ? Removes the ADAM administration tools
  • /restorearchive ? Restores an archived ADAM database
  • /deletearchive ? Deletes an archived ADAM database

So to simply remove your ADAM instance, you can use the following command:

://Change to the directory where our uninstall files areCD %SYSTEMDRIVE%WindowsADAM://Launch our ADAM uninstallationadamuninstall.exe /i DevX /force

AD/AM in Action
ADAM is a very simple, yet powerful, LDAP database you can use to handle authentication for your online applications, without requiring a full-blown NOS directory.

Installation of ADAM is just the first step. ADAM has many parts, and you can enjoy many hours just exploring it!