Règle LDAP

Vous consultez la documentation d'Apigee Edge.
Consultez la documentation Apigee X. en savoir plus

Quoi

La stratégie LDAP fournit:

• Authentification: les identifiants de l'utilisateur fournis dans la requête sont validés par rapport à ceux du fournisseur LDAP. La stratégie LDAP vous offre une grande flexibilité pour l'authentification : vous pouvez utiliser n'importe quelle valeur de nom distinctif avec le mot de passe, même si la valeur souhaitée ne figure pas dans la requête. Par exemple, supposons que vous deviez utiliser une adresse e-mail / 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 de nom distinctif l'est (numéro de téléphone, par exemple), vous pouvez utiliser le numéro de téléphone pour obtenir l'adresse e-mail correspondante à partir du protocole LDAP, puis vous authentifier à l'aide d'une adresse e-mail/d'un mot de passe.
• Recherche de nom distinctif (DN): en plus de l'authentification, vous pouvez également utiliser la stratégie LDAP pour identifier un attribut utilisateur dans la requête, comme l'adresse e-mail, et exécuter une requête qui récupère d'autres attributs de nom distinctif de LDAP pour cet utilisateur. Le nom distinctif 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 les administrateurs, les utilisateurs de l'organisation et les développeurs), en particulier lorsque l'accès par 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 d'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. Vous pouvez éventuellement récupérer les attributs DN (nom de domaine) de l'utilisateur une fois l'authentification effectuée.

Pour en savoir plus, consultez les pages suivantes :

• Gérer la stratégie de mot de passe LDAP par défaut pour la gestion des API
• "Informations importantes sur les règles relatives à vos mots de passe" dans la communauté Apigee

Samples

<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 une description des éléments et attributs de la règle LDAP.

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

Remarques sur l'utilisation

Apigee Edge pour Private Cloud vous permet d'exploiter un fournisseur LDAP dans les appels d'API. Avec la règle LDAP, les applications peuvent authentifier les identifiants auprès des utilisateurs stockés dans LDAP et vous pouvez récupérer les noms distinctifs (DN) à partir de LDAP, c'est-à-dire les métadonnées ou attributs associés à chaque utilisateur (adresse e-mail, adresse postale et numéro de téléphone, par exemple). Le nom distinctif renvoyé est stocké dans une variable pour une utilisation ultérieure par le proxy d'API.

Créer une ressource LDAP

La stratégie LDAP exploite une ressource LDAP que vous avez créée 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 répertoriez (GET) toutes les ressources LDAP:

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

Obtenez les informations concernant (GET), la modification (POST) et la suppression (DELETE) d'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 stratégie en cas de réussite ou d'échec:

• Réussite: 200
• Échec: 401

Utilisation d'un fournisseur LDAP personnalisé dans Edge for Private Cloud

Utiliser un fournisseur LDAP personnalisé

Apigee Edge pour 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 l'activer pour qu'il soit compatible avec la règle LDAP. Procédez comme suit :

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 champ <LdapConnectorClass> de la configuration de la stratégie (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 effectuer un clic droit 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 chemin de classe.
6. Créez une ressource d'environnement pour votre fournisseur LDAP. Vous utiliserez le nom de 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 stratégie LDAP, mais vous devez d'abord télécharger la version 2.3.1 et l'ajouter à chacun des classpaths de votre processeur 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 du SDK LDAP UnboundID :

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

2. Recherchez la version 2.3.1 (SE ou Édition Standard) du SDK et téléchargez le fichier ZIP correspondant à cette version. Par exemple, téléchargez "unboundid-ldapsdk-2.3.1-se.zip".
3. Extrayez le fichier JAR du fichier ZIP du SDK, comme indiqué 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épertoires 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'utilisateur Apigee l'autorisation d'accéder au fichier JAR afin que le processeur de messages puisse y accéder.

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

   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 règle LDAP renseignées par 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 stratégies Edge suivent un format cohérent, comme décrit dans la référence du code d'erreur.

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