Introduction

This is an example of how to build an ASP.NET LDAP authentication application using ADAM.

Microsoft's ADAM (Active Directory Application Mode) is a popular LDAP server for application developers. It's free, easy to install, and can "grow up" into a full-blown Active Directory. It is also simple to use if your application is running in a Windows-only environment with NTLM authentication.

However, many LDAP applications have clients that run on Operating Systems other than Windows and Windows clients that are not on the same domain as the server. When ADAM is configured for those types of scenarios, it becomes harder to use because it requires a few additional administration settings and some extra code to connect to it.

This article describes how to configure ADAM for regular LDAP communication and build a boilerplate ASP.NET application on top of it. We will use an LDAP client which does not use NTLM authentication, to show that this can be done with any client and on any platform.

At the end of this tutorial, you will have an ASP.NET application capable of authenticating users against a directory:

creating new users:

and displaying the credentials of the active user:

Note: There are subtle differences in how ADAM behaves on Windows Server that is part of a domain, Windows Server that is not on a domain, and Windows XP. This sample is based on ADAM running on Windows XP. On Windows Server, additional steps may be necessary to make this sample work.

Creating an ADAM Directory Instance

After downloading and installing the prerequisites above, create an ADAM directory instance using all of the default settings. Start the ADAM setup wizard by clicking Start->All Programs->ADAM->Create an ADAM instance.

Create a new instance:

The instance name is arbitrary:

The default LDAP port is 389. If this is already taken by another instance, we can just pick a different one:

Create a partition for your application data. By default, ADAM will not create a partition because applications are expected to do that on their own, but our sample doesn't have that need:

Select the installation directory:

Again, to simplify configuration, use Network Service account as the service account:

Add yourself as the initial administrator of the LDAP Instance:

Select which LDIF files to import. These files contain schema definitions and describe what kind of data you will be able to store in your directory instance. You can import more LDIF files later, and for now, all we need is user information:

Click next on the summary page, and sit back while ADAM sets up your LDAP instance:

When this process is done, you will have an empty directory with the MS-User schema installed. You will be able to connect to it only with ADSI and only as yourself. Next, we'll put some users into the directory, and after that, we'll use those users for authentication into the directory itself.

Intermission

At this point, we have to make a configuration change in order to loosen up some locked-down default settings: we will need to enable user password changes over non-SSL connections.

Why do we need to do this? Because we want to create users in ADAM, we want to give those users passwords, and we don't want to set up SSL. If we wanted ADAM to use Windows principals (such as domain users) for authentication to the directory, then we would not have to make this change since ADAM would not be storing passwords (or users, for that matter). But since the very point of this exercise is to decouple ourselves from Active Directory and NTLM, and because we want to avoid the extra complexity of setting up SSL, we will disable the security setting which prevents password operations over non-SSL channels.

While a pain in development and prototyping environments, this secure configuration is something that you should use in production servers. In those cases, you should configure SSL instead of disabling this setting. As a bonus, however, this gives us a chance to introduce one of the indispensable ADAM tools: ADSIEdit.

ADAM uses a separate naming context (also called a "partition") to store settings for that ADAM service instance. Settings here are stored using the exact same mechanism that users, organizational units, computers, and groups will be stored in the other partition we created a few minutes ago.

The setting we are looking for is in the object named CN=Directory Service,CN=Windows NT,CN=Services,CN=Configuration,CN={Configuration Naming Context GUID}. The exact name will vary between ADAM instances, but it's always in the same location.

Right-click on the object named CN=Directory Service and click Properties. You are now looking at all of the attributes of the Directory Service object. The attribute in which we are interested is called dsHeuristics. Contrary to its name, this attribute stores security policy, not store heuristics. Change the value of this attribute to 0000000001001 by selecting it, clicking Edit, typing (or pasting in the value 0000000001001), and clicking OK twice.

Now we have modified the configuration of our ADAM directory service instance so that we can give passwords to users we are about to create. Let's move on!

Creating new ADAM users

At this point, only you can log on to your directory instance, and because your user account is a Windows account:

ADAM won't let you use your network credentials to log on over the generic LDAP interface without SSL and

you wouldn't want to use your network credentials without SSL anyway because someone could sniff them, compromising not just your directory, but also any network resources to which you have access.

We will use use ADSIEdit to create two new users. The first user will be the initial administrator, and the second user will be the service account for the ASP.NET application.

Follow the same steps as above to connect to the directory instance, but this time, we will connect to your new naming context (cn=Sandbox,dc=ITOrg) instead of the Configuration naming context. Note that we are still connecting as the current user, i.e., via NTLM as a Windows user.

Now we need to create a container to store our new (and future) users. Navigate to the CN=Sandbox,DC=ITOrg container, right-click on it, and select New->Object... Select container, and click Next.

Specify a cn (common name) for your soon-to-be administrator. I used the name superuser.

Then, click Next and Finish to create the user.

Note: By default, on Windows Server, when ADAM users are created, they are disabled. To enable a user, change the value of its msDS-UserAccountDisabled attribute to false.

At this point, superuser is not very super. She has no permissions at all in the directory, and we have not given her a password, so she can't even log in. Let's fix the password problem first. Right-click on this user and click Reset Password...

Click OK. Now, our superuser can log in, but can't see or do anything. Let's give her some rights by adding her to the Administrators role, which is in the CN=Roles container.

Right-click on CN=Administrators, and select Properties. Scroll to the member attribute and edit it. You'll see the security principal picker. There are two things of note here:

You can add two types of users - Windows and ADAM.

The Administrators group from the Configuration naming context has already been added to this group. For homework, go back to the Configuration naming context and see who is in the Administrators group there.

Next, we will repeat the steps for creating a user to create our service account user. Instead of using superuser, we use ServiceAccount as the user's cn, with password p@ssw0rd. Note that we are using the service account user to add new entries in our demo, so we need to add her to the administrative group as well.

Voila! We now have an LDAP user with administrative rights who can bind to our directory using plain text passwords and a service account user who can create new users.

Authenticating with LDAP Client.Net

Since we now have a directory which can be accessed by any LDAP v3 client, let's do just that. We have built a boilerplate ASP.NET application that authenticates using Forms Authentication.

Note: Forms Authentication is a platform feature of ASP.NET that simplifies building an application with restricted access to selected resources. Specific knowledge of Forms Authentication is not required to follow the remainder of this article (the link provided above is a good starting point for those who want to know more).

There are two tasks required to determine if a user is allowed to access a resource using Forms Authentication:

Verify that the username and password entered are correct

Verify that the user belongs to a role that has access to the desired resource

We will use LDAP Client.Net to perform these tasks. The Authenticate method below validates the user's credentials:

using (LdapServices.Ldap.Client client = new LdapServices.Ldap.Client())
{
try
{
// Connect to the directory as the user who is trying to
// authenticate. If this fails we know the username
// and/or password is incorrect.
LdapConnectionConfigurationSection config =
LdapConnectionConfigurationSection.Current;

Connect to the directory using the credentials we are trying to authenticate:

Get all directory entries whose distinguishedName matches our username. There should only be one.

LdapServices.Ldap.EntryCollection userEntries = client.Search(
config.BaseDn, "distinguishedName=" + username);
if (userEntries.Count == 1)
{
// Now retrieve the roles to which this user belongs and
// store them in the Application object.

The memberof attribute contains a collection of groups the entry belongs to. Each group is considered to be a role.

// We treat the memberof attribute as the collection of
// roles to which this user belongs.
LdapServices.Ldap.Attribute memberOf = userEntries[0].Attributes["memberof"];
// Copy the values from the memberof attribute into a string
// array.
roles = newstring[memberOf.Values.Count];
for (int i = 0; i < memberOf.Values.Count; i++)
{
string adamGroupName = memberOf.Values[i].StringValue;
// Roles cannot contain commas in ASP.Net, so we are
// mapping commas to periods. The cache contains the
// original role names so we need to transform them
// before handing them off to ASP.Net.
roles[i] = adamGroupName.Replace(',', '.');
}
// Save the user's roles in our cache. We will access this
// cache later during the Application-level
// AuthenticateRequest event.
LdapRoleCache.Current[username] = roles;
}
}
}
// If we could not retrieve the roles for this user then return an
// empty array, indicating that the user is not a member of any roles.
if (roles == null)
{
roles = newstring[] { };
}
return roles;
}

Creating users with LDAP Client.Net

The example above shows how to read data from our directory server. In this example, we will use LDAP Client.Net to create new users, modify their password attribute, and add them to roles.

The createButton_Click method below is the event handler for creating a new user in our sample application:

Comments and Discussions

hey hi,i have tried this demo.so first of all i would like to say thank you very much for this demo.as i said i tried this demo,it runs successfull but when i m trying to login with the username and password which we created in adsi edit its showing that incorrect username and password.and second thing when i look for the link create new user its jump directly to login page so please help me for this what i have to do?? i am using AD LDS instance and ADSI Edit i have installed ldap client also..

hey hi,i have tried this demo.so first of all i would like to say thank you very much for this demo.as i said i tried this demo,it runs successfull but when i m trying to login with the username and password which we created in adsi edit its showing that incorrect username and password.and second thing when i look for the link create new user its jump directly to login page so please help me for this what i have to do?? i am using AD LDS instance and ADSI Edit i have installed ldap client also..

Is it possible to know user password was expired?I can check and calculate the expiry date before the password is expired but I cannot separate between incorrect username/password and password expired after the user password was expired.I am writing code on .net framework 1.1Anybody can help?

This solution goes against what Microsoft is trying to do with the .Net 2 Framework, also what will be introduced when the .Net 3 Framework is released.

The solution attempts to implment a solution using an outdated technique by using a proprietary Membership Provider to comunicate with the LDAP. Within the Microsoft Documentation on MSDN a developer may find a more robust and configurable direction that is far more better.

The real-solution only needed is for the developer to create a LDAPMembershipProvider subclassed from MembershipProvider as outlined in :

Calling this a "bad solution" seems a little harsh. I'd be more inclined to call it a .Net 1.0/1.1 solution. I agree that in .Net 2.0 and later a better solution would be to create an LDAPMembershipProvider class, but the fact is that not everybody is using .Net 2.0 (and 3.0 isn't released yet!)