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
Authentification par nom d'utilisateur/mot de passe
<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>
Cet exemple fournit une authentification auprès d'un fournisseur LDAP. La règle transmet le nom d'utilisateur et le mot de passe de la requête à LDAP pour l'authentification.
Authentification par attribut 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>
Cette règle récupère le nom distinctif de l'utilisateur avec l'adresse e-mail figurant dans l'en-tête de requête, puis authentifie l'utilisateur auprès du protocole LDAP à l'aide du mot de passe fourni dans l'en-tête de requête.
Recherche 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>
Cette règle fait référence à un fournisseur LDAP personnalisé. Elle utilise l'adresse e-mail dans l'en-tête de requête pour identifier l'utilisateur, puis récupère l'adresse, le numéro de téléphone et la fonction de l'utilisateur à partir de LDAP. Les attributs DN récupérés sont stockés dans une variable. Consultez la section "Variables spécifiques aux règles".
Pour effectuer une recherche sur LDAP et récupérer des attributs DN, la requête doit inclure des identifiants d'administrateur.
Documentation de référence des éléments
Vous trouverez ci-dessous une description des éléments et attributs de la règle LDAP.
Élément |
Description |
---|---|
|
Élément parent avec un attribut name pour que vous puissiez saisir le nom de la règle. |
|
Lorsque vous utilisez la stratégie LDAP avec un fournisseur LDAP personnalisé (non fourni par Apigee), spécifiez la classe de connecteur LDAP complète.
Il s'agit de la classe dans laquelle vous avez mis en œuvre l'interface |
|
Saisissez le nom d'environnement de la ressource LDAP. Pour en savoir plus, consultez la section Créer une ressource LDAP. |
|
Niveau de base de LDAP sous lequel existent toutes vos données. Par exemple, dans le fournisseur LDAP d'Apigee, toutes les données se trouvent sous
|
|
|
Authentification |
|
|
Élément parent du comportement d'authentification que vous implémentez. |
|
Élément vide qui accepte l'un des attributs suivants:
Si vous ne vous authentifiez pas à l'aide d'un nom d'utilisateur ou si le nom d'utilisateur n'est pas inclus dans la requête, vous n'avez pas besoin d'inclure cet élément. Si la requête contient un nom d'utilisateur, mais que vous souhaitez authentifier un utilisateur avec un attribut de nom distinctif autre que le nom d'utilisateur, tel qu'une adresse e-mail, incluez un |
|
Élément vide qui accepte l'un des attributs suivants:
|
|
Si vous souhaitez vous authentifier à l'aide d'un attribut DN autre que le nom d'utilisateur, tel que l'adresse e-mail, configurez la stratégie LDAP pour obtenir un attribut DN de la requête (par exemple, username), qui permet d'identifier l'utilisateur dans LDAP, de récupérer l'e-mail et d'authentifier l'utilisateur. Supposons par exemple que LDAP définisse un attribut "mail" pour stocker une adresse e-mail:
|
Rechercher |
|
|
Élément parent du comportement de recherche que vous implémentez. |
|
En identifiant l'utilisateur à l'aide de métadonnées dans la requête ou la réponse, vous pouvez utiliser cet élément pour récupérer des attributs DN supplémentaires pour l'utilisateur à partir de LDAP. Par exemple, si la requête contient l'adresse e-mail de l'utilisateur et que votre LDAP définit un attribut
Cette requête recherche dans LDAP une adresse e-mail correspondant à l'adresse e-mail de la requête. La règle peut désormais récupérer des attributs DN supplémentaires pour cet utilisateur grâce à l'élément Attributes. |
|
Utilisez un ou plusieurs éléments Par exemple, une fois que Les valeurs d'attribut sont les noms d'attributs DN définis dans votre protocole 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 :
- 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(); }
- Dans le champ
<LdapConnectorClass>
de la configuration de la stratégie (sections suivantes), ajoutez le nom de classe complet de votre fournisseur LDAP personnalisé. - Téléchargez ce fichier: custom-ldap.jar_.zip. Vous devrez peut-être effectuer un clic droit et sélectionner Enregistrer sous.
- Décompressez-le.
- Ajoutez le fichier custom-ldap.jar à votre environnement et assurez-vous qu'il se trouve dans votre chemin de classe.
- 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:
- Ouvrez un navigateur et accédez au dépôt de fichiers Sourceforge du SDK LDAP UnboundID :
https://sourceforge.net/projects/ldap-sdk/files/
- 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".
- 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. - Sur chaque nœud de processeur de messages:
- Copiez le fichier JAR dans le répertoire
/opt/apigee/edge-gateway/lib/thirdparty
du processeur de messages. - 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.
- Redémarrez le processeur de messages :
/opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
Edge ajoute toutes les bibliothèques tierces du répertoire
/opt/apigee/edge-gateway/lib/thirdparty
au chemin de classe. - Copiez le fichier JAR dans le répertoire
Variables de flux
Voici les variables de règle LDAP renseignées par SearchQuery
.
Variable |
Description |
---|---|
ldap.policyName.execution.success |
Une fois la règle exécutée, cette variable de flux contient la valeur "true" ou "false", en fonction du résultat. |
ldap.policyName.search.result[index]. attribute.attrName[index]=value |
Format flexible de cette variable, en particulier l'index: prend en compte plusieurs attributs ainsi que ceux à plusieurs valeurs. L'index est un nombre qui commence à 1. Si aucun numéro d'index n'est fourni, le numéro d'index par défaut est 1. Si la règle renvoie l'adresse, le numéro de téléphone et l'adresse e-mail, vous pouvez récupérer le premier attribut et la première valeur à l'aide des variables suivantes: ldap.policyName.search.result.attribute.address ldap.policyName.search.result.attribute.phone ldap.policyName.search.result.attribute.email Si vous souhaitez récupérer le troisième attribut d'adresse dans les résultats de recherche, utilisez le code suivant: ldap.policyName.search.result[3].attribute.address Si un attribut possède plusieurs valeurs (par exemple, si un utilisateur possède plusieurs adresses e-mail), vous récupérez la deuxième adresse e-mail des résultats comme suit: 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:
Code d'erreur | d'un message ; |
---|---|
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. |