Active Directory Services Interface in the Microsoft Exchange 5.5 Environment

Microsoft Corporation

November 1997

Abstract

Active Directory Services Interfaces (ADSI) makes it easy to create directory-enabled applications by using high-level tools such as the Microsoft® Visual Basic® programming system, Java®, C, or the Visual C++® development system without having to worry about the underlying differences between the different directory implementations or namespaces. This means that you will be able to build applications that give you a single point of access to multiple directories in your network environment, whether those directories are based on the Lightweight Directory Access Protocol (LDAP) service, the NetWare Directory Service (NDS), or Windows NT Directory Service (NTDS).

Microsoft Exchange 5.5 is a scalable, reliable, and secure messaging platform. Microsoft Exchange 5.5 directory service supports LDAP V3. You can use ADSI with its LDAP provider to manipulate any object in the Microsoft Exchange 5.5 directory. This capability, together with Collaboration Data Objects (CDO), allows Administrators and developers to write powerful collaborative applications or administration tools efficiently. Formerly known as Active Messaging, CDO provides the object interface for manipulating message and calendar objects as well as submission and retrieval of such objects.

This paper helps application developers to write directory-enabled applications using ADSI on top of the Exchange 5.5 directory service.

ADSI and LDAP

ADSI provides a Component Object Model (COM) interface to directory objects. ADSI is built on a provider-based model; the client interacts with the COM interfaces exposed by ADSI while the providers implement the mapping between the underlying directory system and the COM interfaces exposed by the ADSI client. An ADSI application that creates or modifies a user in an NDS directory can be used to create a user in an Exchange 5.5 directory. On the other hand, LDAP is an on-the-wire protocol for directory access. So an LDAP application is restricted to accessing directories that expose the LDAP protocol.

Given that ADSI is a set of COM objects, it can easily be used within Visual Basic or Java script to directory-enable your Web-based applications. It is somewhat harder to do that with a "C"-based LDAP API.

ADSI and ADO

ActiveX® Data Objects (ADO) is used to perform searches within the directory and have the results presented in a tabular form. ADSI, on the other hand, is used to modify entries in the directory. Often you use ADO to search for one or more objects then iterate through the result set and modify the objects of interest. The use of ADSI and ADO is illustrated in the samples below.

The Microsoft Exchange Directory Schema

In order to write applications using ADSI on the Exchange directory, you must have an understanding of the directory schema. The schema defines the available object classes in the directory, the relationship between the object classes, the attributes on each object class, and specific characteristics of the attributes and classes. The Exchange Administration program allows you to view the Exchange directory schema. To do this:

1. Run Exchange Admin in RAW mode (admin /r).
   
   
2. Select View.Raw Directory from the menu.
   
   
3. Select Schema from the window on the left.
   
   
4. Double click the object that represents the attribute or object class of interest from the window on the right.

There are three properties that are significant in ADSI support:

Heuristic

The heuristic property can be interpreted as follows:

By taking note of heuristics, you can determine the visibility of particular attributes. For example, a heuristic value of 3 means the attribute is not replicated between sites and is visible by anonymous LDAP clients.

A heuristic value of 11 means the attribute is an operational attribute and is visible to authenticated LDAP clients.

Operational attributes (attributes with a heuristic bit 3 set) are not visible through ADSI even though it is possible to set their values. To get the value of an operational attribute, you must use an ADO query as described in the example below.

Caution   Changing bit 0 of the heuristic property could cause directory replication to stop. You should not change this bit of the heuristic property of an attribute.

ACL

The ACL property determines what rights a user needs to modify the attribute. The ACL property value definitions are:

Description

Description determines the LDAP name of the attribute or class.

Caution   Changing the LDAP name causes interoperability problems.

Commonly Used Object Classes

The following section contains object classes commonly used as well as their most significant attributes. The columns in the tables below should be interpreted as follows:

Mail-Recipient (person) Object Class

The Mail-Recipient object class is exposed as the “person” object class through LDAP. This object class is inherited by all object classes to which mail can be sent—for example mailbox, custom-recipient, distribution-list, and public-folder. 

It should be noted that this object class is abstract. Thus you cannot create an instance of this object class. It is defined only so that other object classes in the directory can inherit its attributes.

The following table describes the commonly used attributes on the person object class:

Mailbox (organizationalPerson) Object Class

The Mailbox object class is exposed as the “organizationalPerson” object class through LDAP. This object class represents an object that contains mail storage in the Microsoft Exchange system. One critical attribute on a Mailbox object is the Assoc-NT-Account, which contains the Security Identifier (SID) of the NT account that has access to the mailbox.

Custom-Recipient (custom-recipient)

The Custom-Recipient object class is exposed as “custom-recipient” object class through LDAP. This object class contains all the attributes of the organizationalPerson object class noted above with the exception of mailPreferenceOption. The Custom-Recipient object class does contain an additional mandatory attribute with the following properties

Distribution-List

The Distribution-List object class is exposed as the groupOfNames object class through LDAP. Its attributes are:

Retrieving Incremental Changes through ADSI

In certain applications, such as a directory synchronization service, it is important to get incremental changes out of the Exchange directory. This can be achieved by performing searches on the following operational attributes, which exist on every object in the Exchange directory:

By keeping track of USN-Changed/Created or When-Changed/Created, an application can get at changes in the Exchange directory since the last time it polled for changes.

These attributes are available to any authenticated user.

Retrieving Deleted Objects through ADSI

Just as important as retrieving incremental changes from the Exchange Directory is the capability of retrieving deleted objects. This can be done by binding using clear text authentication with “,cn=admin” appended to the user’s DN (e.g. dc=domain,cn=jsmith,cn=admin).

When a client is authenticated with the Exchange Directory with “,cn=admin” in the user’s DN, it will be able to query for an operational attribute called “is-deleted”. This attribute is a Boolean attribute that indicates whether the object has been deleted or not. A deleted object is referred to as a tombstone. Tombstones exist for a period of time indicated by the “Tombstone lifetime” parameter on the DS Site Configuration property page in the Microsoft Exchange Admin program. By default, the “Tombstone lifetime” is set to 30 days. If your application depends on getting deletions out of the Exchange Directory you should make sure that it runs within the “Tombstone lifetime” period.

ADSI Samples

This section contains a couple of ADSI samples that demonstrate authentication against the Exchange directory, searches for objects using ADO, and manipulation of objects using ADSI.

Distribution List manager

The code below will create a distribution list and populate it with the users found via an ADO query:

Option Explicit

Dim strDisplayName    ' DL's Display name
Dim strAliasName      ' DL's Alias name
Dim strDirectoryName  ' DL's Directory name
Dim strUserName       ' User's logon name and domain
Dim strPassword       ' User's domain password
Dim strServer         ' Exchange server name
Dim strOrganization   ' Exchange Organization
Dim strSite           ' Exchange Site
Dim strRecipientsPath ' ADsPath to the Recipients Container
Dim strMSPrivMDBPath  ' ADsPath to the MS Private MDB
Dim objRecipients     ' Recipients Container object
Dim objMSPrivMDB      ' MS Private MDB object
Dim objNewDL          ' new distribution list object
Dim strMail           ' mail address of the MS Private MDB object
Dim intPos            ' numeric position of the '@' in an SMTP address
Dim strSMTPExt        ' SMTP domain type (ie. com, org, etc...)
Dim strSMTPAddr       ' new DL's SMTP address
Dim aOtherMailbox(1)  ' other addresses created (ie. MSMail, CCMail)
Dim strx400Addr       ' new DL's X400 address
Dim objMyIADs         ' ADSI object

' used by the PutEx method to set a muti-valued property
Const ADS_PROPERTY_UPDATE = 2

strDisplayName = "BellevueDL"
strAliasName = "BellevueDL"
strDirectoryName = "BellevueDL"

strUserName = "dc=redmond, cn=v-sparke"
strPassword = "password"

strServer = "sparker1"
strOrganization = "16"
strSite = "3081"

Set objMyIADs = GetObject("LDAP:")

The following code determines the domain address extension by looking at the ‘'mail' property of the well-known “Microsoft Private MDB” object:

strMSPrivMDBPath = "LDAP://" + strServer + "/cn=Microsoft Private MDB,cn=" + strServer + ",cn=Servers ,cn=Configuration,ou=" + strSite + ",o=" + strOrganization

This application uses the OpenDSObject method to access directory objects. The user's logon domain, name and password are passed as parameters. The value of 0 means that the ADSI LDAP provider will do a simple bind:

Set objMSPrivMDB = objMyIADs.OpenDSObject(strMSPrivMDBPath, strUserName, strPassword, 0)
objMSPrivMDB.GetInfo
strMail = objMSPrivMDB.Get("mail")
intPos = InStr(strMail, "@")
strSMTPExt = Mid(strMail, intPos, Len(strMail))

The code below builds SMTP, MSMAIL, CCMAIL, and X400 addresses. "US" is hardcoded into the X400 address. The textEncodedORaddress property of the MS Private MDB object may be parsed to determine the correct X400 addressing scheme:

strSMTPAddr = replace(strAliasName, " ", "") + strSMTPExt
aOtherMailbox(0) = CStr("MS$" + strOrganization + "/" + strSite + "/" + strAliasName)
aOtherMailbox(1) = CStr("CCMAIL$" + strAliasName + " at " + strSite)
strx400Addr = "c=US;a= ;p=" + strOrganization + ";o=" + strSite + ";s=" + strAliasName + ";"

strRecipientsPath = "LDAP://" + strServer + "/cn=Recipients,ou=" + strSite + ",o=" + strOrganization
Set objRecipients = objMyIADs.OpenDSObject(strRecipientsPath, strUserName, strPassword, 0)

This code creates the distribution list:

Set objNewDL = objRecipients.Create("groupOfNames", "cn=" + strDirectoryName)

Note that in VBScript, it is necessary to CStr() string values to properly format the data for ADSI:

objNewDL.Put "cn", CStr(strDisplayName)
objNewDL.Put "uid", CStr(strAliasName)
objNewDL.Put "distinguishedName", CStr("cn=" + strAliasName + ",cn=Recipients,ou=" + strSite + ",o=" + strOrganization)
objNewDL.Put "mail", CStr(strSMTPAddr)

This code creates a multivalued property. In VBScript you have to de-reference the array by using parentheses:

objNewDL.PutEx ADS_PROPERTY_UPDATE, "otherMailbox", (aOtherMailbox)

objNewDL.Put "Report-To-Originator", True
objNewDL.Put "Report-to-Owner", False
objNewDL.Put "Replication-Sensitivity", CInt(20)
objNewDL.Put "rfc822Mailbox", CStr(strSMTPAddr)
objNewDL.Put "textEncodedORaddress", CStr(strx400Addr)
objNewDL.SetInfo

Response.Write "DL Created Successfully!<BR><BR>"

The code below will find mailboxes in the Exchange directory services whose "City" property matches the search criteria. The ADSI LDAP name for "City" property is "l."

Dim objADOconn          ' ADO connection object
Dim strADOQueryString   ' ADO query string
Dim objRS               ' recordset object
Dim strCriteria         ' value used to search the directory tree

strCriteria = "Bellevue"

Set objADOconn = CreateObject("ADODB.Connection")
objADOconn.Provider = "ADSDSOObject"
objADOconn.Open "ADs Provider"
strADOQueryString = "<LDAP://" + strServer + ">;(&(objectClass=organizationalPerson)(l=" + strCriteria + "));cn,adspath;subtree"
Set objRS = objADOconn.Execute(strADOQueryString)
If Not objRS.EOF Then
  While Not objRS.EOF
    objNewDL.Add objRS.Fields(1).Value
    Response.Write objRS.Fields(0) + " added :)<BR>"
    objRS.MoveNext
  Wend
Else
  Response.Write "No mailboxes were added to the DL :(<BR>"
End If
objRS.Close

Phone List

This code will modify the Phone number property of a mailbox. All users have access to modify this property on their mailbox by default.

This following code will cause the browser to pop up a user-identification dialog box. The IIS server's password authentication must be set to "Allow Anonymous" and "Basic (Clear Text)" only. This way, the browser will be able to use the correct security context when using the GetObject method.

Dim strAT ' Authorization Type information

strAT = Request.ServerVariables("AUTH_TYPE")
If InStr(1, "_BasicNTLM", strAT, 1) < 2 Then
  Response.Buffer = True
  Response.Status = ("401 Unauthorized")
  Response.End
End If

Dim strMailboxPath        ' ADsPath to the user's mailbox
Dim strServer             ' name of the Exchange 5.5 server
Dim intPosPrefix          ' numeric index used used to build ADsPath to schema object
Dim intPosSuffix          ' numeric index used used to build ADsPath to schema object
Dim strPrefix             ' prefix string used to build ADsPath to schema object
Dim strSuffix             ' suffix string used to build ADsPath to schema object
Dim strPathToSchemaObject ' ADsPath to the schema object
Dim objMailbox            ' mailbox object
Dim strNewPoneNumber      ' value of the new phone number

Function isUserEditable(strSchemaObjectPath)
  Dim objSchemaObject     ' schema object
  Dim intValue            ' value of the Access-Category property

  Set objSchemaObject = GetObject(strSchemaObjectPath)
  intValue = objSchemaObject.Get("Access-Category")
  If intValue = 2 Then    ' user may modify the mailbox property
    isUserEditable = True
  Else                    ' the value was 0, 1, or 3
    isUserEditable = False
  End If
End Function

This procedure will modify the property of an object that contains a string value. To set a property to the empty string, you must remove it from the object:

Sub ModifyProperty(strNewValue, strADsProperty)
  On Error Resume Next

  If Len(strNewValue) <> 0 Then
    objMailbox.Put strADsProperty, CStr(strNewValue)

  Else  ' The new value is empty
    objIADs.Get (strADsProperty)

If the property doesn't exist on the object, an error will be generated using the Get method:

    If Err.Number = 0 Then ' the property exists on the object and must be removed
      objMailbox.PutEx ADS_PROPERTY_CLEAR, strADsProperty, CStr(" ")
    End If
    Err.Clear
  End If
End Sub

Const ADS_PROPERTY_CLEAR = 1  ' used by the PutEx method to clear a property from an object

strMailboxPath = "LDAP://SPARKER1/cn=SParker,cn=Recipients,ou=3081,o=16"
strServer = "sparker1"
strNewPoneNumber = "(425) 882-8080 x 13882"

intPosPrefix = InStr(strMailboxPath, "/cn")
intPosSuffix = InStr(strMailboxPath, "ou")
strPrefix = Mid(strMailboxPath, 1, intPosPrefix - 1) + "/cn="
strSuffix = ",cn=Microsoft DMD," + Mid(strMailboxPath, intPosSuffix, Len(strMailboxPath))

strPathToSchemaObject = strPrefix + "Telephone-Office1" + strSuffix
If isUserEditable(strPathToSchemaObject) Then
  Set objMailbox = GetObject(strMailboxPath)
  ModifyProperty strNewPoneNumber, "telephoneNumber"
  objMailbox.SetInfo  ' save the object information
  Response.Write "Phone number modified successfully :)<BR>"
Else
  Response.Write "You don't have permissions to modify your phone number :(<BR>"
End If
%>

Limitations of ADSI

ADSI cannot yet manipulate Access Control Lists (ACLs), which contain security information about which user has rights on a certain object. It cannot get the Windows NT Security Identifier (SID), the binary representation of a user’s account name, and thus cannot set the bits necessary to create the user’s rights. Thus developers cannot create a functional Mailbox object completely with ADSI, since a mailbox object requires the NT account SID in the Assoc-NT-Account attribute as well as the correct security rights on the mailbox object in the NT-Security-Descriptor attribute. The capability to manipulate ACLs is expected in a future release.

Enhancing Exchange with ADSI

Because ADSI frees developers from involvement in directory-specific APIs, it makes administrative functions more flexible. For example, a directory-specific API might require an administrator to key in a security password and domain on an Active Server Page, exposing it to risk. By contrast, ADSI objects force the Web browser to prompt the administrator.

Once a developer learns the ADSI convention, it is easy to write an LDAP path name and specify the class and property of an object. Exchange 5.5 will bring up an ADSI page that allows developers to type in the appropriate Exchange Server, pull it from the registry and populate the server field. By using ADSI objects, they can develop a variety of easy-to-use applications. For example, developers can write a Web-server script that allows a browser to look up details of users represented in different directories. Or, they can create a distribution list manager that creates distribution lists from users in different directories. Or, they can specify access privileges for printer queues. With the flexibility of ADSI, the possibilities are manifold.

Conclusion

Designed to provide a single, consistent open set of interfaces for heterogeneous directory services, ADSI provides an important common ground in today’s far-flung enterprise networks and intranets. Furthermore, it enables Exchange administrators and developers to write applications and to port Exchange Directory Access Programming Interface (DAPI)-based applications to ADSI. These applications will run in Exchange 5.5 environments and with minimal or no changes can run on top of the Windows NT 5 Active Directory. Exchange developers and administrators can thus more easily keep pace with changes while developing directory-enabled applications more efficiently.

For More Information

Visit the following Web sites for more information:

• Internet drafts, including the LDAPV3-protocol: ftp://ds.internic.net/internet-drafts/
  
  
• ADSI and Windows NT 5 Active Directory: http://www.microsoft.com/ntserver/default.asp
  
  
• Information on Exchange 5.5: http://www.microsoft.com/exchange/default.asp