| Directory Services |
The IADsOpenDSObject::OpenDSObject method binds to an ADSI object, using the given credentials, and retrieves an IDispatch pointer on the specified object.
HRESULT OpenDSObject( BSTR lpszDNName, BSTR lpszUserName, BSTR lpszPassword, LONG lnReserved, IDispatch** ppOleDsObj );
For more information and other return values, see ADSI Error Codes.
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. Binding to any NDS object will ignore the lnReserved flag.
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.
Dim dso As IADsOpenDSObject
Dim obj1, obj2 As IADs
Dim szUsername As String
Dim szPassword As String
Set dso = GetObject("LDAP:")
' Insert code securely.
' Supply full credentials to initiate a server connection.
Set obj1 = dso.OpenDSObject( _
"LDAP://server1/CN=Dept1,DC=Fabrikam,DC=com", _
szUsername, _
szPassword, _
ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)
' Perform an operation with the bound object, obj1
MsgBox obj1.Class
' Bind to another object with the cached user credential.
Set obj2 = dso.OpenDSObject( _
"LDAP://server1/CN=Dept2,DC=Fabrikam,DC=com", _
szUsername, _
szPassword, _
ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)
MsgBox obj2.Class
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.
Dim dso As IADsOpenDSObject
Dim obj1, obj2 As IADs
Dim szUsername As String
Dim szPassword As String
Set dso = GetObject("LDAP:")
' Insert code securely.
' Bind using full credentials.
Set obj1 = dso.OpenDSObject( _
"LDAP://server1/CN=Dept1,DC=Fabrikam,DC=com", _
szUsername, _
szPassword, _
ADS_SECURE_AUTHENTICATION + ADS_SERVER_BIND)
' Bind to another object with the default credentials.
Set obj2 = GetObject("LDAP://server1/CN=Dept2,DC=Fabrikam,DC=com")
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 WinNT provider, you may pass in lpszUserName as one of the following strings:
With the LDAP provider for Active Directory, you may pass in lpszUserName as one of the following strings:
The NWCOMPAT provider does not support this interface. NWCOMPAT users can call WNetAddConnetion2 prior to binding to the object with GetObject when security credentials are required for the bind to succeed.
The following code example shows how to use IADsOpenDSObject to open the "Administrator" user object on "Fabrikam" with Secure Authentication through the WinNT provider.
Dim dso As IADsOpenDSObject
Dim domain As IADsDomain
Dim szUsername As String
Dim szPassword As String
On Error GoTo Cleanup
' Insert code to securely retrieve the username and password.
Set dso = GetObject("WinNT:")
Set domain = dso.OpenDSObject("WinNT://Fabrikam", szUsername, szPassword,_
ADS_SECURE_AUTHENTICATION)
Cleanup:
If (Err.Number <> 0 ) Then
MsgBox("An error has occurred. " & Err.Number)
End If
Set dso = Nothing
Set domain = Nothing
The following code example uses IADsOpenDSObject to open an Active Directory object through the LDAP provider.
IADsOpenDSObject *pDSO = NULL;
HRESULT hr = S_OK;
hr = ADsGetObject(L"LDAP:", IID_IADsOpenDSObject, (void**) &pDSO);
if (SUCCEEDED(hr))
{
IDispatch *pDisp;
hr = pDSO->OpenDSObject(CComBSTR("LDAP://DC=Fabrikam, DC=com"),
CComBSTR("jeffsmith@Fabrikam.com"),
CComBSTR("passwordhere"),
ADS_SECURE_AUTHENTICATION,
&pDisp);
pDSO->Release();
if (SUCCEEDED(hr))
{
IADs *pADs;
hr = pDisp->QueryInterface(IID_IADs, (void**) &pADs);
pDisp->Release();
if (SUCCEEDED(hr))
{
// Perform an object manipulation here.
pADs->Release();
}
}
}
Client: Included in Windows XP and
Windows 2000 Professional.
Server: Included in Windows Server 2003 and
Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension
on Windows NT 4.0 SP6a and Windows 95/98/Me.
Header: Declared in Iads.h.
ADSI Error Codes, ADS_AUTHENTICATION_ENUM, ADsOpenObject, Binding, GetObject, IADsOpenDSObject, IDispatch, LDAP ADsPath, WinNT ADsPath, WNetAddConnetion2