Class UserObjects

COM Class Identification

The following values identify this COM class.  These values are set in the registry with the Site Server 3.0 product installation.

COM Class Logical Name

UserObjects

Programmatic Identifier

Membership.UserObjects.1

CLSID

77BD6B36-B1B5-11D0-BBD6-00C04FB615E5

Type Information

Type Library location

"c:\microsoft site server\bin\p&m\auo.dll"

IDL file

 AUO.idl (comes with this SDK)

Type Library name

 AUO 1.0 Type Library

Class Overview

This class defines a Component Object Model (COM) object that programmers and scripters can use to easily store and retrieve information about users.

AUO Providers

An object of this class relies on a set of configuration entries referred to as Active User Objects (AUO) providers to define the specific access details to information about users.  When configuring the AUO, administrators supply an instance-unique AUO alias to identify the specific AUO provider configuration.  Programmers and scripters may then access the targeted information using this alias. 

Each AUO provider configuration is comprised of information used to bind to a specific COM object that implements the Active Directory Service Interfaces (ADSI).  It is specifically through these COM objects that all management and transport of data occurs. In the simplest case, the AUO is simply a set of "helper" COM objects that assist programmers in gaining access to a particular ADSI implemented COM object with a minimum of fuss.  Further, the ADSI interfaces define only general information about the expected behavior of ADSI implemented COM objects, allowing developers to implement the details in any fashion they so desire.  The AUO system makes no assumptions about the actual implementations used COM objects that implement the ADSI interfaces.  The AUO objects, specifically UserObjects and SchemaObjects, are strictly clients of the bound ADSI COM objects, or fetch and return interfaces on ADSI objects.

The Default Provider

The one provider definition that has special status is the default AUO provider.  Programmers or scripts need not specify this provider in programs or scripts directly.  Instead, they may interact with the UserObjects or SchemaObjects objects as if they were the corresponding ADSI object.  However, if an interface on the actual ADSI object is required by an application, it can always be requested by the IUserObjects::GetObjectEx (or IADsContainer::GetObject implemented by the UserObjects object) method with the empty string "".  This provider configuration normally points to user data in the appropriate Membership Directory service and works in conjunction with the Membership Server attribute or property cache to provide high-speed access and synchronization.  The IADs and IADsContainer interface implemented by the UserObjects coclass provides this service only for the ADSI object specified by the configuration of the default AUO provider. 

The Active Directory Service Interfaces (ADSI)

The UserObjects coclass relies on other COM objects that implement the Active Directory Service COM Interfaces (ADSI) for all connectivity to data stores.  (I.e. directory services, databases, etc)  As its name suggests, an instance of the UserObjects coclass acts as a collection of ADSI COM objects that implement ADSI interfaces and provide connectivity services.  However, it also simultaneously masquerades as the ADSI object defined by the default AUO provider and the current user.  All invocations made on the UserObject IADs interface are delegated to the actual ADSI COM object.  If the Membership system is configured to have the AUO check the Membership service property cache, the Get/GetEx methods implemented on the UserObjects object first check there for a requested attribute.  If this feature is disabled, the call goes directly to the ADSI object in a standard COM "delegation" fashion.  If the user's ADSI object also is an ADSI container object, the IADsContainer interface implemented on the UserObjects coclass will delegate these calls as well.

Constructing the ADs Paths to the Objects

Example

A hypothetical example may help make these ideas concrete.  Assume there are two directory service "containers" that store data about users.  Assume the Suffix value is set to "1" for each AUO provider that defines the paths to user information in these databases.  The ADsPathPrefix and Name of the corresponding AUO provider entries could be

Note that the default AUO alias is specified by the "" alias. (I.e. the empty string)

Next assume a registered user with username "JohnS" (i.e. has REMOTE_USER="JohnS") requests an ASP page that uses the UserObjects object to personalize his 401k page.  When the script programmer instructs the UserObjects object to fetch some properties from a directory, it binds the appropriate ADSI object by combining the two sets of information.  Take the following ASP script example:

Hello <%= UserObjects.Get "givenName" %>, your current 401k balance is
<%= UserObjects.GetObjectEx("Secure").Get("Balance") %>.

In the first call, the UserObjects object constructs the complete ADs path from the ADsPathPrefix from default provider and the value of REMOTE_USER as follows:

ADsPath 1

"LDAP://ldasvr1:389/o=company1/ou=accounting" + "/cn=JohnS"

When the script parser hits the line

UserObjects.Get "givenName"

the script invokes the Get method on the class UserObjects object's IADs interface.  In this case, the Get method in the UserObjects object requests the "givenName" attribute from the Membership virtual server cache first. If not found there, it then binds the ADSI object shown above in ADsPath 1 and passes on the Get invocation to the actual ADSI object IADs interface.  In either case, the attribute value is returned or an error is raised.

In the second call, the UserObjects object constructs the complete using the AUO entry with the alias of "Secure" and the current username as follows:

ADsPath 2

"LDAP://ldapsvr1:443/o=company/ou=401k" + "/cn=JohnS"

In this case, we must explicitly ask for this ADSI object via the GetObjectEx method using the alias "Secure."  This method simply returns the IDispatch interface to the ADSI object bound by the above ADs Path 2. 

ADSI Security Issues

ADSI implements a set of security features to restrict access to information by unauthorized accounts stored in directory services.  Essentially, how one goes about binding to an ADSI object determines what type of credentials are presented to the underlying directory service.  A complete discussion of ADSI security features is beyond the scope of this reference.  For a complete discussion of ADSI related security issues, see the ADSI 2.0 SDK documentation found in the Platform SDK under Network and Distributed Services.

The UserObjects class implements the following checklist when determining which credentials to present when binding to ADSI objects.  The list is in order of precedence.

First and foremost,

• If the AUO provider has the BindAsUsername value currently set, the UserObjects object binds ADSI objects using these values.  The BindAsUsername and BindAsPassword values can be set for the AUO entry permanently with an instance of the AuoConfig class or with the IUserObjects::BindAs method at runtime. 
  
  
• That not being the case,
  
  
• If the programmer uses the SetUserName method to change the username within the UserObjects object at runtime, it subsequently binds to all ADSI objects anonymously.  (i.e. no credentials are presented when binding) Note that this only applies if the initial condition was not met.  If the BindAsUsername value is set for the provider, then these values are used to bind irrespective of whether SetUserName has been called or not.  This allows programmers and scripters to use the "auto user-create" feature of the AUO within a secured directory service.
  
  
• Otherwise, the UserObjects object uses the current username and password as credentials to bind to ADSI objects.

When ADSI Objects are Bound

The actual ADSI objects are not bound until a method is explicitly invoked on either the IADs or IADsContainer interfaces of a UserObjects object.  This is often referred to a "lazy" binding.  It is best to think of it as "bound when requested by a method."

Creating Instances of this Class

Normally, a web site programmer would have a built-in ASP Server-class object create the instance of the Membership.UserObjects class:  (VBScript example)

<% Set UserObject = Server.CreateObject(“Membership.UserObjects”)

However, this class is a bona fide COM object, and programmers can create instances  in any context using the normal COM library methods.