The IADsOpenDSObject::OpenDSObject method binds to an ADSI object, using the given credentials, and retrieves an IDispatch pointer to the specified object.
The null-terminated Unicode string that specifies the ADsPath of the ADSI object. For more information and examples of binding strings for this parameter, see LDAP ADsPath. When using the LDAP provider with an ADsPath that includes a specific server name, the lnReserved parameter should include the ADS_SERVER_BIND flag.
The null-terminated Unicode string that specifies the user name to be used for securing permission from the namespace server. For more information, see the following Remarks section.
The null-terminated Unicode string that specifies the password to be used to obtain permission from the namespace server.
Authentication flags used to define the binding options. For more information, see ADS_AUTHENTICATION_ENUM.
Pointer to a pointer to an IDispatch interface on the requested object.
This method supports the standard return values, including S_OK when the IDispatch interface has been successfully retrieved using these credentials.
For more information, see ADSI Error Codes.
This method should not be used just to validate user credentials.
When lnReserved is set, the behavior of OpenDSObject depends on the provider it connects to. High security namespaces may ignore these flags and always require authentication.
The IADsOpenDSObject::OpenDSObject method maintains the authenticated and encrypted user credentials in the cache. Cached credentials may be used in subsequent operations for binding to any other directory objects. The ADSI client applications should not cache the credentials supplied by the user. Instead, they should rely on ADSI infrastructure to perform caching. To use the cached credentials, lpszPassword and lpszUserName must remain unchanged in any subsequent calls of OpenDSObject. The following code example shows this operation.
The credentials passed to the IADsOpenDSObject::OpenDSObject function are used only with the particular object bound to and do not affect the security context of the calling thread. This means that, in the following code example, the call to IADsOpenDSObject::OpenDSObject will use different credentials than the call to GetObject.
With a serverless binding, the server name, "server1", is not stated explicitly. The default server is used instead. Only the LDAP provider supports the serverless binding. To use this feature, the client computer must be on an Active Directory domain. To attempt a serverless binding from a computer, you must bind as a domain user.
For credential caching to work properly, it is important to keep an object reference outstanding to maintain the cache handle. In the example given above, an attempt to open "obj2" after releasing "obj1" will result in an authentication failure.
The IADsOpenDSObject method uses the default credentials when lpszUserName and lpszPassword are set to NULL.
If Kerberos authentication is required for the successful completion of a specific directory request using the LDAP provider, the lpszDNName binding string must use either a serverless ADsPath, such as "LDAP://CN=Jeff Smith,CN=admin,DC=Fabrikam,DC=com", or it must use an ADsPath with a fully qualified DNS server name, such as "LDAP://central3.corp.Fabrikam.com/CN=Jeff Smith,CN=admin,DC=Fabrikam,DC=com". Binding to the server using a flat NETBIOS name or a short DNS name, for example, using the short name "central3" instead of "central3.corp.Fabrikam.com", may or may not yield Kerberos authentication.
The ADsOpenObject helper function offers the same features as the IADsOpenDSObject::OpenDSObject method.
With the LDAP provider for Active Directory, you may pass in lpszUserName as one of the following strings:
- The name of a user account, such as "jeffsmith". To use a user name by itself, you must set only the ADS_SECURE_AUTHENTICATION flag in the lnReserved parameter.
- The user path from a previous version of Windows, such as "Fabrikamjeffsmith".
- Distinguished Name, such as "CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=Com". To use a DN, the lnReserved parameter must be zero or it must include the ADS_USE_SSL flag
- User Principal Name (UPN), such as "jeffsmith@Fabrikam.com". To use a UPN, you must assign the appropriate UPN value for the userPrincipalName attribute of the target user object.
Examples
The following code example shows how to use IADsOpenDSObject to open the "Administrator" user object on "Fabrikam" with Secure Authentication through the LDAP provider.
The following code example uses IADsOpenDSObject to open an Active Directory object through the LDAP provider.
ADSI Error Codes
ADS_AUTHENTICATION_ENUM
ADsOpenObject
Binding
GetObject
IADsOpenDSObject
IDispatch
LDAP ADsPath