Método IADsOpenDSObject::OpenDSObject (iads.h)
El método IADsOpenDSObject::OpenDSObject se enlaza a un objeto ADSI, utilizando las credenciales especificadas y recupera un puntero IDispatch al objeto especificado.
Sintaxis
HRESULT OpenDSObject(
[in] BSTR lpszDNName,
[in] BSTR lpszUserName,
[in] BSTR lpszPassword,
[in] long lnReserved,
[out] IDispatch **ppOleDsObj
);
Parámetros
[in] lpszDNName
Cadena Unicode terminada en null que especifica el ADsPath del objeto ADSI. Para obtener más información y ejemplos de cadenas de enlace para este parámetro, vea LDAP ADsPath. Cuando se usa el proveedor LDAP con un ADsPath que incluye un nombre de servidor específico, el parámetro lnReserved debe incluir la marca ADS_SERVER_BIND .
[in] lpszUserName
Cadena Unicode terminada en null que especifica el nombre de usuario que se va a usar para proteger el permiso del servidor de espacio de nombres. Para obtener más información, vea la sección Comentarios que se muestra más adelante.
[in] lpszPassword
Cadena Unicode terminada en null que especifica la contraseña que se va a usar para obtener permiso del servidor de espacio de nombres.
[in] lnReserved
Marcas de autenticación usadas para definir las opciones de enlace. Para obtener más información, consulte ADS_AUTHENTICATION_ENUM.
[out] ppOleDsObj
Puntero a un puntero a una interfaz IDispatch en el objeto solicitado.
Valor devuelto
Este método admite los valores devueltos estándar, incluidos S_OK cuando la interfaz IDispatch se ha recuperado correctamente con estas credenciales.
Para obtener más información, consulta Códigos de error adsi.
Comentarios
Este método no debe usarse solo para validar las credenciales de usuario.
Cuando se establece lnReserved , el comportamiento de OpenDSObject depende del proveedor al que se conecta. Los espacios de nombres de alta seguridad pueden omitir estas marcas y siempre requerir autenticación.
El método IADsOpenDSObject::OpenDSObject mantiene las credenciales de usuario autenticadas y cifradas en la memoria caché. Las credenciales almacenadas en caché se pueden usar en operaciones posteriores para enlazar a cualquier otro objeto de directorio. Las aplicaciones cliente ADSI no deben almacenar en caché las credenciales proporcionadas por el usuario. En su lugar, deben confiar en la infraestructura adsi para realizar el almacenamiento en caché. Para usar las credenciales almacenadas en caché, lpszPassword y lpszUserName deben permanecer sin cambios en las llamadas posteriores de OpenDSObject. En el ejemplo de código siguiente se muestra esta operación.
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
Las credenciales que se pasan a la función IADsOpenDSObject::OpenDSObject solo se usan con el objeto determinado enlazado a y no afectan al contexto de seguridad del subproceso que realiza la llamada. Esto significa que, en el ejemplo de código siguiente, la llamada a IADsOpenDSObject::OpenDSObject usará credenciales diferentes a la llamada a 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")
Con un enlace sin servidor, el nombre del servidor, "server1", no se indica explícitamente. En su lugar, se usa el servidor predeterminado. Solo el proveedor LDAP admite el enlace sin servidor. Para usar esta característica, el equipo cliente debe estar en un dominio de Active Directory. Para intentar un enlace sin servidor desde un equipo, debe enlazar como usuario de dominio.
Para que el almacenamiento en caché de credenciales funcione correctamente, es importante mantener una referencia de objeto pendiente para mantener el identificador de caché. En el ejemplo anterior, un intento de abrir "obj2" después de liberar "obj1" provocará un error de autenticación.
El método IADsOpenDSObject usa las credenciales predeterminadas cuando lpszUserName y lpszPassword se establecen en NULL.
Si la autenticación Kerberos es necesaria para completar correctamente una solicitud de directorio específica mediante el proveedor LDAP, la cadena de enlace lpszDNName debe usar un ADsPath sin servidor, como "LDAP://CN=Jeff Smith,CN=admin,DC=Fabrikam,DC=com", o bien debe usar un ADsPath con un nombre de servidor DNS completo, como "LDAP://central3.corp.Fabrikam.com/CN=Jeff Smith, CN=admin,DC=Fabrikam,DC=com". El enlace al servidor mediante un nombre NETBIOS plano o un nombre DNS corto, por ejemplo, con el nombre corto "central3" en lugar de "central3.corp.Fabrikam.com", puede o no producir autenticación Kerberos.
La función auxiliar ADsOpenObject ofrece las mismas características que el método IADsOpenDSObject::OpenDSObject .
Con el proveedor LDAP para Active Directory, puede pasar lpszUserName como una de las cadenas siguientes:
- Nombre de una cuenta de usuario, como "jeffsmith". Para usar un nombre de usuario por sí mismo, solo debe establecer la marca ADS_SECURE_AUTHENTICATION en el parámetro lnReserved .
- Ruta de acceso del usuario de una versión anterior de Windows, como "Fabrikam\jeffsmith".
- Nombre distintivo, como "CN=Jeff Smith,OU=Sales,DC=Fabrikam,DC=Com". Para usar un DN, el parámetro lnReserved debe ser cero o debe incluir la marca de ADS_USE_SSL
- Nombre principal de usuario (UPN), como "jeffsmith@Fabrikam.com". Para usar un UPN, debe asignar el valor UPN adecuado para el atributo userPrincipalName del objeto de usuario de destino.
Ejemplos
En el ejemplo de código siguiente se muestra cómo usar IADsOpenDSObject para abrir el objeto de usuario "Administrador" en "Fabrikam" con autenticación segura a través del proveedor LDAP.
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 user name and password.
Set dso = GetObject("LDAP:")
Set domain = dso.OpenDSObject("LDAP://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
En el ejemplo de código siguiente se usa IADsOpenDSObject para abrir un objeto de Active Directory a través del proveedor LDAP.
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();
}
}
}
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows Vista |
| Servidor mínimo compatible | Windows Server 2008 |
| Plataforma de destino | Windows |
| Encabezado | iads.h |
| Archivo DLL | Activeds.dll |