Easy Active Directory Scripting for Systems Administrators, Part 1

Many Windows 2000 and Windows NT systems administrators find that developing custom scripts to manage their infrastructure is a radical departure from using traditional graphical toolsets. If you agree, you might be reluctant to learn Windows Script (WS) and supporting technologies such as Active Directory Service Interfaces (ADSI). Although you don't need to write custom scripts to manage your environment, scripting Active Directory (AD) administration tasks is much easier than you might think. To prove my point, I introduce three core interfaces in ADSI—IADsOpenDSObject, IADs, and IADsContainer—in a two-part series about ADSI. I also show you how to use these core interfaces to accomplish 80 percent of the most common AD management tasks.

What Is ADSI?
ADSI is a set of automation-enabled COM objects that let you uniformly manage and manipulate multiple heterogeneous directories. ADSI is Microsoft's primary programmatic interface into AD, and all of Microsoft's graphical AD management tools use ADSI.

Out of the box, ADSI supports Lightweight Directory Access Protocol version 3 (LDAPv3), the NT 4.0 SAM, Novell Directory Services (NDS), and the NetWare Bindery. By virtue of ADSI's LDAP support, ADSI supports a range of LDAP/X.500-based directories, including Win2K AD, Microsoft Exchange Server 5.5, and Site Server 3.0. Although I focus on AD, many of the concepts I discuss in this article apply to the other supported directories.

Because ADSI is automation-savvy, you can use ADSI to write directory management scripts in any COM-compliant scripting environment, including Windows Script Host (WSH), VBScript, JScript, and ActivePerl. ADSI also supports fast, read-only ActiveX Data Objects (ADO) queries through OLE DB.

ADSI is also a set of client-side interfaces, which means you need to install ADSI only on the computer that runs your scripts. You don't need to install ADSI on target domain controllers. Win2K includes ADSI, but you need to download and install it if you plan to run ADSI scripts on NT or Windows 9x computers.

ADSI 2.5 is the current version, which you can download from Microsoft's ADSI Web site (http://www.microsoft.com/adsi). The Web site also has links to ADSI white papers and developer resources such as the ADSI software development kit (SDK).

AD and ADSI Terminology
Before you can effectively use ADSI, you must learn AD scripting terminology. Let's examine some of the terms you need to know.

AD is the Win2K directory service (DS). A DS is a network service that identifies and stores information about all resources on a network and that makes the information accessible to users and applications. AD is a multimaster replicated directory information tree (DIT) named ntds.dit that physically resides in the \%systemroot%\ntds directory on all Win2K domain controllers. You can update any AD replica, and AD will replicate the changes to all other domain controllers.

AD resembles a database in several ways (e.g., AD stores data). However, unlike relational databases that are optimized for insert, update, and delete operations, AD is a hierarchical structure optimized for read operations.

Every Win2K domain controller maintains a writeable directory replica, and each replica consists of a minimum of three partitions (known as naming contexts): the default naming context, the schema naming context, and the configuration naming context. The default naming context stores information about common domain objects (e.g., computers, groups, organizational units—OUs, users). The schema naming context stores the AD schema (which I describe below), and the configuration naming context stores site and subnet configuration information. The core interfaces provide a common and consistent approach to managing objects in all three naming contexts.

The schema is a collection of class and attribute definitions; it defines information that AD can store. A class is similar to a template for an object, and an attribute is an object property (e.g., common name, description, distinguished name—DN). The schema defines attributes that an object must have (i.e., mandatory properties) and additional attributes that an object can have (i.e., optional properties). You can access the schema from within your ADSI scripts to determine an object's mandatory and optional properties. The schema also defines the DIT structure. Objects that can contain other objects are container objects; objects that can't contain other objects are leaf objects.

AD represents network resources as objects. From AD's perspective, an object is a distinct named set of properties and associated values that represent a specific network resource (e.g., a computer named US-E-FN-01, a group named Investors, an OU named Finance, a user named Judy). From a programmatic or scripting perspective, an object is an instance of a schema class definition.

The interfaces in ADSI are the mechanisms you use to modify an object's properties. The term interface isn't unique to ADSI. In the COM programming discipline and vocabulary, an interface is a collection of methods and properties that a COM object exposes. Methods perform some action on an object, and properties describe an object's state. COM objects can expose multiple interfaces. For example, ADSI provides more than 50 interfaces. However, don't let this number alarm you; the three core interfaces let you accomplish many AD tasks.

In summary, ADSI is a set of programmatic interfaces you use to manage AD objects. The interfaces in ADSI provide the methods and properties for creating, deleting, and modifying objects. An object is a collection of properties that represent a network resource. The object's class definition, which the schema stores, governs the properties that make up an object. The schema class defines the object's mandatory and optional attributes. ADSI scripting is the process of using ADSI methods to create and delete objects and to modify properties.

What's in a Name?
Every object in AD has several names. DN and relative distinguished name (RDN) are the primary naming conventions for referencing objects in ADSI scripts. The DN identifies an object's precise location in the DIT based on an attributed name. The RDN is the object's mandatory name attribute. The relationship between the DN and RDN in AD is similar to the relationship between fully qualified paths and filenames in a file system.

Each DN component is an RDN, and each RDN is a string that consists of two parts—a key and a value—that you express as "key=value". The key identifies a valid attribute type, and the value is the attribute's value.

The Internet Engineering Task Force's (IETF's) Request for Comments (RFC) 2253, "Lightweight Directory Access Protocol (v3): UTF-8 String Representation of Distinguished Names," defines the keys and attribute types that you use to construct LDAPv3 DNs. Table 1 lists several of the more commonly used keys and corresponding attribute types.