Washington, September 15-18, 1999 – London, November 21-24, 1999

Using ADSI in ASP

Introduction

Active Directory Service Interfaces is the Microsoft strategic set of directory access interfaces. ADSI abstracts the capabilities of different directory services from different network vendors and presents a single set of directory service interfaces for managing resources. ADSI focuses on ease of use for cross-language development. Any COM compliant language such as Visual Basic, Java, and Visual C++ can be used with ADSI.

This article explains the various pieces that make up ADSI, demonstrates how to use them, and provides solutions to common problems found in ASP applications. All code examples in this article are presented in Visual Basic Script.

Adam Cartwright Adam S. Cartwright is a Principal Consultant for Software Spectrum in Denver Colorado. As an Internet specialist, Adam has designed and developed many ASP based applications that take advantage of advanced database and directory services. Adam specializes in advanced Internet technologies such as DHTML, ASP, ADSI, and XML. As a Microsoft Certified Professional, Adam holds Microsoft Certified Systems Engineer and Microsoft Certified Solutions Developer certifications, as well as being a recognized expert on ASP, XML and ADSI technologies. Being a native of Salt Lake City, Utah, Adam enjoys the mountains, golfing, driving fast cars, and spending time with his wife and two small children.

ADSI Concepts and Structure

The AdsPath

An ADsPath uniquely represents each object in a directory service. ADsPath strings are synonymous to COM display names in that they uniquely identify the location and names of objects within the directory service. While an ADsPath regardless of directory service implementation represents every object, the exact syntax and structure of the ADsPath varies per provider.

LDAP://exchangeserver/o=Microsoft/ou=msftsite/ou=recipients/ou=mailbox

LDAP://MyDomain.Microsoft.com/CN=TopHat,DC=Dev,DC=MSFT,DC=COM

WinNT://MyDomain/UserAccount

NDS://MarsTree/O=MARS/OU=MARTIANS/CN=MyFavorite

Connecting/Binding to an Object

To bind to an object, use the GetObject. This function is run in the security context of the currently logged on user.

Set X = GetObject("LDAP://cn=jsmith,cn=users,dc=wrox,dc=com")

In order to bind to an object with different credentials than the currently logged on user, use the IADsOpenDSObject interface.

Set ds = GetObject("LDAP:")

Set X = ds.OpenDSObject("LDAP://cn=jsmith,cn=users,dc=wrox,dc=com", "cn=Administrator,cn=users,dc=wrox,dc=com", "password", 0)

Enumerating Children in a Container

After binding to an object, which is a container, you can enumerate its children using the Visual Basic For Each…Next statement. It is important to note that only immediate children are enumerated using this call. If you want to list all of the objects of a subtree, you must use the Search function described later.

Set cont = GetObject("WinNT://MyDomain")

For Each obj in cont

  Response.Write obj.Name

Next

Getting an Objects Attribute

To get an attribute of an object, you can use the IADs::Get method.

fname = usr.Get("fullName")

Because the "get" method is the default method of the IADs object, you can use a shortcut to get an attribute.

fname = usr.fullName

Put Objects Attribute

Setting an attribute on an object is as simple as passing the attribute name and value.

usr.Put "givenName", "Jane"

usr.Put "sn", "Doe"

As with the "get" method, you can use the same shortcut for setting attributes.

usr.givenName = "Jane"

usr.sn = "Doe"

Creating an Object

To create an object, you use the IADsContainer::Create method. There are three steps: 1) Bind to an object container, 2) Create the object, and 3) Fill mandatory properties.

Set ou = GetObject("…")

Set usr = ou.CreateObject ("user", "cn=jsmith")

usr.Put "samAccountName", "jsmith"

usr.Put "userPrincipalName", jsmith@wrox.com

usr.setInfo

Notice the use of "setInfo" in the last statement. This is necessary to commit the object to the directory. Up until that point the object has been created in memory only. Once setInfo is called, the object is written permanently to the directory service.

Deleting an Object

You use the IADsContainer::Delete method to delete an object. Note: traditionally, directory services do not support any type of un-delete method, thus one should use the delete method with extreme care.

Set ou = GetObject("…")

ou.Delete "user", "cn=jsmith"

Renaming an Object

It is possible to rename an object in the directory using the IADsContainer::MoveHere method.

ou = GetObject("…cn=johnd")

ou.MoveHere (usr.ADsPath, "cn=jdoe")

Because the ADsPath remained the same in the above example, the object will be renamed with the new "cn" attribute value.

Moving an Object

To move an object you also use the IADsContainer::MoveHere method.

ou = GetObject("…")

ou.MoveHere (usr.ADsPath, 0)

Contrasted to using the "MoveHere" method to rename an object, by supplying a new ADsPath value will move the existing object to the new ADsPath location. Additionally, you must pass a "0" as the second parameter indicating that the same "cn" attribute is to be used.

Searching

Searching is one of the most fundamental operations in the directory as directory services are optimized for reading and searching. ADSI supports two methods of searching: ADO/OLE-DB and IDirectorySearch. The IDirectorySearch interface may only be accessed through Visual C++, so we'll focus on the ADO/OLE-DB method.

There are two dialects supported by ADO/OLE-DB: SQL and LDAP. The SQL dialect is simply Structured Query Language syntax, and is very easy to use. The LDAP dialect is a little more complicated, but can sometimes provide greater granularity in your search.

SQL query: SELECT attlist FROM 'ADsPath' WHERE conditions ORDER BY attlist

SQL query: SELECT cn, ADsPath FROM 'LDAP://dc=arcadiabay,dc=com' WHERE objectCategory='person' AND sn='H*' ORDER BY sn

Distributed Query

ADSI supports SQL 7.0's Distributed Query technology that allows heterogeneous joins across different OLE-DB data sources.

Scenarios:

Ø        Join data from SQL server to Active Directory.

Ø        Update data from AD to SQL server.

Ø        Join data from Active Directory to Index Server.

Ø        Join data from Exchange Server to SQL Server.

Filtering Objects

ADSI allows you to filter objects in a container. This is useful when you only want to return specific types of objects, and improves performance saving you from checking each one individually.

Set dom = GetObject("WinNT://MyDomain")

dom.Filter = Array("user", "group")

For Each obj in dom…

ADSI in ASP

Because ADSI is so easily scriptable, it is a perfect technology for use in ASP. ADSI allows you to get at information only previously available by custom server components.

Some common challenges faced in ASP include the following:

Retrieving the NT Security Groups a User Belongs To

Often it would be useful to know which NT groups a user belongs to in order to provide a more "dynamic" application. Using ADSI you can easily get at this information. Consider the following example:

Set UserObj = GetObject("WinNT://DomainName/UserName")

For Each GroupObj In UserObj.Groups

…GroupObj.Name…

Next

Changing a Users Password

One of the simplest things to do, but sometimes tricky for users with only web access, is to change their own password. Fortunately, ADSI provides a simple change password method to accomplish this:

Set UserObj = GetObject("WinNT://ComputerName/UserName")

UserObj.ChangePassword "oldpassword", "newpassword"

UserObj.SetInfo

Finding a Alias in Exchange Server

Sometimes it is handy to be able to search Exchange for a specific alias, either to see if it exists or to get more information about it. The following ADO query accomplishes just that:

Set objCon = Server.CreateObject("ADODB.Connection")

Set objCom = Server.CreateObject("ADODB.Command")

objCon.Provider = "ADsDSOObject"

objCon.Open "Active Directory Provider"

Set objCom.ActiveConnection = objCon

strADsPath = "LDAP://exchsvr/o=MyOrg/ou=Recipients"

objCom.CommandText = "SELECT ADsPath, uid, givenName, sn FROM '" & strADsPath & "' where uid='jdoe'"

objCom.Properties("searchscope") = ADS_SCOPE_SUBTREE

Set objRS = objCOM.Execute

Accessing Site Server's Active User Objects

Microsoft Site Server's Personalization and Membership system provides a very slick way of storing session and other user specific information, and sharing it across a web farm. The following example shows how to access the AUO object:

Set objAUO = Server.CreateObject("Membership.UserObjects")

strName = objAUO.givenName & " " & objAUO.sn

Summary

ADSI is a perfect technology to accompany ASP. Using ADSI you can access various directory services from right inside your ASP application. Because ADSI hides the complexities of the actual directory services, you only need to learn one syntax in order to use multiple providers.

---