Getting Started with Net::LDAP
Let's start with a simple example of how to use the Net::LDAP modules. Listing 1 contains code that retrieves basic information from a directory. In this code, I use the new() method to create a new connection to a domain controller (DC) named dc1.
Next, I call the root_dse method to retrieve the desired attributes from the Root DSE, which is a repository of configuration information about the DC. In this case, I want to retrieve the attribute that specifies the domain naming context (NC), so I set the attrs parameter to defaultNamingContext. If you want to retrieve all the attributes in the Root DSE, you set the attrs parameter to an asterisk (*). I then use the get_value() method to return the attribute's value. The value returned for the mycorp.com domain, for example, would be dc=mycorp,dc=com.
Note that Listing 1 doesn't include any authentication code. The Root DSE is available through anonymous access so that applications can have a starting point to dynamically determine some basic information about a directory. To perform more-sophisticated queries, though, you need to include authentication code similar to the code that Web Listing 1 (http://www.winscriptingsolutions.com, InstantDoc ID 27569) shows. In this code, I call the bind() method and specify the distinguished name (DN) and password of the user that I want to authenticate as. The bind() method returns a Net::LDAP::Message object, which I use to determine whether a logon error occurred. If an error occurred, the code() method will return the error code, and the error() method returns the textual error message. To terminate the authenticated session, I call the unbind() method.
Querying AD
If you're familiar with the parameters used for LDAP searching, searching with Net::LDAP is straightforward. You typically use three parameters to perform an LDAP search: base DN, scope, and filter. The base DN parameter specifies the location from which to start the search. The scope parameter specifies the range of the search. You can use one of the following values:
- base—match only the object that the base DN specifies
- onelevel or one—match objects one level down from the base DN (i.e., direct children of the parent), not including the base DN
- subtree or sub—match any object below the base DN, not including the base DN
The filter parameter is a prefix notation string that specifies the criteria against which to match objects. RFC 2254 (http://www.ietf.org/rfc/rfc2254.txt) defines the filter syntax. Web Table 1 contains a few sample search filters. For information and tips about how to use filters to search AD, check out "Understanding ADO Search Filters in LDAP Queries," May 1999, http://www.winscriptingsolutions.com, InstantDoc ID 5282, and the Searching Active Directory Web page (http://msdn.microsoft.com/library/en-us/netdir/adsi/searching_active_directory.asp).
Listing 2 contains code that performs an AD query to search for all users with the last name of Allen. Note the $user variable in the code that callout A highlights. Instead of specifying a user DN, I specify a user principal name (UPN), which is an email-style identifier that users can use to log on. Having users' UPNs match their email addresses is common practice. If your forest DNS name doesn't match the DNS suffix used in your email addresses, you can create additional UPN suffixes by following the steps outlined in the Microsoft article "HOW TO: Add UPN Suffixes to a Forest" (http://support.microsoft.com/?kbid=243629). If you use a UPN, you don't need to specify the entire DN for the user in the code.
As the code at callout B in Listing 2 shows, I use the search() method to perform the query. I pass in the three parameters (i.e., base DN, scope, and filter) that I discussed earlier. I could also pass in a fourth parameter, attrs, to specify the array of attributes to return from the search. If you don't specify an attrs parameter, the search returns all the attributes that have values. If you're performing searches that will return a lot of attributes, you'll want to use the attrs parameter to reduce the amount of data the search returns.
As the code at callout C in Listing 2 shows, I use the entries() method to iterate through the returned search data. This method returns an array of Net::LDAP::Entry objects. For each object, I use the dump() method to print all returned attributes. If you want to access specific attributes, you can use the get_value() method, as I did in Listing 1.
Prev. page
1
[2]
3
next page 
