Class UserObjects

Programmatic Identifier

Membership.UserObjects.1

COM Class Logical Name

UserObjects

CLSID

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

Type Library Name

AUO 1.0 Type Library

Type Library Location

c:\Microsoft Site Server\bin\p&m\auo.dll

Threading Model

"Both"

This class defines a Component Object Model (COM) object that programmers and script writers can use to easily store and retrieve information about users stored in the Membership Directory service

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 script writers can then access the targeted information using this alias.

Each AUO provider configuration consists 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 by 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 script writers need not specify this provider in programs or scripts directly. Instead, they can interact with the UserObjects or SchemaObjects objects as if they were the corresponding ADSI objects. 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 interfaces implemented by the UserObjects coclass provide this service only for the ADSI object specified by the configuration of the default AUO provider.

The Active Directory Service Interfaces (ADSI)

The UserObjects COM class relies on other COM objects that implement the Active Directory Service COM Interfaces (ADSI) for all connectivity to data stores (directory services, databases, and so on). As its name suggests, an instance of the UserObjects COM class 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 UserObjects 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 and 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 COM class will delegate these calls as well if the object name passed is not the name of a defined AUO provider.

Constructing the ADs Paths to the Objects

The Active Directory Service (ADs paths) paths are assembled using the ADsPathPrefix of the specified AUO provider and its suffix value. The suffix value determines how the actual suffix string is assembled.

If the suffix is set to 1, the user name passed to the Init method is used, or the one specified with SetUserName. The standard Lightweight Directory Access Protocol (LDAP) syntax is then constructed. If the user name "John" is passed, then the full ADs path is ADsPathPrefix + "/" + "CN=" + "John." If the user name "DOMAIN\John" is passed, as is the normal case when Microsoft® Windows NT® authentication is the security package being used, the suffix "ou=DOMAIN\cn=John" is used.
If the suffix is set to 2, an AUO provider alias and property are named that hold the suffix to use. You set the AUO provider alias name and the property containing the suffix using the AUO provider entry's DepObject and DepProp values.
If the suffix is set to 3, the Site Server GUID value sent with the browser request is used to bind an object with relative distinguished name (RDN) "cn=<GUID>" in the "ou=AnonymousUsers" container, right below the "ou=Members" container.

Automatic Creation of User Objects

When a process calls one of the IADs methods on a UserObjects object, and no object by that display name exists, it will automatically generate a GUID for the new user and create the object using the suffix rules listed above. This operation is contingent on the necessary access control list (ACL) values being present on the container object. The class of the created object is defined by the AUO provider entry's Class value.

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

*Alias*	*ADsPathPrefix*
""	"LDAP://ldapsvr1:389/o=company1/ou=accounting"
"Secure"	"LDAP://ldapsvr1:443/o=company1/ou=401ks"

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

Next assume that a registered user with user name "JohnS" (REMOTE_USER="JohnS") requests an Active Server Pages (ASP) page that uses the UserObjects object to personalize his 401k page. When the script writer instructs the UserObjects object to fetch some properties from a directory, it binds the appropriate ADSI object by combining the two sets of information. Consider 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 the 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 ADs path using the AUO entry with the alias of "Secure" and the current user name as follows:

ADsPath 2

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

In this case, we must explicitly ask for this ADSI object through the GetObjectEx method using the alias "Secure." This method simply returns the IDispatch interface to the ADSI object bound by the above ADsPath 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 you go 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 Networking and Distributed Services section of the Microsoft® Platform SDK.

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 run time.

That not being the case,

If the programmer uses the SetUserName method to change the user name within the UserObjects object at run time, it subsequently binds to all ADSI objects anonymously (that is, 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 script writers to use the "auto user-create" feature of the AUO within a secured directory service.
Otherwise, the UserObjects object uses the current user name and password as credentials to bind to ADSI objects. This is the standard case, and allows the finest granularity when enforcing ACL checks for remote users.

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, or an object is requested through GetObject. This is often referred to a "lazy" binding. It is best to think of it as "bound when requested to do so by some appropriate method."

Creating Instances of this Class

Normally, a Web site programmer would have a built-in ASP Server object create the instance of the Membership.UserObjects class. The following code is a Microsoft® Visual Basic® Scripting Edition (VBScript) example:

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

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

For example, in a Visual Basic 5.0 application, you could do the following:

Dim Auo as UserObjects
Set Auo = new UserObjects
Auo.Init “2”, “JohnS”
Dim IAds as IADs
Set IAds = Auo
Dim givenName as String
GivenNAme = IADs.Get(“givenName”)

Note that in this case, you must call the Init method explicitly.

Interface IDispatch

The IDispatch interface on the UserObjects object presents a pure dispinterface to all the COM interfaces implemented including IADs, IADsContainer, and IUserObjects.

When programmers request access to attributes through the IDispatch interface on an instance of the UserObjects class, they can use a special syntax shared by most ADSI implementations. Normally, properties and methods defined for an object are implemented before compile time. That is, if an object has a public property called "Name" then the corresponding methods to get and put the value of this property for the object are implemented as part of the interface implementation before compiling. Most ADSI objects (and the UserObjects object), however, support the notion of dynamic properties through the IDispatch interface. What this means is that programmers can request attributes stored in the object that originally are fetched from a directory service or database dynamically at run time as if they belonged to the object natively. For script writers, this presents a much less cumbersome syntax, since all method and property calls proceed through the IDispatch interface.

Example: VBScript

Static syntax (clear)

UserObjects.Get("givenName")

Direct Syntax (may be occasionally confusing, but is easy)

UserObjects.givenName

In terms of the low-level mechanics of the IDispatch interface, this means a C++ programmer can call IDispatch::Invoke, passing the DISPATCH_PROPERTYGET flag and simply the DISPID of the attribute assigned dynamically by IDispatch::GetIDsOfNames. This is in contrast to passing the DISPATCH_METHOD flag, the DISPID for the "Get" or "GetEx" method, and the name of the attribute as a member of the dispparams argument.

CAUTION When using the dynamic property syntax, you must be careful to avoid name collisions with actual properties of the object. These "real" properties of the object always take precedence over data fetched from a directory service. For example, any directory service properties with the names "GUID," "Parent," or "Name" would conflict since these names are used to store information about the object itself, and must be returned when requested. In such cases, you must use the "Get" and "Set" methods for these properties.

Interface IADs

Properties

Name	Description
Name	Gets the relative name of the object as it appears in the underlying directory service. This and all properties exposed by this interface are always the same name that would be present if you bound the ADSI object defined by the default AUO provider's ADsPathPrefix value and the current AUO suffix.
Class	Gets the schema class name of the object. See above.
GUID	Gets the globally unique identifier of the object. See above.
ADsPath	Gets the ADs Path of the object. This path uniquely identifies the object from all others. See above.
Parent	Gets the ADs Path to the object that contains this object (its parent object). See above.
Schema	Gets the ADs Path to the object that defines the schema for this object. See above.

Methods

Name	Description
GetInfo	Loads or reloads the data from the directory service into the ADSI object. This method is implicitly called if a call to Get is encountered before GetInfo.
GetInfoEx	Loads or reloads specific properties from the directory service database into the ADSI object.
SetInfo	Commits the data in the ADSI object to the directory service database.
Get	Gets the value or values of the property specified by name. The method will first check the Membership Server instance property cache if configured to do so.
GetEx	Gets the value of the property specified by name. The method will check the Membership Server instance cache if configured to do so.
Put	Sets the value for the property specified in the ADSI object.
PutEx	Sets the value for the property specified in the ADSI object.

Remarks

The IADs interface implementation in the UserObjects COM object provides extra functionality enhancements relating to the Membership system. These enhancements are as follows:

If the Membership service instance has the bUseCache flag set to TRUE, the various Get/GetEx methods first check the Membership service instance cache for the property value. If the property value is not in the cache, the call is delegated to the actual underlying ADSI object. This can increase performance tremendously. The Put/PutEx methods, however, do not attempt to set the property in the cache.
The SetInfo method always attempts to issue a "RecentChanges" cookie to the user through an instance of the VerifUsr coclass.

The properties stored in the ADSI object are available through the IDispatch interfaces on ADSI objects using a special syntax. This syntax is referred to as "direct syntax." In this case, you can refer to the property names as if they were "real" properties of the ADSI object. For example,

<%
  Set IUserObjects = Server.CreateObject("Membership.UserObjects
  name = IUserObjects.GivenName
%>

or alternatively, using the Get method:

<%
    Set IUserObjects = Server.CreateObject("Membership.UserObjects")
    name = IUserObjects.Get "givenName"
 %>

Note that objects of class UserObjects as well as most ADSI objects support this syntax. Check the documentation for the specific ADSI provider (ADSI Namespace COM object) for more information about support of this feature.

Interface IADsContainer

The IADsContainer interface implementation for the UserObjects class allows a programmer to access the various ADSI objects for the current user. This implementation differs from those on other ADSI objects in that they deal with the objects defined by the AUO provider entries for the current Membership server instance. For example, if the AUO entries for Membership server instance 3 are the default, "container1", and "container2", the Count property would return 3 and the enumeration would return interfaces on the corresponding user ADSI objects defined by these entries. It could be said that the UserObjects object is a container of the user's ADSI objects as defined by the AUO provider entries for the server instance. Hence the name UserObjects.

Properties

Property	Description
Count	Gets the number of ADSI objects defined by the AUO entries for this Membership virtual server instance. (For example, if there are three AUO entries, this method returns "3".)
_NewEnum	Gets an interface on an enumerator object that can be used to enumerate the ADSI objects defined by the AUO entries for this Membership server instance.
Filters	Not implemented by this class.
Hints	Not implemented by this class.

Methods

Method	Description
GetObject	Gets an interface on a named ADSI object. In this case, the name can refer to a defined AUO provider entry name. If the name is not defined as an AUO entry, the method will attempt to delegate this method invocation onto the ADSI object defined by the default AUO entry.
Create	Not implemented by this class.
Delete	Not implemented by this class.
CopyHere	Not implemented by this class.
MoveHere	Not implemented by this class.

Interface IUserObjects

BindAs

The BindAs method sets the credentials used when binding to the ADSI object defined by the AUO entry specified.

IDL Definition

HRESULT BindAs(
BSTR bszEntryName,
BSTR bszUserName,
BSTR bszPassword
);

Parameters

bszEntryName

The name of the AUO entry to change binding credentials on.

bszUserName

The distinguished name to use when binding.

bszPassword

The password to use when binding.

Return Value

A standard HRESULT value.

Remarks

The Init method must be called before BindAs. This loads the entries defined for a particular Membership virtual server instance.

The distinguished name (DN) is the full path to the user as it appears in the underlying directory service (for example, in an LDAP service: /o=company/ou=admingroup/cn=John").

This method can only be invoked prior to the binding of any ADSI objects. After an ADSI object has been bound by the UserObjects object, the binding credentials cannot be changed, and any further invocations of the BindAs method will fail.

This method only changes the binding credentials for the lifetime of the class UserObjects object. To permanently change binding credentials for an AUO entry, see the reference for the AuoConfig COM class.

Example

<% Set UserObjects = Server.CreateObject(“Membership.UserObjects”)
  UserObjects.BindAs(“o=company/ou=public/cn=publicuser”,”password”)
%>

See Also

Class AuoConfig

GetObjectAsUser

This method attempts to bind a specified ADSI object, and if successful, returns the IDispatch address of the object. The authentication procedure is the same as normally used by the class UserObjects object when binding ADSI objects.

IDL Definition

HRESULT GetObjectAsUser(
[in]         BSTR        bszADsPath,
[out,retval] IDispatch** ppObject
);

Parameters

bszADsPath

The ADSI path to an object.

ppObject

Upon return, the IDispatch interface to the ADSI object.

Return Value

A standard HRESULT value.

Remarks

This method differs from IADsContainer GetObject or IUserObjects GetObjectEx in that it returns any accessible ADSI object, rather than an object defined by an AUO provider entry or an object that is located in the object defined by the ADsPathPrefix and suffix.

Example

VBScript in an ASP page:

<% Set IUserObjects = Server.CreateObject(“Membership.UserObjects”)
   Set IContainer =    IUserObjects.GetObjectAsUser(“LDAP://someserver/ou=groups/o=company”)
   For Each IItem in IContainer
     Response.write “Item’s Name: “ & IItem.Name & “<br>”
     Response.write “Item’s ADsPath: “ & IItem.AdsPath & “<br>”
   Next

GetObjectEx

This method returns the IDispatch interface to the user's ADSI object as defined by the specified AUO entry name passed as an argument. This is the default method for the IUserObjects interface.

IDL Definition

HRESULT GetObjectEx(
[in]         BSTR         bszEntryName,
[out,retval] IDispatch**  ppEntry
);

Parameters

bszEntryName

The name of the AUO provider entry (the AUO provider alias).

ppEntry

Upon return, the IDispatch interface to the ADSI object.

Return Value

A standard HRESULT value.

Remarks

Since each Membership server instance has its own set of AUO entries defined, the Init method must be called before GetObjectEx.

GetObjectEx is marked in its IDL definition as [id(DISPID_VALUE)]. This means that this method is the default method for the object. If no method is specified when IDispatch::Invoke is called, the object defaults to invoking GetObjectEx. This is nice for languages such as VBScript as a shorthand to avoid extra typing:

UserObject("this") is the same as UserObjects.GetObjectEx("this"). That is, they invoke the same method using "this" as an argument.

Example

VBScript in an ASP Page:

<% 
 Set IUserObjects = Server.CreateObject("Membership.UserObjects")
 Set IadsiObj = IUserObjects("AUOAlias")
 Response.write "Hello " & IadsObj.givenName
%>

In this example, the givenName user property is fetched from the user ADSI object using the configuration information for the AUO entry named "AUOAlias". Note also that you need not explicitly type out GetObjectEx because it is the default method for the dispinterface for IUserObjects.

Init

The Init method is used to initialize the object with a user name and a Microsoft® Internet Information Server (IIS) server instance identifier. This is the first method to call when using the UserObjects COM object. It is called automatically if the ASP Server object is used to create the instance.

IDL Definition

HRESULT Init(
BSTR bszIISVirtId,
BSTR bszUserName
);

Parameters

bszIISVirtId

An Internet Information Server virtual server instance identifier (from INSTANCE_ID in ASP).

bszUserName

The user name (from REMOTE_USER variable in ASP).

Return Value

A standard HRESULT value.

Remarks

The bszIISVirtId is used to map to the corresponding Membership server instance, and hence to a set of AUO provider entries.

The bszUserName is used to complete the ADs path to the user's directory information when ADSI objects are requested of the UserObjects object if the Suffix value for the entry is set to "username" (0x1).

The Init method is invoked automatically within the OnStartPage method which is always invoked on the object when the Server dispinterface method CreateObject is used to create the instance. The IIS virtual server instance identifier (INSTANCE_ID) and the current user name (REMOTE_USER) are fetched from the Request object to be sent as arguments.

In a non-ASP environment, you must explicitly call the Init method.

Example

VBScript in an ASP page:

<% Set IUserObjects = CreateObject("Membership.UserObjects") ' Note here that the Server dispinterface (object) was not used to create the object ' In this case, the OnStartPage method was not called, so we must do so Username = Request.ServerVariables("REMOTE_USER") IISVirtId = Request.ServerVariables("INSTANCE_ID") call IUserObjects.Init(IISVirtId,Username)

See Also

OnStartPage Method

OnStartPage

The OnStartPage method is an implementation of the standard server-side method invoked by the ASP scripting context on any COM objects created using the built-in ASP Server dispinterface CreateObject method. In this case, the OnStartPage method invokes the IUserObject::Init method on the UserObjects object, passing the virtual server instance identifier and the user name found in the REMOTE_USER variable sent with the request.

OnEndPage

The OnEndPage method is an implementation of the standard server-side method invoked by the ASP scripting context on any COM objects created using the built-in ASP Server dispinterface CreateObject method. It performs any necessary cleanup in an ASP context, and need never be called explicitly.

SetUserName

The SetUserName method sets the user name in the object. This value overrides the value set using the Init method.

IDL Definition

HRESULT SetUserName(  BSTR  bszUserName ) ;

Parameters

bszUserName

The new user name.

Return Value

A standard HRESULT value.

Remarks

SetUserName can be called at any time before any ADSI objects have been bound by the UserObjects object. After an ADSI object has been bound, the SetUserName can no longer be used.

Example

VBScript in an ASP page:

<% Set IUserObjects = Server.CreateObject("Membership.UserObjects")
IUserObjects.SetUserName "KellyC"
Response.write “User Object ADs Path: “ & IUserObjects.AdsPath
Response.Write “Given Name property:  “ & IUserObjects.Get(“givenName”)

In the case above, the ADSI user object with relative name "cn=KellyC" in the default AUO entry would be used, not the one sent with the HTTP request. The output would be, depending on the default AUO entry ADsPathPrefix and the properties stored in the user object:

User Object ADs Path: LDAP://someserver/o=so,ecompnay/ou=members/cn=KellyC
Given Name property:  Kelly