Política de LDAP

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Qué

La política de LDAP proporciona lo siguiente:

  • Autenticación: Las credenciales de usuario proporcionadas en la solicitud se validan con las credenciales del proveedor de LDAP. La política LDAP te ofrece mucha flexibilidad con la autenticación, lo que te permite usar cualquier valor de DN junto con la contraseña, incluso si el valor de DN que deseas no está en la solicitud. Por ejemplo, supongamos que necesitas usar un correo electrónico o contraseña para la autenticación. Puedes acceder a las siguientes opciones:
    • Si el correo electrónico está en la solicitud, puedes usarlo con la contraseña para la autenticación LDAP.
    • Si el correo electrónico no está en la solicitud, pero sí otro atributo DN (como el número de teléfono), puedes usar el número de teléfono para obtener el correo electrónico correspondiente de LDAP y, luego, usar el correo electrónico o la contraseña para la autenticación.
  • Búsqueda de nombre distinguido (DN): Además de la autenticación, también puedes usar la política de LDAP para identificar un atributo de usuario en la solicitud, como el correo electrónico, y realizar una consulta que recupera otros atributos de DN de LDAP para ese usuario. El DN recuperado se almacena en una variable.

Usa la política de LDAP cuando el acceso a los recursos protegidos esté limitado a los usuarios de tu proveedor de LDAP, como los usuarios administradores, los usuarios de la organización y los desarrolladores, en especial si el acceso al token de OAuth es innecesario o demasiado pesado. La política también está diseñada para recuperar metadatos de nombres de dominio a fin de usarlos en flujos de proxy de API.

Por ejemplo, puedes hacer que se ejecute una llamada a la API solo cuando un usuario se autentique de forma correcta en LDAP y, de manera opcional, recuperar los atributos de DN (nombre de dominio) para el usuario después de que la autenticación se realice de forma correcta.

Para obtener información adicional, consulta:

Ejemplos

Autenticación de nombre de usuario y contraseña

<Ldap name="4GLdapPolicy">
   <LdapResource>ldap1</LdapResource>
   <Authentication>
       <UserName ref="request.header.username"/>
       <Password ref="request.header.password"/>
       <Scope>subtree</Scope>
       <BaseDN ref="apigee.baseDN"></BaseDN> <!-- default is dc=apigee,dc=com -->
    </Authentication>
 </Ldap>

En este ejemplo, se proporciona autenticación con un proveedor de LDAP. La política pasa el nombre de usuario y la contraseña de la solicitud a LDAP para la autenticación.

Autenticación de atributos DN

<Ldap name="LdapPolicy">
   <LdapResource>ldap1</LdapResource>
   <Authentication>
       <Password ref="request.header.password"/>
       <SearchQuery>mail={request.header.mail}</SearchQuery>
       <Scope>subtree</Scope>
       <BaseDN ref="apigee.baseDN"></BaseDN> <!-- default is dc=apigee,dc=com -->
    </Authentication>
 </Ldap>

Esta política obtiene el DN del usuario con el correo electrónico en el encabezado de la solicitud y, luego, lo autentica en LDAP con la contraseña proporcionada en el encabezado de la solicitud.

Buscando LDAP

<Ldap name="LdapPolicy">
    <!-- using a custom LDAP provider -->
    <LdapConnectorClass>com.custom.ldap.MyProvider</LdapConnectorClass>
    <LdapResource>MyLdap</LdapResource>
    <Search>
        <BaseDN ref="apigee.baseDN"></BaseDN> <!-- default is dc=apigee,dc=com -->
        <SearchQuery>mail={request.header.mail}</SearchQuery>
        <Attributes>
            <Attribute>address</Attribute>
            <Attribute>phone</Attribute>
            <Attribute>title</Attribute>
        </Attributes>
        <Scope></Scope> <!-- default is ‘subtree’ -->
    </Search>
</Ldap>

Esta política hace referencia a un proveedor de LDAP personalizado. Usa la dirección de correo electrónico en el encabezado de la solicitud para identificar al usuario y, luego, recupera la dirección, el teléfono y el título del usuario desde LDAP. Los atributos DN recuperados se almacenan en una variable. Consulta “Variables específicas de la política”.

Para buscar LDAP y recuperar atributos de DN, la solicitud debe incluir credenciales de administrador.

Referencia del elemento

A continuación, se describen los elementos y atributos de la política LDAP.

Elemento

Descripción

Ldap

Elemento superior con un atributo de nombre para que ingreses el nombre de la política.

LdapConnectorClass

Cuando uses la política de LDAP con un proveedor de LDAP personalizado (no proporcionado por Apigee), especifica la clase de conector LDAP completamente calificada. Esa es la clase en la que implementaste la interfaz ExternalLdapConProvider de Apigee.

LdapResource

Ingresa el nombre del entorno del recurso de LDAP. Consulta la sección sobre cómo crear un recurso de LDAP para obtener más información.

BaseDN

El nivel base de LDAP en el que existen todos tus datos. Por ejemplo, en el proveedor de LDAP de Apigee, todos los datos están en dc=apigee,dc=com.

  • ref: Se usa para especificar una variable de flujo que contiene el valor BaseDN, como apigee.baseDN. La ref tiene prioridad sobre un valor BaseDN explícito. Si especificas tanto la ref como el valor, ref tiene prioridad. Si la referencia no se resuelve en el tiempo de ejecución, se usa el valor.

Scope

  • object: La autenticación o la búsqueda se realizan solo en el nivel base de LDAP.
  • onelevel: La autenticación o la búsqueda se realiza un nivel por debajo del nivel base.
  • subtree (predeterminado): La autenticación o la búsqueda se realizan en el nivel de la base y de manera recursiva por completo debajo de la base.

Autenticación

Authentication

Es el elemento principal para el comportamiento de autenticación que implementas.

UserName

Elemento vacío que toma uno de los siguientes atributos:

  • ref: Una referencia al nombre de usuario en la solicitud, como request.header.username
  • value: Es el nombre de usuario en sí.

Si no autenticas con el nombre de usuario o si el nombre de usuario no está incluido en la solicitud, no necesitas incluir este elemento.

Si el nombre de usuario está en la solicitud, pero deseas autenticar a un usuario con un atributo DN que no sea el nombre de usuario (como el correo electrónico), incluye un SearchQuery para obtener el correo electrónico del usuario asociado con la contraseña. La política LDAP usa el nombre de usuario para consultar al proveedor de LDAP por la dirección de correo electrónico correspondiente, que luego se utiliza para la autenticación.

Password

Elemento vacío que toma uno de los siguientes atributos:

  • ref: Una referencia a la contraseña en la solicitud, como request.header.password
  • value: La propia contraseña encriptada

SearchQuery

Si deseas autenticar con un atributo DN que no sea el nombre de usuario, como el correo electrónico, configura la política de LDAP para obtener un atributo DN de la solicitud (como el nombre de usuario), que se usa para identificar al usuario en LDAP, recuperar el correo electrónico y autenticar al usuario.

Por ejemplo, suponiendo que LDAP define un atributo de “correo electrónico” para almacenar una dirección de correo electrónico:

<SearchQuery>mail={request.header.mail}</SearchQuery>

Búsqueda

Search

Es el elemento principal del comportamiento de búsqueda que implementas.

SearchQuery

Si identificas al usuario con metadatos en la solicitud o respuesta, puedes usar este elemento a fin de recuperar atributos de DN adicionales para el usuario desde LDAP. Por ejemplo, si la solicitud contiene el correo electrónico del usuario y tu LDAP define un atributo mail para almacenar direcciones de correo electrónico del usuario, deberías usar la siguiente configuración:

<SearchQuery>mail={request.header.mail}</SearchQuery>

Esta consulta busca en LDAP un correo electrónico que coincida con el de la solicitud y la política ahora puede recuperar atributos de DN adicionales para ese usuario con el elemento Attributes.

Attributes

Usa uno o más elementos <Attribute> para identificar los metadatos del DN que deseas recuperar para el usuario. Se requiere al menos un atributo.

Por ejemplo, después de que la SearchQuery identifica al usuario, la política ahora puede recuperar atributos de DN para el usuario, como la dirección, el número de teléfono y el título del usuario, como se muestra en el siguiente ejemplo.

Los valores de los atributos son los nombres de atributos de DN definidos en tu LDAP.

<Attributes>
  <Attribute>address</Attribute>
  <Attribute>phone</Attribute>
  <Attribute>title</Attribute>
</Attributes>

Notas de uso

Apigee Edge para nube privada te permite aprovechar un proveedor de LDAP en las llamadas a la API. Con la política de LDAP, las aplicaciones pueden autenticar credenciales en los usuarios almacenados en LDAP, y puedes recuperar nombres distinguidos (DN) de LDAP: los metadatos o atributos asociados con cada usuario, como el correo electrónico, la dirección y el número de teléfono. El DN que se muestra se almacena en una variable para que el proxy de la API lo use más.

Crea un recurso de LDAP

La política de LDAP aprovecha un recurso LDAP que crea en Apigee Edge. Un recurso de LDAP proporciona la información de conexión al repositorio de LDAP.

Para crear y administrar recursos LDAP, usa la siguiente API y carga útil:

API

Crea (POST) un recurso de LDAP o genera una lista (GET) de todos los recursos de LDAP:

/v1/organizations/org_name/environments/environment/ldapresources

Obtén detalles sobre (GET), actualiza (POST) y borra (DELETE) un recurso de LDAP:

/v1/organizations/org_name/environments/environment/ldapresources/ldap_resource_name

Carga útil

A continuación, se incluye un ejemplo de carga útil de XML con comentarios de uso.

<LdapResource name="ldap1">
  <Connection>
    <Hosts>
      <!-- port is optional: defaults to 389 for ldap:// and 636 for ldaps:// -->
      <Host port="636">foo.com</Host>
    </Hosts>
    <SSLEnabled>false</SSLEnabled> <!-- optional, defaults to false -->
    <Version>3</Version> <!-- optional, defaults to 3-->
    <Authentication>simple</Authentication> <!-- optional, only simple supported -->
    <ConnectionProvider>jndi|unboundid</ConnectionProvider> <!-- required -->
    <ServerSetType>single|round robin|failover</ServerSetType> <!-- not applicable for jndi -->
    <!-- If using a custom LDAP provider, the fully qualified class: -->
    <LdapConnectorClass>com.custom.ldap.MyProvider</LdapConnectorClass>
  </Connection>
  <ConnectPool enabled="true"> <!-- enabled is optional, defaults to true -->
    <Timeout>30000</Timeout> <!-- optional, in milliseconds; if not set, no timeout -->
    <Maxsize>50</Maxsize> <!-- optional; if not set, no max connections -->
    <Prefsize>30</Prefsize> <!-- optional; if not set, no pref size -->
    <Initsize></Initsize> <!-- optional; if not set, defaults to 1 -->
    <Protocol></Protocol> <!-- optional; if not set, defaults to 'ssl plain' -->
  </ConnectPool>
  <Admin>
    <DN>cn=manager,dc=apigee,dc=com</DN>
    <Password>secret</Password>
  </Admin>
</LdapResource>

Ejemplo de curl: Crea un recurso de LDAP

En el siguiente ejemplo, se crea un recurso LDAP llamado ldap1.

curl -X POST -H "Content-Type: application/xml" \
  https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/ldapresources \
  -u apigee_email:password -d \
  '<LdapResource name="ldap1">
    <Connection>
      <Hosts>
      <Host>foo.com</Host>
      </Hosts>
      <SSLEnabled>false</SSLEnabled>
      <Version>3</Version>
      <Authentication>simple</Authentication>
      <ConnectionProvider>unboundid</ConnectionProvider>
      <ServerSetType>round robin</ServerSetType>
    </Connection>
    <ConnectPool enabled="true">
      <Timeout>30000</Timeout>
      <Maxsize>50</Maxsize>
      <Prefsize>30</Prefsize>
      <Initsize></Initsize>
      <Protocol></Protocol>
    </ConnectPool>
    <Admin>
      <DN>cn=manager,dc=apigee,dc=com</DN>
      <Password>secret</Password>
    </Admin>
  </LdapResource>'

Códigos de respuesta

A continuación, se indican los códigos de respuesta HTML que la política muestra para indicar si la solicitud se realizó correctamente o no:

  • Listo: 200
  • Error: 401

Usa un proveedor de LDAP personalizado en Edge para la nube privada

Usa un proveedor de LDAP personalizado

Apigee Edge para nube privada incluye un proveedor de LDAP que ya está configurado para interactuar con la política de LDAP. Sin embargo, si usas un proveedor de LDAP personalizado, debes habilitarlo para que admita la política de LDAP. Para ello, siga estos pasos:

  1. En la clase de tu proveedor de LDAP, implementa la interfaz ExternalLdapConProvider.
    public interface ExternalLdapConProvider {
      void doAuthentication(LdapBean LlapBean, String userDN, String password, String baseDN);
    
      void doSearchAndAuthentication(LdapBean LlapBean, String password, String baseDN, String query, int scope);
    
      Collection<Map<String, String[]>> doSearch(LdapBean LlapBean, String query,
        String baseDN, Collection<String> requiredAttributes, int scope);
    
      void closeConnections();
    }
  2. En el <LdapConnectorClass> de la configuración de la política (próximas secciones), agrega el nombre de la clase completamente calificado de tu proveedor de LDAP personalizado.
  3. Descarga este archivo: custom-ldap.jar_.zip. (Es posible que debas hacer clic con el botón derecho y seleccionar Guardar como).
  4. Descomprímelo.
  5. Agrega el archivo custom-ldap.jar a tu entorno y asegúrate de que esté en tu ruta de clase.
  6. Crea un recurso de entorno para tu proveedor de LDAP. Usarás el nombre del recurso del entorno en el elemento <LdapResource> de la política de LDAP.

Usa el SDK de LDAP UnboundID para Java

Puedes usar el SDK de LDAP UnboundID con la política LDAP, pero primero debes descargar la versión 2.3.1 y agregarla a cada una de las rutas de clase del procesador de mensajes.

Para usar el SDK de LDAP UnboundID con la política LDAP, siga estos pasos:

  1. Abre un navegador y ve al repositorio de archivos de Sourceforge para el SDK de LDAP UnboundID:
    https://sourceforge.net/projects/ldap-sdk/files/
  2. Busca la versión 2.3.1 (SE o Standard Edition) del SDK y descarga el archivo ZIP de esa versión. Por ejemplo, descarga "unboundid-ldapsdk-2.3.1-se.zip".
  3. Extrae el archivo JAR del archivo ZIP del SDK, como se muestra en el siguiente ejemplo:
    unzip -j -d ~/tmp ~/Downloads/unboundid-ldapsdk-2.3.1-se.zip unboundid-ldapsdk-2.3.1-se/unboundid-ldapsdk-se.jar

    Con este comando, se extrae solo el archivo JAR en el directorio ~/tmp. Quita la estructura del directorio con -j, aunque esto es opcional.

  4. En cada nodo de Message Processor, haz lo siguiente:
    1. Copia el archivo JAR en el directorio /opt/apigee/edge-gateway/lib/thirdparty de Message Processor.
    2. Si es necesario, otorga permiso de usuario a Apigee sobre el archivo JAR para que el procesador de mensajes pueda acceder a él.
    3. Edge agrega todas las bibliotecas de terceros que se encuentren en el directorio /opt/apigee/edge-gateway/lib/thirdparty a la ruta de clase.

    4. Reinicia Message Processor:
      /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Variables de flujo

A continuación, se presentan las variables de política LDAP propagadas por un SearchQuery.

Variable

Descripción

ldap.policyName.execution.success

Después de que se ejecuta la política, esta variable de flujo contiene un valor de “true” o “false”, según el resultado.

ldap.policyName.search.result[index].
  attribute.attrName[index]=value

El formato flexible de esta variable, el índice en particular: considera varios atributos, así como atributos con varios valores. El índice es un número que comienza en 1. Si no se proporciona un número de índice, el predeterminado es 1.

Si la política muestra la dirección, el teléfono y el correo electrónico, puedes recuperar el primer atributo y valor mediante estas variables:

ldap.policyName.search.result.attribute.address
ldap.policyName.search.result.attribute.phone
ldap.policyName.search.result.attribute.email

Si deseas recuperar el tercer atributo de dirección en los resultados de la búsqueda, debes usar lo siguiente:

ldap.policyName.search.result[3].attribute.address

Si un atributo tiene varios valores (por ejemplo, si un usuario tiene varias direcciones de correo electrónico), recuperarías la segunda dirección de correo electrónico de los resultados de la siguiente manera:

ldap.policyName.search.result.attribute.mail[2]

Códigos de error

Los errores que muestran las políticas de Edge siguen un formato coherente, como se describe en la Referencia de códigos de error.

Esta política usa los siguientes códigos de error:

Código de error Mensajes
InvalidAttributeName Invalid attribute name {0}.
InvalidSearchBase Search base can not be empty.
InvalidValueForPassword Invalid value for password field. It can not be empty.
InvalidSearchScope Invalid scope {0}. Allowed scopes are {1}.
InvalidUserCredentials Invalid user credentials.
InvalidExternalLdapReference Invalid external ldap reference {0}.
LdapResourceNotFound Ldap resource {0} not found.
BaseDNRequired Base DN required.
OnlyReferenceOrValueIsAllowed Only value or reference is allowed for {0}.
AttributesRequired At least one attribute required for search action.
UserNameIsNull User name is null.
SearchQueryAndUserNameCannotBePresent Both search query and username can not be present in the authentication action. Please specify either one of them.