Business
ADSI provides a powerful directory services interface tool
The objective of ADSI was to provide a powerful, but easy-to-use, development interface for various directory services, such as Windows NT, Novell Directory Services and Lightweight Data Access.
Microsoft introduced Active Directory Services Interface (ADSI) with Windows
2000 as the company prepared to release Active Directory. The objective of ADSI
was to provide a powerful, but easy-to-use, development interface for various
directory services, such as Windows NT, Novell Directory Services (NDS),
Lightweight Data Access Protocol (LDAP), and Active Directory. In this article,
I’ll give you an introduction to how ADSI can be leveraged in your applications.
Let’s begin by considering how you should incorporate directory access beginning
in the design phase of your application.
Incorporate directory access in your design
Directory access needs to be included in an application’s design before any directory can be leveraged in an application. Consider the following points during the design phase:
Working with ADSI
Once you have decided how a directory can be utilized in an application, let’s see how to work with ADSI. The following examples are in Visual Basic working with Active Directory. For information about using ADSI with other languages or directories, see the ADSI documentation on MSDN. ADSI is natively part of Windows starting with Windows 2000. If you want to use ADSI with Windows NT 4, you can download it from Microsoft.
Preparing to access ADSI
Because ADSI is a COM interface, a reference to the ADSI type library needs to be added to your Visual Basic application. To do this, open Project | References and select Active DS Type Library.
Binding to an Active Directory object with ADSI
In order to work with an Active Directory object, you need to bind to it. The code in Listing A shows how to declare an ADSI object and how to bind to an Active Directory user called Test User.
Let’s take a look at the key parts of this example. First, we declare oADUser as an IADsUser object, which is defined in the ADSI type library. Next, we instantiate oADUser as the Test User object by accessing Active Directory using LDAP. Notice how the LDAP query includes the user’s fully qualified distinguished name, where Test User is in the Test OU in the Demo domain.
Accessing object information
Once you have bound to the desired user, you can access the user’s attributes by using the Get method followed by the name of the property to retrieve. Listing B demonstrates how to retrieve common user attributes from the Active Directory.
Modifying object information
You just saw how to access an object’s properties, but what about changing these properties? It will not help you much to retrieve information that isn’t there. The Put method lets you change an object’s attributes. To write the changes to the directory, you must call the SetInfo method. (Note: The security context under which your application is running must have rights to modify the object’s properties. For example, in Listing C, if the application is running under the user’s Active Directory account and the user wants to change his or her telephone number, the user must have rights to change his or her own object’s attributes.)
What attributes are available?
We have demonstrated a few attributes in these examples, but you are probably wondering what attributes you can work with. Objects and attributes in a directory are defined in the directory’s schema. The attributes in the previous examples are default attributes in the Active Directory schema. Various directories have their own way for browsing the available attributes. For Active Directory, the tool ADSI Edit allows you to browse through the Active Directory and look at all the objects in the directory and their associated attributes.
If an object or an attribute that you need is not available, you are not out of luck: Most directories allow you to extend the schema and add customized objects and attributes. However, be very careful about extending the schema. Most organizations with large directories have strict guidelines regarding schema extensions.
Checking group membership
Group membership is an easy way to grant specialized access. Since your directory probably already has security groups or e-mail groups, you can quickly leverage groups for access control in your application. The example in Listing D demonstrates how to check if our oADUser is a member of the Payroll group.
I was surprised how easy it was to check a group membership when I first wrote this code. The keys are the Groups method and the IADsMembers object. The Groups method returns an IADsMembers collection of the groups of which the user is a member.
Searching for users
When we instantiated the oADUser object, we referenced the user with the user’s fully qualified distinguished name. You can query the Global Catalog, a fast-lookup subset of the Active Directory, to retrieve a user’s distinguished name. Also, for this query, you can leverage how Active Data Objects (ADO) and ADSI work together. To do this, you first need to find out the distinguished name of the Global Catalog by querying the Active Directory. Next, you tell ADO to query Active Directory, as shown in Listing E.
Then, you execute the Active Directory query based on a query string. The resulting recordset can be read like a normal ADO recordset. For a complete listing of how to query Active Directory, see Listing F.
Conclusion
ADSI is a powerful tool for working with directories. This article focused on using ADSI to access Active Directory, but you can use it to access many different directories. By utilizing ADSI, you can take advantage of common user information that usually is already stored in a company’s directory. For more information about ADSI, be sure to check out MSDN.
Incorporate directory access in your design
Directory access needs to be included in an application’s design before any directory can be leveraged in an application. Consider the following points during the design phase:
- Is there an existing directory that can be leveraged? Most corporate environments have some directory service currently in their environment. Look into how the existing directory can be utilized instead of adding another directory or user store.
- Does the application require authentication? Directories are built on the idea of authentication and access control. If authentication is necessary for the application, the user may already be authenticated to the directory. Use the directory’s authentication to promote single sign-on.
- Will the application have users with different access rights? Users often have different access in an application. Directory group membership can be used to assign application access rights. By using directory groups for access rights, you can reduce the amount of administration an application requires.
- Will the application need user information that is common among different applications? Applications often need common user information such as address, telephone number, or employee number. Directories provide a central common data store for such information and reduce the amount of data duplication.
Working with ADSI
Once you have decided how a directory can be utilized in an application, let’s see how to work with ADSI. The following examples are in Visual Basic working with Active Directory. For information about using ADSI with other languages or directories, see the ADSI documentation on MSDN. ADSI is natively part of Windows starting with Windows 2000. If you want to use ADSI with Windows NT 4, you can download it from Microsoft.
Preparing to access ADSI
Because ADSI is a COM interface, a reference to the ADSI type library needs to be added to your Visual Basic application. To do this, open Project | References and select Active DS Type Library.
Binding to an Active Directory object with ADSI
In order to work with an Active Directory object, you need to bind to it. The code in Listing A shows how to declare an ADSI object and how to bind to an Active Directory user called Test User.
Let’s take a look at the key parts of this example. First, we declare oADUser as an IADsUser object, which is defined in the ADSI type library. Next, we instantiate oADUser as the Test User object by accessing Active Directory using LDAP. Notice how the LDAP query includes the user’s fully qualified distinguished name, where Test User is in the Test OU in the Demo domain.
Accessing object information
Once you have bound to the desired user, you can access the user’s attributes by using the Get method followed by the name of the property to retrieve. Listing B demonstrates how to retrieve common user attributes from the Active Directory.
Modifying object information
You just saw how to access an object’s properties, but what about changing these properties? It will not help you much to retrieve information that isn’t there. The Put method lets you change an object’s attributes. To write the changes to the directory, you must call the SetInfo method. (Note: The security context under which your application is running must have rights to modify the object’s properties. For example, in Listing C, if the application is running under the user’s Active Directory account and the user wants to change his or her telephone number, the user must have rights to change his or her own object’s attributes.)
What attributes are available?
We have demonstrated a few attributes in these examples, but you are probably wondering what attributes you can work with. Objects and attributes in a directory are defined in the directory’s schema. The attributes in the previous examples are default attributes in the Active Directory schema. Various directories have their own way for browsing the available attributes. For Active Directory, the tool ADSI Edit allows you to browse through the Active Directory and look at all the objects in the directory and their associated attributes.
If an object or an attribute that you need is not available, you are not out of luck: Most directories allow you to extend the schema and add customized objects and attributes. However, be very careful about extending the schema. Most organizations with large directories have strict guidelines regarding schema extensions.
Checking group membership
Group membership is an easy way to grant specialized access. Since your directory probably already has security groups or e-mail groups, you can quickly leverage groups for access control in your application. The example in Listing D demonstrates how to check if our oADUser is a member of the Payroll group.
I was surprised how easy it was to check a group membership when I first wrote this code. The keys are the Groups method and the IADsMembers object. The Groups method returns an IADsMembers collection of the groups of which the user is a member.
Searching for users
When we instantiated the oADUser object, we referenced the user with the user’s fully qualified distinguished name. You can query the Global Catalog, a fast-lookup subset of the Active Directory, to retrieve a user’s distinguished name. Also, for this query, you can leverage how Active Data Objects (ADO) and ADSI work together. To do this, you first need to find out the distinguished name of the Global Catalog by querying the Active Directory. Next, you tell ADO to query Active Directory, as shown in Listing E.
Then, you execute the Active Directory query based on a query string. The resulting recordset can be read like a normal ADO recordset. For a complete listing of how to query Active Directory, see Listing F.
Conclusion
ADSI is a powerful tool for working with directories. This article focused on using ADSI to access Active Directory, but you can use it to access many different directories. By utilizing ADSI, you can take advantage of common user information that usually is already stored in a company’s directory. For more information about ADSI, be sure to check out MSDN.