Building a Bridge to the Active Directory

Introduction

Active Directory of Windows 2000's directory service, allowing organizations to keep and share information about networked resources and users. One significant feature of the Active Directory is that it is LDAP-compliant. Unfortunately, it is still very difficult to access the Active Directory without using the Active Directory Services Interface (ADSI). As a COM component, ADSI is very partial to the Windows operating system.

What if you want to access information in your organization's Active Directory from a host that is not running Windows? One option is to build a piece of middleware (a daemon) to bridge a non-Windows host to the Active Directory. This article describes how to build such a daemon, and how to build a simple client would communicate with that daemon.

XML-RPC and Active Perl to the Rescue

XML-RPC is a mechanism that enables platform-independent and language-independent distributed computing. It serializes function calls and their associated arguments into an XML stream, and transports the stream via the ubiquitous HTTP protocol. Although it might be an over-simplification, XML-RPC provides some of the power of CORBA without the associated pain.

The aim of this article is to walk you through the construction of a daemon that accesses data from the Active Directory using ADSI and passes on this data to other non-Windows clients via XML-RPC. This daemon must, of necessity, run on a Windows host.

A daemon isn't much good unless there is a client with which to communicate. As such, I will also walk you through the construction of a simple client application.

Since Visual Basic is the de facto standard for writing Windows applications, it would seem natural to build the daemon in Visual Basic. However, I'm just not comfortable with Visual Basic, even though I had used it on several projects. Fortunately, ActivePerl from ActiveState has a very well developed COM interface that can be used to interact with ADSI.

Before we get into the details of our Active Directory Daemon and Active Directory Client, here are the links to the source code, so that you can refer to it as we discuss the code and the logic behind it.

Active Directory Daemon: activedirectory_daemon.pl
Active Directory Client: activedirectory_client.pl

The Active Directory Daemon

Our daemon will be able to do the following:

a. Authenticate a user against the Active Directory using the user ID and password. A successful login will result in the salient data (e.g. surname, given name and email address) associated with the user ID being returned.

b. Return the chain of command (the user's immediate boss, the immediate boss's immediate boss, etc).

First, we need to load the modules below, and we also invoke the strict pragma.

  use strict;
  use Win32::OLE;
  use Win32::OLE::Const 'Microsoft ActiveX Data Objects';
  use Frontier::Daemon;

The first two are part of Active Perl, while the third module is available from CPAN.

The AuthenticateUser subroutine authenticates the user against the active directory.

  sub AuthenticateUser {
        my $strUserID       = shift || "someuserid"; 
        my $strUserPassword = shift || "Somepassword1";
        my $strADsPath      = shift || 
           'LDAP://OU=somedivision,OU=somedepartment,DC=someuniversity,DC=edu';
        my $strDomain       = shift || "\@someuniversity.edu";
        my $strAttributeName = "userPrincipalName";
        my $strAttributeValue = $strUserID;

We've assigned default values to some of the scalars above to provide an example of how arguments will be used at various points in the process of querying the Active Directory. There are several ways of interacting with ADSI. In this bit of code, we bind directly to ADSI. Later on, we will show how we can use ADO to bind to ADSI. It is important to note that each method of interacting with ADSI has its own peculiarities.

         my $objNameSpace = Win32::OLE->GetObject ('LDAP:') 
                or die ("Cannot create LDAP object");.
         my $objObjSec = $objNameSpace->OpenDSObject($strADsPath, $strUserID,
   $strUserPassword, 1);
         my %hashAdRecord;

We use Win32::OLE->GetObject('LDAP:') to utilize the LDAP services of ADSI. ADSI supports several directory services such as Novell NDS, and Windows NT4 amongst others. Next we try to access the Active Directory record associated with our user ID and password. The $strADsPath variable specifies what is roughly the domain name of the Windows 2000 forest, and how far down the forest one wants to begin searching. The DC=someuniversity,DC=edu is the LDAP analog of a DNS style domain name i.e. someuniversity.edu. In this example, we want to access the Active Directory starting at the organizational unit somedepartment that is a child of the organization unit somedivision.

We use $objNameSpace->OpenDSObject($strADsPath, $strUserID, $strUserPassword, 1) to access the Active Directory and retrieve the relevant record. The last argument in this subroutine is set to 1. It indicates that we are using an unencryted password.

    if (Win32::OLE->LastError()==0) {
        $refAdRecord =
            GetUserData($strAttributeName,$strAttributeValue,$strADsPath,$strDomain);
    } else {
        %hashAdRecord =('result' => 'failed');
        $refAdRecord = \%hashAdRecord;
    }

We use Win32::OLE->LastError() to ascertain if we have a valid user. Win32::OLE->LastError() is ActivePerl's implementation of Visual Basic's Err.Number. Up to now, everything is pretty straightforward. Deciphering the error codes is a little tricky. Here's how the error logic works. Win32::OLE->LastError() returns a non-zero only if the password is invalid. However, supplying a non-existent user ID will result in zero being returned. As such this bit of code is only good for detecting an invalid password. So, how do we detect a non-existent user ID? Our GetUserData subroutine serves a dual purpose. It not only detects a non-existent user ID, but also returns data from the Active Directory object that is associated with a valid user ID.

We can only return references to the XML-RPC client, so we need to define a scalar variable to which we can assign a reference of the return value. Furthermore, the scalar variable has to be global to the XML-RPC daemon program. In our case, the scalar variable is $refAdRecord. If the user id and password are valid, the reference to the hash returned by the subroutine GetUserData is assigned to the scalar $refAdRecord. On the other hand, if the user id and password are not valid, we insert the 'result' => 'failed' key-value pair to the %hashAdRecord hash variable, and subsequently assign the reference of that hash variable to $refAdRecord.

    $objObjSec->Close;
    $objNameSpace->Close;
    return $refAdRecord;
    }

And, it's time to destroy the ADSI objects that we created earlier.

Now, we move on to the XML-RPC specific bits of the daemon program.

    my $methods = {
    'activedirectory_daemon1.GetUserData' => \&GetUserData,
    'activedirectory_daemon1.GetCommandChain' => \&GetCommandChain,
    'activedirectory_daemon1.AuthenticateUser' => \&AuthenticateUser

};

We declare a hash of subroutines that are accessible to the XML-RPC client. The key of each entry is the name of the method prefixed by an identifier using the dot convention. In our case, we arbitrarily use the name of the daemon file as the identifier. The value part of each hash entry is the de-referenced pointer to the corresponding method. This hash serves as a sort of look up table for requests to methods made at the XML-RPC client. The subroutines besides AuthenticateUser will be discussed later in this article.

    Frontier::Daemon->new(LocalPort => 8080, methods => $methods) 
           or die ("Cannot start HTTP daemon: $!");

At this juncture, we insert the code that fires up the XML-RPC daemon. We do so creating a new Frontier::Daemon instance. The constructor subroutine takes two arguments, each as a key-value pair. The first argument is the port used by the daemon. Since the host may already be running a web server, we'll use port 8080. The second argument is the set of subroutines to be published for use by the XML-RPC client (see above).

Besides the AuthenticateUser subroutine, we've also included a couple of subroutines that retrieve useful information about a user. GetUserData retrieves data like the user's email address, telephone number, etc. Although we call GetUserData from other subroutines (AuthenticateUser and GetCommandChain) within the daemon program, GetUserData may also be called from an XML-RPC client to retrieve data in the Active Directory about any user whose record is accessible. Instead of binding directly with ADSI, in this case, we use ADO to bind with the Active Directory, just so that the retreived data is presented as a record like if the data was retrieved from a relational database.

    sub GetUserData {
        my $strAttributeName  = shift; #could be userPrincipalName, cn etc
        my $strAttributeValue = shift; #could be user ID, cn value etc
        my $strADsPath        = shift; #could be
        # "LDAP://OU=somedivision,OU=somedepartment,DC=someuniversity,DC=edu"
		
        my $strDomain         = shift; #could be "someuniversity.edu"

        if ($strAttributeName eq "userPrincipalName") { 
            $strAttributeValue = $strAttributeValue . $strDomain; s
        }

        my $strProvider = "Active Directory Provider";

        my $strConnectionString = $strProvider;

        my $strFilter = "(" . $strAttributeName . "=" . $strAttributeValue . ")";

        my $strAttribs =
             "userPrincipalName,sn,givenName,cn,department,telephoneNumber,mail,title,manager";

        my $strScope = "subtree";

        my $strCommandText = "<" . $strADsPath . "E>;" . $strFilter . "
        ;" . $strAttribs . ";" . $strScope;

        my $objConnection = Win32::OLE->new ("ADODB.Connection") 
             or die ("Cannot create ADODB object!");

        my $objRecordset = Win32::OLE->new ("ADODB.Recordset")
             or die ("Cannot create ADODB recordset!");

        my $objCommand = Win32::OLE-E<gt>new ("ADODB.Command") 
             or die ("Cannot create ADODB command!");

        my %hashAdRecord;

The above code snippet from the GetUserData subroutine shows what values are assigned to varaibles. This subroutine has four arguments:

a. $strAttributeName

b. $strAttributeValue

c. $strADsPath

d. $strDomain

At this juncture, I'll try to explain how the above variables are used. In our case, we will search the Active Directory for the record that contains a given value for the userPrincipalName. As such, $strAttributeName = "userPrincipalName". If the user ID is jsmith12, then $strAttributeValue = "jsmith12". Alternatively, if we call the GetUserData subroutine from inside the AuthenticateUser subroutine, we declare $strAttributeValue = $strUserID in the AuthenticateUser subroutine.

Since we have used the user ID instead of the full userPrincipalName, we need to append @somedomain to the user ID. Hence we get,

    if ($strAttributeName eq "userPrincipalName") { 
        $strAttributeValue = $strAttributeValue . $strDomain; 
    }

The remainder of the above variable declarations with the exception of %hashAdRecord are required to enable ADO to bind with ADSI. I'll try to explain what's happening there. First we create the following objects:

a. ADODB connection object

b. ADODB Recordset object

c. ADODB Command object

Once these objects have been created, we assign values to selected properties of the ADODB Connection object.

    $objConnection->{Provider} = ("ADsDSOObject");
    $objConnection->{ConnectionString} = ($strConnectionString);

    $objConnection->Open();
    $objCommand->{ActiveConnection} = ($objConnection);

We open the ADODB connection, and assign the ADODB Connection object to the ActiveConnection property of the ADODB Command object.

    $objCommand->{CommandText} = ($strCommandText);

    $objRecordset = $objCommand->Execute($strCommandText) 
        or die ("Cannot execute!");

We assign $strCommandText to the CommandText property of the ADODB Command object, and next, we run the Execute method of the ADODB Command object.The $strCommandText variable is the argument of the Execute method. The value of the $strCommandText is the Active Directory analog of an SQL statement use to query an relational database. $strCommandText comprises four elements:

a. $strADsPath

b. $strFilter

c. $strAttribs

d. $strScope

$strADsPath contains the address of the Active Directory server, and the subset of the total set of records one wishes to search through. The address of the Active Directory server is specified by splitting the domain name up. And the result is DC=someuniversity,DC=edu. The subset of the records in the Active Directory is defined by listing the hierarchy of OUs (Organizational Units) e.g. OU=somedivision,OU=somedepartment. The syntax of the entire $strADsPath string complies with the LDAP RFC 2307 syntax. However, many programming or scripting languages do not seem to support this syntax as yet. Instead, the LDAP RFC 2251 syntax is widely supported.

$strFilter specificies the Active Directory records that we are interested in. In this instance, we are interested in the record where userPrincipalName is equal to someuserid@someuniversity.edu. Hence, this relationship is expressed as

    $strFilter="(" . $strAttributeName . "=" . $strAttributeValue . ")".

$strAttribs contains the list of fields that we want to retrieve from the query. If the query is successful, the result will be returned in ADODB Recordset object, and we can use the methods in the ADODB Recordset objects to retrieve the data.

$strScope="subtree" indicates that the scope of the search is limited to the subtree that has been specified in $strADsPath.

Finally, we turn our attention to getting a list of a user's superiors. This is possible because each user's record in the Active Directory has a manager field that contains the canonical name or CN (amongst other bits of data) of the user's immediate superior. The GetCommandChain subroutine returns an array of a user's superiors. This subroutine takes two arguments:

a. $refAdRecord

b. $strApexTitle

    sub GetManagerString {
        my %hashAdRecord = %$refAdRecord;
        my $strManagerString=$hashAdRecord{"manager"};
        return $strManagerString;
    }

$refAdRecord is the reference of the user's data returned by GetUserData. $strApexTitle is the highest office (e.g. ``Division Manager'') relevant to the search. The logic within this subroutine is quite simple. We make use of the GetManagerString subroutine to retrieve the data that was obtained from the Manager field in the Active Directory.

    sub GetManagerCN {
        my $strManagerString=shift;
        $strManagerString =~ /\bCN=([-_#@%\&\$\*\.a-zA-Z0-9\s]+)/;
        return $1;
    }

Next we use the GetManagerCN subroutine to extract the canonical name from the string returned by the GetManagerString subroutine.

    do {
        $refAdRecord =
        <GetUserData>("cn",$strManagerCN,"LDAP://OU=somedivision,
        OU=somedepartment,DC=someuniversity,DC=edu",
        "\@someuniversity.edu");
        %hashAdRecord=%$refAdRecord;

        $strTitle = $hashAdRecord{"title"};

        push @arrCommandChain, {%hashAdRecord};
        $strManagerString = GetManagerString($refAdRecord);
        $strManagerCN = GetManagerCN($strManagerString); 
    } until ($strTitle eq $strApexTitle);
    $refCommandChain = \@arrCommandChain;
    return $refCommandChain;

A do loop is used to traverse up the management hierarchy till we reach the user record that has a title value which matches the value in $strApexTitle. Over each iteration, we store the hash of the data retreived from the Active Directory into the array @arrCommandChain. Finally, we return the reference to this array as $refCommandChain.

In the next section we will examine how the client uses the XML-RPC mechanism to make requests of the daemon.

The Client in Perl

Since most of the work is done by the active directory daemon, the active directory client in Perl is relatively simple. Because we've used the XML-RPC protocol, the client can be written in various languages, e.g. PHP 4, Python, Java, etc. However we shall continue with Perl to be consistent with the theme of this web site.

As with the daemon, we invoke the strict pragma, and load the Frontier::Client module.

    $strDaemon_url = "http://www.someuniversity.edu:8080/RPC2";

To make use of the subroutines in the Active Directory daemon, we need to provide a url to the daemon. In our case we've assigned the url to the $strDaemon_url variable. As discussed in the Daemon section of this article, we've assigned port 8080 for our daemon's use. The Frontier::Daemon package has also assigned a default virtual directory, RPC2.

Next, we create a new instance of the XML RPC client by passing $strDaemon_url as the value part of the key-value pair of a hash entry.

    $objServer = Frontier::Client->new(url => $strDaemon_url);

Now we can utilize the published subroutines in the Active Directory daemon.

$refAdRecord=$objServer->call('activedirectory_daemon.AuthenticateUser','someuserid',
'Somepassword1','LDAP://OU=somedivision,OU=somedepartment,DC=someuniversity,DC=edu',
"\@someuniversity.edu");

The first argument in the $objServer->call subroutine is the qualified daemon subroutine name. The rest of the arguments are the arguments of the daemon subroutine.

As mentioned earlier, the XML-RPC daemon, can only return references. As such, we need to convert references to hashes, or arrays as appropriate. For example, %hashAdRecord = %$refAdRecord.

Conclusion

XML-RPC is a much more than an effective mechanism to enable distributed computing. We can use it to provide access to platform specific services. In our case, we used XML-RPC to enable a non-Windows host to access data and services in the Active Directory. Furthermore, XML-RPC is simple to implement. I've made forays into distributed computing several years ago by way of Java's RMI and Microsoft's DCOM. In my experience, XML-RPC is by far the cleanest and most fuss-free mechanism of the three.

So, if you're a Perl programmer, and are looking to leveraging off a service that only runs on the Windows platform, give Active Perl and XML-RPC a go. You'll be pleasantly surprised.