LDAP_BIND/UNBIND

Sinopsis

Parámetros de entrada

ld

Especifica el puntero LDAP devuelto por una llamada anterior a ldap_init(), ldap_ssl_init() o ldap_open().

dn

Especifica el Nombres distinguidos (DN) de la entrada con la que enlazar.

mechanism

Aunque varios mecanismos están registrados IANA (Internet Assigned Numbers Authority), los únicos mecanismos básicos soportados actualmente por la biblioteca LDAP son:

• Mecanismo LDAP_MECHANISM_EXTERNAL , representado por la serie EXTERNAL.
• Mecanismo LDAP_MECHANISM_GSSAPI , representado por la serie GSSAPI.
• Mecanismo LDAP_MECHANISM_DIGEST_MD5 , representado por la serie DIGEST-MD5.
  Nota: El mecanismo CRAM-MD5 no está soportado en una operación de enlace.

El mecanismo LDAP_MECHANISM_EXTERNAL indica al servidor que se debe utilizar información externa a SASL para determinar si el cliente está autorizado para autenticarse. Para esta implementación, el sistema que proporciona la información externa debe ser SSL. Por ejemplo, si el cliente establece el DN y las credenciales en NULL (el valor de los punteros debe ser NULL), con el mecanismo establecido en LDAP_MECHANISM_EXTERNAL, el cliente solicita que el servidor utilice la identidad autenticada del certificado X.509 del cliente que se utilizó para autenticar el cliente en el servidor durante el reconocimiento SSL. A continuación, el servidor puede utilizar la identidad autenticada para acceder al directorio.

El mecanismo LDAP_MECHANISM_GSSAPI se utiliza para habilitar la autenticación Kerberos . En la autenticación Kerberos , un cliente presenta credenciales válidas que se obtienen de un centro de distribución de claves (KDC) de Kerberos a un servidor de aplicaciones. El servidor descifra y verifica las credenciales utilizando su clave de servicio.

Cuando el mecanismo se establece en un puntero NULL, la solicitud de enlace SASL se interpreta como una solicitud de autenticación simple, es decir, equivalente a utilizar ldap_simple_bind() o ldap_simple_bind_s().

Para obtener más información sobre cómo utilizar los plug-ins de cliente LDAP, consulte LDAP_PLUGIN_REGISTRATION. Para obtener más información sobre el desarrollo de un plug-in de cliente LDAP, consulte Referencia de programación del plug-in de cliente LDAP.

El mecanismo LDAP_MECHANISM_DIGEST_MD5 se utiliza para autenticar el ID y la contraseña con el servidor utilizando un protocolo de desafío o respuesta. El protocolo protege la contraseña de texto simple a través de la conexión y evita ataques de reproducción.

Este mecanismo sólo es útil cuando el servidor LDAP puede recuperar la contraseña de usuario. Si la contraseña se almacena en un formato hash, por ejemplo, cifrado o SHA, la autenticación utilizando el mecanismo DIGEST-MD5 falla. Cuando se utiliza el mecanismo DIGEST-MD5 , el nombre de host que se proporciona en la llamada ldap_init debe resolverse en el nombre de host completo del servidor.

La aplicación debe proporcionar un nombre de usuario en la llamada ldap_sasl_bind_s utilizando el control de cliente IBM_CLIENT_MD5_USER_NAME_OID . Opcionalmente, la aplicación puede proporcionar un dominio en la llamada ldap_sasl_bind_s utilizando el control de cliente IBM_CLIENT_MD5_REALM_NAME_OID . Opcionalmente, la aplicación puede proporcionar un ID de autorización como parámetro dn .

cred

Especifica las credenciales con las que autenticarse. Se pueden pasar credenciales arbitrarias con este parámetro. En la mayoría de los casos, esta credencial es la contraseña de usuario. Cuando se utiliza un enlace SASL (Simple Authentication Security Layer), el formato y el contenido de las credenciales dependen del valor del parámetro de mecanismo.

method

Selecciona el método de autenticación que se va a utilizar. Especifique LDAP_AUTH_SIMPLE para la autenticación simple o LDAP_AUTH_SASL para el enlace SASL. El uso de las API ldap_bind y ldap_bind_s está en desuso.

password

Especifica la contraseña que se utiliza en asociación con el DN de la entrada en la que se va a enlazar.

serverctrls

Especifica una lista de controles de servidor LDAP. Para obtener más información sobre los controles del servidor, consulte Controles LDAP.

clientctrls

Especifica una lista de controles de cliente LDAP. Para obtener más información sobre los controles de cliente, consulte Controles LDAP.

rebindproc

Especifica el punto de entrada de una rutina a la que se llama para obtener las credenciales de enlace que se utilizan cuando se contacta con un nuevo servidor después de una referencia LDAP.

Parámetros de salida

msgidp

Este parámetro de resultado se establece en el ID de mensaje de la solicitud si la llamada ldap_sasl_bind() se ejecuta correctamente.

servercredp

Este parámetro de resultado se establece en las credenciales devueltas por el servidor. Si no se devuelven credenciales, se establece en NULL.

Uso

Estas rutinas proporcionan varias interfaces para la operación de enlace LDAP. Después de utilizar ldap_init, ldap_ssl_init o ldap_open para crear un descriptor de contexto LDAP, se puede ejecutar un enlace antes de que se intenten otras operaciones a través de la conexión. Se proporcionan las versiones síncronas y asíncronas de cada variante de la llamada de enlace.

Un enlace es opcional cuando se comunica con un servidor LDAP que da soporte al protocolo LDAP V3 . La ausencia de un enlace es interpretada por el servidor V3 de LDAP como una solicitud de acceso no autenticado. Los servidores LDAP que sólo dan soporte al protocolo LDAP V2 necesitan un enlace.

Las API ldap_simple_bind() y ldap_simple_bind_s() proporcionan una autenticación simple, utilizando un ID de usuario o dn y una contraseña que se pasa en texto simple a la API LDAP.

ldap_bind() y ldap_bind_s() proporcionan rutinas de autenticación generales, donde se puede elegir un método de autenticación. En este kit de herramientas, method debe establecerse en LDAP_AUTH_SIMPLE. Puesto que el uso de estas dos API está en desuso, en su lugar se deben utilizar ldap_simple_bind y ldap_simple_bind_s .

Las API ldap_sasl_bind y ldap_sasl_bind_s se pueden utilizar para ejecutar la autenticación general y ampliable a través de LDAP utilizando SASL.

Todas las rutinas de enlace toman ld como su primer parámetro tal como se devuelve de ldap_init, ldap_ssl_inito ldap_open.

Autenticación simple

La forma más sencilla de la llamada de enlace es ldap_simple_bind_s(). Toma el DN para enlazar y la contraseña de usuario (proporcionada en contraseña). Devuelve una indicación de error de LDAP (consulte LDAP_ERROR). La llamada ldap_simple_bind() es asíncrona, tomando los mismos parámetros pero iniciando sólo la operación de enlace y devolviendo el ID de mensaje de la solicitud que ha enviado. El resultado de la operación se puede obtener con una llamada posterior a ldap_result().

Autenticación general

Las rutinas ldap_bind() y ldap_bind_s() están en desuso.

Las API en desuso se pueden utilizar cuando se selecciona el método de autenticación en tiempo de ejecución. Ambos toman un parámetro de método adicional cuando se selecciona el método de autenticación que se va a utilizar. Sin embargo, cuando utilice este kit de herramientas, method debe establecerse en LDAP_AUTH_SIMPLE para seleccionar la autenticación simple. ldap_bind() y ldap_simple_bind() devuelven el ID de mensaje de la solicitud iniciada. ldap_bind_s() y ldap_simple_bind_s() devuelven una indicación de error de LDAP cuando la finalización no es satisfactoria, oLDAP_SUCCESSal finalizar correctamente.

Autenticación SASL

Se da soporte a cinco categorías de autenticación SASL:

• Autenticación SASL utilizando el mecanismo EXTERNAL
• Autenticación SASL utilizando el mecanismo GSSAPI (Kerberos está soportado e implementado como un plug-in)
• Autenticación SASL utilizando el mecanismo DIGEST-MD5 (implementado como un plug-in)
• Autenticación SASL utilizando una biblioteca de plug-ins SASL proporcionada por el usuario
• Autenticación SASL utilizando un mecanismo SASL implementado por la propia aplicación

Cuando el parámetro de entrada mechanism se establece en un puntero NULL, la solicitud de enlace SASL se interpreta como una solicitud de autenticación simple, es decir, equivalente a utilizar ldap_simple_bind() o ldap_simple_bind_s().

Además, el mecanismo de autenticación SASL proporciona un recurso para que el servidor LDAP devuelva las credenciales de servidor al cliente. Una aplicación puede obtener las credenciales de servidor que se devuelven del servidor en el resultado de enlace SASL con la API ldap_parse_sasl_bind_result() .

Enlaces EXTERNAL SASL

La razón principal para utilizar el mecanismo de enlace EXTERNAL SASL es utilizar el mecanismo de autenticación de cliente. SSL proporciona este mecanismo para autenticarse fuertemente en Directory Server utilizando el certificado X.509 del cliente. Por ejemplo, la aplicación cliente puede utilizar la lógica siguiente:

• ldap_ssl_client_init (inicializar la biblioteca SSL)
• ldap_ssl_init (host, puerto, nombre), donde el nombre hace referencia a un par de claves pública o privada en el archivo de base de datos de claves de cliente
• ldap_sasl_bind_s (ld, dn=NULL, mechanism=LDAP_MECHANISM_EXTERNAL, cred=NULL)

Un servidor que dé soporte a este mecanismo, como por ejemplo IBM® Directory Server, puede acceder al directorio. Utiliza la identidad de cliente autenticada tal como se extrae del certificado de cliente X.509 .

Enlaces SASL de GSSAPI

La autenticación Kerberos está soportada en este release. Si los parámetros de entrada para ldap_sasl_bind o ldap_sasl_bind_s son mechanism==GSSAPI y cred==NULL, se presupone que el usuario ya se ha autenticado en un servidor de seguridad Kerberos y ha obtenido un tíquet de otorgamiento de tíquet (TGT), ya sea a través de un proceso de inicio de sesión de escritorio o utilizando un programa como kinit. El descriptor de contexto de credenciales GSSAPI utilizado para iniciar un contexto de seguridad en el lado del cliente LDAP se obtiene del contexto de inicio de sesión actual. Si los parámetros de entrada para estas dos funciones de enlace SASL son mechanism==GSSAPI y cred!=NULL, el interlocutor de las funciones debe proporcionar el descriptor de contexto de credenciales GSSAPI para que el cliente LDAP inicie un contexto de seguridad con un servidor LDAP. Por ejemplo, un servidor LDAP llama a una función de enlace SASL con un descriptor de contexto de credenciales que el servidor recibe de un cliente como descriptor de contexto de credenciales delegado.

Enlaces SASL de DIGEST-MD5

El servidor acepta solicitudes de enlace SASL utilizando el mecanismo DIGEST-MD5 . Existen dos tipos de solicitudes de enlace DIGEST-MD5 : solicitudes de enlace de autenticación inicial y solicitudes de enlace de autenticación posterior. La autenticación inicial es necesaria y está soportada por el servidor de directorios. El soporte de autenticación posterior es opcional y no está soportado por Directory Server.

El servidor responde a una solicitud de enlace SASL de DIGEST-MD5 con un desafío de resumen. El desafío contiene los valores necesarios para la sección 2.1.1de RFC2831 , con el siguiente comportamiento específico de la implementación:

• realm -El servidor siempre envía el dominio en el que está configurado el servidor.
• nonce -El servidor genera un nonce aleatorio.
• qop-options -El servidor sólo da soporte a auth .

La siguiente respuesta del cliente al servidor debe ser otro mensaje de enlace SASL de DIGEST-MD5 . La respuesta incluye varios campos con valores que el servidor utiliza como se indica a continuación:

• username-El servidor utiliza el valor de nombre de usuario para determinar si el usuario está enlazando como administrador o para buscar una entrada en el rdbmprimario. Si el nombre de usuario es un administrador DigestUsername, el servidor utiliza dicho administrador para enlazar. Si el nombre de usuario no era un administrador, el servidor busca en el rdbm primario un usuario con ese nombre de usuario. Si el nombre de usuario no se corresponde con una sola entrada o la entrada no tiene un valor de contraseña de usuario, el servidor devuelve LDAP_INVALID_CREDENTIALS. También imprime el mensaje de error adecuado.
• realm -El valor del campo de dominio debe coincidir con el dominio en el que está configurado el servidor. Si el valor de dominio no coincide con el dominio en el que está configurado el servidor, el servidor devuelve LDAP_PROTOCOL_ERROR.
• nonce -El valor del campo nonce debe coincidir con el valor nonce que el servidor ha enviado al cliente con el digest-challenge. Si el valor no coincide, el servidor devuelve LDAP_PROTOCOL_ERROR.
• response -El valor del campo de respuesta contiene un hash de la contraseña. Para cada uno de los valores de contraseña de usuario que el servidor obtiene de la entrada de usuario, genera el hash DIGEST-MD5 . A continuación, el servidor lo compara con el hash del cliente. Si uno coincide, el servidor devuelve LDAP_SUCCESS y el usuario está enlazado como ese usuario. De lo contrario, el servidor devuelve LDAP_INVALID_CREDENTIALS e imprime un mensaje de error.
• authzid -El valor del campo authzid contiene un ID de autorización "dn:"- o "u:"-style de RFC 2829. El servidor utiliza RFC 2829 para la comprobación de autorización después del enlace, en lugar de la entrada encontrada para el nombre de usuario, similar a la autenticación de Proxied. La entrada a la que corresponde el nombre de usuario debe tener autorización para utilizar el otro DN. El servidor correlaciona el valor con una entrada similar al parámetro de nombre de usuario si authzid contiene un ID de autorización de "u:"-style . Si la correlación falla, el servidor devuelve LDAP_INVALID_CREDENTIALS.

Plugins SASL proporcionados por el usuario

El desarrollador de aplicaciones, o un tercero, puede implementar más mecanismos SASL utilizando el recurso de plug-in SASL de cliente C de Directory Server. Por ejemplo, se puede desarrollar un plug-in SASL de cliente y servidor que dé soporte a un nuevo mecanismo de autenticación basado en una exploración retinal. Si el mecanismo asociado con este nuevo mecanismo de autenticación es retscan, la aplicación llama a ldap_sasl_bind() con el mecanismo establecido en retscan. En función de cómo se diseñen el mecanismo y el plug-in, es posible que sea necesario que la aplicación proporcione también el DN y las credenciales del usuario. De forma alternativa, el propio plug-in puede ser responsable de obtener la identidad de usuario y las credenciales, que se derivan de alguna forma de una imagen de exploración de retina.

Si el plug-in de exploración de retina no está definido en ibmldap.conf, la aplicación debe registrar explícitamente el plug-in, utilizando ldap_register_plugin () API. Para obtener información sobre cómo definir un plug-in SASL para utilizarlo con una aplicación, consulte la sección Definición de un plug-in SASL en LDAP_BIND/UNBIND. Para obtener más información sobre cómo utilizar un plug-in de cliente LDAP, consulte LDAP_PLUGIN_REGISTRATION. Para obtener más información sobre el desarrollo de un plug-in de cliente LDAP, consulte Referencia de programación del plug-in de cliente LDAP.

try

Mecanismos SASL implementados por la aplicación

En algunos casos, es posible que el mecanismo SASL no requiera la presencia de un plug-in o cualquier soporte especial en la biblioteca LDAP. Si la aplicación puede llamar a la API ldap_sasl_bind() o ldap_sasl_bind_s() con los parámetros adecuados para el mecanismo, la biblioteca LDAP codifica la solicitud de enlace SASL y la envía al servidor. Si se define un plug-in para el mecanismo especificado, la solicitud se desvía al plug-in. La solicitud puede realizar más procesos antes de enviar el enlace SASL al servidor.

Mecanismos SASL soportados por el servidor LDAP

La aplicación puede consultar el DSE raíz del servidor LDAP, utilizando ldap_search() con los valores siguientes:

• DN base establecido en NULL
• ámbito que se establece en base
• filtro establecido en "(objectclass=*)"

Si el servidor LDAP da soporte a uno o más mecanismos SASL, los resultados de la búsqueda incluyen uno o más valores para el tipo de atributo mecanismos de soporte .

Definición de un plug-in SASL

Cuando la aplicación emite una API de ldap_sasl_bind_s() con un mecanismo soportado por un plug-in SASL determinado, la biblioteca LDAP debe poder localizar la biblioteca compartida del plug-in. Hay dos mecanismos disponibles para crear un plug-in de cliente LDAP conocido en la biblioteca LDAP:

• El plug-in para el mecanismo SASL especificado se define en el archivo ibmldap.conf .
• La aplicación registra explícitamente el plug-in utilizando la API ldap_register_plugin() .

Para obtener más información sobre cómo localizar una biblioteca de plugins y definir plugins en el archivo ibmldap.conf , consulte la sección Búsqueda de la biblioteca de plugins en LDAP_PLUGIN_REGISTRATION.

Desenlace

ldap_unbind_ext(), ldap_unbind()y ldap_unbind_s() son API síncronas. Envían una solicitud de desenlace al servidor. A continuación, cierran todas las conexiones abiertas que están asociadas con el descriptor de sesión LDAP. Posteriormente, desechan todos los recursos que están asociados con el descriptor de contexto de sesión antes de una devolución. No hay respuesta del servidor a una operación de desenlace de LDAP. Las tres funciones de desenlace devuelven LDAP_SUCCESS u otro código de error LDAP si la solicitud no se puede enviar al servidor LDAP. Después de una llamada a una de las funciones de desenlace, el descriptor de contexto de sesión ld no es válido y no es válido realizar más llamadas de API LDAP utilizando ld.

Las API ldap_unbind() y ldap_unbind_s() se comportan de forma idéntica. La API de ldap_unbind_ext() permite que los controles de servidor y cliente se incluyan explícitamente. Puesto que no hay ninguna respuesta del servidor a una solicitud de desenlace, por lo tanto, no puede recibir una respuesta a un control de servidor enviado con una solicitud de desenlace.

Volver a enlazar mientras se siguen las referencias

La llamada ldap_set_rebind_proc() se utiliza para establecer el punto de entrada de una rutina que se vuelve a llamar para obtener las credenciales de enlace para su uso cuando se contacta con un nuevo servidor después de una referencia LDAP o una referencia de búsqueda. Esta función sólo está disponible cuando se establece LDAP_OPT_REFERRALS , que es el valor predeterminado. Si nunca se llama a ldap_set_rebind_proc() , o si se llama con un parámetro rebindproc NULL, siempre se realiza un enlace LDAP simple no autenticado cuando se persiguen las referencias. Las características SSL de las conexiones con los servidores a los que se hace referencia se conservan cuando se persiguen las referencias. Además, si el enlace original era un enlace LDAP V3 , se utiliza un enlace LDAP V3 para conectarse a los servidores a los que se hace referencia. Si el enlace original era un enlace LDAP V2 , se utiliza un enlace LDAP V2 para conectarse a cada servidor al que se hace referencia.

rebindproc debe ser una función que se declare como se indica a continuación:

  int rebindproc( LDAP *ld, char **whop, char **credp,

      int *methodp, int freeit );

La biblioteca LDAP llama en primer lugar a rebindproc para obtener las credenciales de enlace de referencia y el parámetro freeit es cero. Los parámetros whop, credpy methodp deben establecerse según corresponda. Si rebindproc devuelve LDAP_SUCCESS, el proceso de referencia continúa y se llama a rebindproc una segunda vez con freeit distinto de cero para dar a la aplicación la posibilidad de liberar cualquier memoria asignada en la llamada anterior.

Si es distinto deLDAP_SUCCESSse devuelve mediante la primera llamada a rebindproc, el proceso de referencia se detiene y se devuelve el código de error para la operación LDAP original.

Errores

Retorno de rutinas asíncronas-1en caso de error. Sin embargo, en el caso de la rutina de enlace asíncrono ldap_sasl_bind(), devuelve un código de resultado LDAP distinto de LDAP_SUCCESS si la solicitud enviada no ha sido satisfactoria. Para obtener el código de resultado LDAP de la rutina de enlace asíncrono, ldap_sasl_bind(), utilice la API ldap_result() . Para obtener el error LDAP, utilice la API ldap_get_errno() . Las rutinas síncronas devuelven el código de error LDAP que resulta de la operación.

Consulte también

ldap_error, ldap_open