Easy Active Directory Scripting for Systems Administrators, Part 1

You can apply the same basic steps to other objects in the directory. For now, let's take a closer look at the core interfaces in ADSI and apply these steps in a functional script. I use easyadsi.vbs as a reference for the discussion that follows and examine the core IADsOpenDSObject interface. Listing 1 shows the portion of the script that completes the first four steps for creating a new user object. You can download complete listings from the Windows 2000 Magazine Web site at http://www.win2000mag .com/. (Enter 9168 in the InstantDoc ID text box, and click the 9168.zip file.)

Connecting to AD
Connecting is the first step to communicating with AD; connecting to an object is known as an LDAP bind request. Binding is the point in your ADSI script at which credential authentication occurs. ADSI's in-process LDAP providers (adsldp.dll and wldap32.dll) create and return a reference to a specified object (e.g., domain, OU, group, user, printer, service, share, site, schema class).

You use VBScript's GetObject function to bind to an AD object. The string you pass to GetObject is the ADSI LDAP path that identifies the target object. To bind to an object, you can use several approaches, which are based on the syntax of the LDAP path you provide. You must begin ADSI LDAP paths with "LDAP:". You can follow the string with optional elements, as the examples in Figure 2 show.

The mandatory "LDAP:" prefix is the programmatic identifier (ProgID) for ADSI's LDAP provider. ADSI ProgIDs identify the ADSI provider DLL through which your script communicates with the underlying directory. ADSI ProgIDs are case sensitive, so you must always use all caps for the "LDAP:" prefix. The remainder of the ADSI LDAP path isn't case sensitive.

Optional LDAP path elements include the target server's name, IP address, LDAP port number, and DN. The elements you append to the "LDAP:" prefix determine how ADSI binds to AD.

Server-based binding occurs when you supply a target server name or IP address as part of the LDAP path, as the examples in Figure 3 show. You should avoid binding to a hard-coded server name or IP address because your script will fail if the server is offline. You can specify the LDAP port number if your DS is listening on a port other than the default LDAP port (port 389). However, you don't need to worry about AD listening on another port because Win2K domain controllers reserve port 389 for AD.

Serverless bind requests remove the dependency associated with LDAP paths that contain hard-coded server names, which is why using serverless paths is advisable. When you omit the target server name or IP address, ADSI issues a call to a new Win32 API—DSGetDCName—that queries DNS to locate a domain controller in the domain that the current user is logged on to. ADSI attempts to locate and connect to a domain controller at the workstation's local site based on the IP subnet. If ADSI can't locate a site domain controller, ADSI uses the first directory server that responds.

Serverless LDAP paths commonly include a DN that identifies the target object. In the bind request that callout A in Listing 1 shows, I bind to the Finance OU that resides in the acme.com domain. The string value in the strContainer variable provides this location.

Figure 4 shows bind requests that contain other forms of serverless LDAP paths. In the first example in Figure 4, I explicitly bind to the defaultNamingContext (where user, computer, group, and OU objects reside) of the acme.com domain. In the second example, I bind to a specific user object. The third example is as a DN-less bind request. In this type of request, ADSI binds to the Root Directory Service Entry (rootDSE) object (a special LDAPv3 object) and uses the rootDSE defaultNamingContext property to bind to the DIT's root. The result is identical to that of the first example, but the DN-less approach is independent of a specific domain.

You can also explicitly bind to the rootDSE object. Introduced in LDAPv3, rootDSE resides at the top of every domain controller's DIT. Unlike the DN-less (i.e., "LDAP:") approach, in which rootDSE returns only the DN for the defaultNamingContext, binding directly to rootDSE lets you access all the directory server information that the rootDSE object provides. You'll find the DNs for all the directories' naming contexts in this information. As Listing 2 shows, I use the rootDSE defaultNamingContext, schemaNamingContext, and configurationNamingContext properties at callouts A, B, and C in Listing 2 to bind to the root of each naming context and echo the top-level objects. RootDSE provides the most reliable and robust mechanism to bind to a directory.

Thus far, I've relied on my current credentials to authenticate my bind request. Although this approach is the preferred authentication method, you might encounter situations in which you need to provide alternative credentials or specify the authentication type required. ADSI's IADSOpenDSObject interface exposes the OpenDSObject method that employs user-supplied credentials to bind to an object. OpenDSObject accepts four parameters, which Table 2 lists.

Callout B in Listing 1 illustrates how to use OpenDSObject in lieu of the current user's credentials. Replace the code at callout A in Listing 1 with the code at callout B in Listing 1 to use OpenDSObject. You must use

Set oRoot=GetObject("LDAP:") 

to obtain a reference to the LDAP provider before you call OpenDSObject. You can use DN, User Principal Name (UPN), downlevel SAM account name (pre-Win2K), or Anonymous as your username.

Binding Tips
ADSI provides a great deal of flexibility in terms of binding to AD objects. As you begin developing your own ADSI scripts, keep the following tips in mind:

1. Use your current credentials whenever possible.
2. Never hard-code passwords in your scripts. If you must use a password, prompt the user or retrieve the password from a secure location, store the password in a temporary variable, and destroy the variable's contents immediately following the bind request.
3. Use rootDSE when your script calls for binding to the current domain's root.
4. Avoid hard-coding server names in LDAP paths.
5. Bind to container objects to create, move, and delete objects in the container.
6. Bind to a leaf object to modify the object's properties.

In my next ADSI article, I'll examine the two remaining core interfaces in ADSI— IADs and IADsContainer. In the meantime, try connecting to some objects in your directory. For some real fun, fire up Network Monitor and try several different binding methods. The worst that can happen is that you'll learn more about the role DNS plays and about LDAP protocol mechanics.