Règle LDAP

Vous consultez la documentation Apigee Edge.
Accédez à la documentation Apigee X.

Quoi

La règle LDAP fournit les éléments suivants :

• Authentification : les identifiants utilisateur fournis dans la requête sont validés par rapport aux identifiants du fournisseur LDAP. La règle LDAP vous offre une grande flexibilité en matière d' authentification, car elle vous permet d'utiliser n'importe quelle valeur DN avec le mot de passe, même si cette valeur DN souhaitée ne figure pas dans la requête. Supposons, par exemple, que vous deviez utiliser une adresse e-mail et un mot de passe pour l'authentification. Les options suivantes sont possibles :
  • Si l'adresse e-mail figure dans la requête, vous pouvez simplement l'utiliser avec le mot de passe pour l'authentification LDAP.
  • Si l'adresse e-mail ne figure pas dans la requête, mais qu'un autre attribut DN y figure (par exemple, un numéro de téléphone), vous pouvez utiliser le numéro de téléphone pour obtenir l'adresse e-mail correspondante à partir de LDAP, puis utiliser l'adresse e-mail / et le mot de passe pour vous authentifier.
• Recherche de nom distinctif (DN) : en plus de l'authentification, vous pouvez également utiliser la règle LDAP pour identifier un attribut utilisateur dans la requête, tel qu'une adresse e-mail, et exécuter une requête qui récupère d'autres attributs DN à partir de LDAP pour cet utilisateur. Le DN récupéré est stocké dans une variable.

Utilisez la règle LDAP lorsque l'accès aux ressources protégées doit être limité aux utilisateurs de votre fournisseur LDAP , tels que vos utilisateurs administrateurs, les utilisateurs de l'organisation et les développeurs, en particulier lorsque l'accès au jeton OAuth est inutile ou trop lourd. La règle est également conçue pour récupérer les métadonnées de nom de domaine à utiliser dans les flux de proxy API.

Par exemple, vous pouvez faire en sorte qu'un appel d'API ne s'exécute que lorsqu'un utilisateur est authentifié auprès de LDAP, puis récupérer éventuellement les attributs DN (nom de domaine) de l'utilisateur une fois l'authentification réussie.

Pour en savoir plus, consultez les pages suivantes :

• Gérer la règle de mot de passe LDAP par défaut pour la gestion des API
• "Informations importantes concernant votre règle de mot de passe" dans la communauté Apigee

Exemples

<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>

<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>

<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>

Documentation de référence des éléments

Vous trouverez ci-dessous des descriptions des éléments et des attributs de la règle LDAP.

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

Remarques sur l'utilisation

Apigee Edge pour le cloud privé vous permet d'exploiter un fournisseur LDAP dans les appels d'API. Avec la règle LDAP , les applications peuvent authentifier les identifiants par rapport aux utilisateurs stockés dans LDAP, et vous pouvez récupérer les noms distinctifs (DN) à partir de LDAP : les métadonnées ou attributs associés à chaque utilisateur, tels que l'adresse e-mail, l'adresse et le numéro de téléphone. Le DN renvoyé est stocké dans une variable pour être utilisé ultérieurement par le proxy API.

Créer une ressource LDAP

La règle LDAP exploite une ressource LDAP que vous créez dans Apigee Edge. Une ressource LDAP fournit les informations de connexion à votre dépôt LDAP.

Pour créer et gérer des ressources LDAP, utilisez l'API et la charge utile suivantes :

API

Créez (POST) une ressource LDAP ou listez (GET) toutes les ressources LDAP :

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

Obtenez des détails (GET), mettez à jour (POST) et supprimez (DELETE) une ressource LDAP :

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

Charge utile

Voici un exemple de charge utile XML avec des commentaires d'utilisation.

<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>

Exemple curl : créer une ressource LDAP

L'exemple suivant crée une ressource LDAP nommée 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>'

Codes de réponse

Voici les codes de réponse HTML renvoyés par la règle en cas de succès ou d'échec :

• Opération réussie : 200
• Échec : 401

Utiliser un fournisseur LDAP personnalisé dans Edge pour le cloud privé

Utiliser un fournisseur LDAP personnalisé

Apigee Edge pour le cloud privé est fourni avec un fournisseur LDAP déjà configuré pour interagir avec la règle LDAP. Toutefois, si vous utilisez un fournisseur LDAP personnalisé, vous devez activer le fournisseur pour qu'il soit compatible avec la règle LDAP. Pour ce faire :

1. Dans la classe de votre fournisseur LDAP, implémentez l'interface 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. Dans le <LdapConnectorClass> de la configuration de la règle (sections suivantes), ajoutez le nom de classe complet de votre fournisseur LDAP personnalisé.
3. Téléchargez ce fichier : custom-ldap.jar_.zip. (Vous devrez peut-être cliquer avec le bouton droit de la souris et sélectionner Enregistrer sous.)
4. Décompressez-le.
5. Ajoutez le fichier custom-ldap.jar à votre environnement et assurez-vous qu'il se trouve dans votre classpath.
6. Créez une ressource d'environnement pour votre fournisseur LDAP. Vous utiliserez le nom de la ressource d'environnement dans l'élément <LdapResource> de la règle LDAP.

Utiliser le SDK LDAP UnboundID pour Java

Vous pouvez utiliser le SDK LDAP UnboundID avec la règle LDAP, mais vous devez d'abord télécharger la version 2.3.1 et l'ajouter au classpath de chacun de vos processeurs de messages.

Pour utiliser le SDK LDAP UnboundID avec la règle LDAP :

1. Ouvrez un navigateur et accédez au dépôt de fichiers Sourceforge pour le SDK LDAP UnboundID :

   https://sourceforge.net/projects/ldap-sdk/files/

2. Recherchez la version 2.3.1 (SE ou Standard Edition) du SDK et téléchargez le fichier ZIP correspondant. Par exemple, téléchargez "unboundid-ldapsdk-2.3.1-se.zip".
3. Extrayez le fichier JAR du fichier ZIP du SDK, comme illustré dans l'exemple suivant :

   unzip -j -d ~/tmp ~/Downloads/unboundid-ldapsdk-2.3.1-se.zip unboundid-ldapsdk-2.3.1-se/unboundid-ldapsdk-se.jar

   Cette commande extrait uniquement le fichier JAR dans le répertoire ~/tmp. Elle supprime la structure de répertoire avec -j, bien que cela soit facultatif.

4. Sur chaque nœud de processeur de messages :
   1. Copiez le fichier JAR dans le répertoire /opt/apigee/edge-gateway/lib/thirdparty du processeur de messages.
   2. Si nécessaire, accordez l'autorisation d'utilisateur Apigee sur le fichier JAR afin que le processeur de messages puisse y accéder.

   Edge ajoute toutes les bibliothèques tierces du /opt/apigee/edge-gateway/lib/thirdparty répertoire au classpath.

   3. Redémarrez le processeur de messages :

      /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

Variables de flux

Voici les variables de la règle LDAP renseignées par une SearchQuery.

ldap.policyName.execution.success

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

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

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

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

Codes d'erreur

Les erreurs renvoyées par les règles Edge suivent un format cohérent, comme décrit dans la Documentation de référence sur les codes d'erreur.

Cette règle utilise les codes d'erreur suivants: