Historique de la page

Sommaire :

...

Cette page montre comment on peut accéder en lecture aux information contenues dans un annuaire LDAP. Pour un accès en écriture se référer à Accès à l'annuaire LDAP en écriture.

...

De nombreuses classes sont disponibles :

Manipulation des utilisateurs LDAP

Nous ne détaillons dans ce document que la manipulation des utilisateurs LDAP. Il sera facile au lecteur d'étendre les principes montrés ci-dessous à la manipulation des groupes et des entités LDAP quelconques.

Utilisation basique

L'implémentation utilisée pour manipuler seulement les utilisateurs LDAP est SearchableLdapUserServiceImpl.

La déclaration d'un bean ldapUserService de cette classe ressemblera à :

	<bean
  id="ldapUserService"
  		class="[org...]esupportail.commons.services.ldap.SearchableLdapUserServiceImpl"
  >
  		lazy-init="true"
		>
		<property name="ldapTemplatei18nService" ref="ldapTemplatei18nService" />
  		<property name="uidAttributeldapTemplate" valueref="uidldapTemplate" />
  		<property name="searchAttributednSubPath" value="cn" ${ldap.dnSubPath}"/>
  		<property name="idAttribute" value="searchDisplayedAttributes"${ldap.uidAttribute}"/>
		<property    <list>
      <value>displayName</value>
      <value>ur1composante</value>
      <value>ur1typeEntree</value>
    </list>
  </property>
  <property name="otherAttributes">
    <list>
      <value>homeDirectory</value>
    </list>
  </property>
  name="attributesAsString" value="${ldap.attributes}"/>
		<property name="searchAttribute" value="${ldap.searchAttribute}"/>
		<property name="searchDisplayedAttributesAsString" value="${ldap.searchDisplayedAttributes}" />
		<property name="cacheManager" ref="cacheManager"/>
		<property name="cacheName" value=""/>
		<property name="testFilter" value="cn=*bourges*${ldap.testFilter}" />
	</bean>

La propriété uidAttribute donne le nom de l'attribut LDAP qui contient l'identifiant unique des utilisateurs de l'annuaire.

La propriété searchAttributes donne le nom de l'attribut sur lequel on effectue des recherches. Dans l'exemple ci-dessous, la recherche du mot bourges utilisera le filtre cn=bourges*.

...

... avec dans config.properties :

########################################################################
# LDAP
#
ldap.url=ldap://ldap.univ.fr:389,ldap://ldap2.univ.fr:389
ldap.userDn=uid=user,ou=comptes,dc=univ,dc=fr
ldap.password=mdp
ldap.base=dc=univ,dc=fr
ldap.dnSubPath=ou=people
ldap.uidAttribute=uid
ldap.displayNameAttribute=displayName
ldap.emailAttribute=mail
ldap.searchAttribute=cn
ldap.testFilter=cn=*bourges*
ldap.attributes=cn,displayName,employeeType,department,homeDirectory
ldap.searchDisplayedAttributes=cn,displayName,employeeType,department

La propriété uidAttribute donne le nom de l'attribut LDAP qui contient l'identifiant unique des utilisateurs de l'annuaire.

La propriété searchAttributes donne le nom de l'attribut sur lequel on effectue des recherches. Dans l'exemple ci-dessous, la recherche du mot bourges utilisera le filtre cn=bourges*.

La propriété searchDisplayedAttributes donne les noms des attributs qui seront affichés à l'utilisateur lors du choix d'un utilisateur parmi plusieurs (après une recherche dans l'annuaire). Par exemple : Image Added
La propriété otherAttributes donne les noms des attributs qui seront remontés lors des requêtes LDAP, pour être utilisés dans du code Java.

La propriété testFilter pourra être utilisée dans les classes de test JUnit.

Cette classe s'appuie sur la bibliothèque LdapTemplate  org.springframework.ldap.core.LdapTemplate:

	<bean 
		id="ldapTemplate" 
		class="org.springframework.ldap.core.LdapTemplate"
		lazy-init="true"
		>		
		<property name="contextSource" ref="contextSource"/>
	</bean>

	<bean id="contextSource"
		class="org.esupportail.commons.services.ldap.MultiUrlLdapContextSource"
		lazy-init="true"
		>
		<property name="url" value="${ldap.url}"/>
		<property name="userDn" value="${ldap.userDn}"/>
		<property name="password" value="${ldap.password}"/>
		<property name="base" value="${ldap.base}"/>
		<property name="baseEnvironmentProperties">
			<map>
				<entry key="com.sun.jndi.ldap.connect.timeout"
					value="${ldap.connectTimeout}" />
			</map>
		</property>
	</bean>

Mise en cache des requêtes LDAP

Il est possible d'injecter un gestionnaire de cache aux instances de cette classe pour leur faire cacher le résultat des requêtes afin de moins solliciter l'annuaire LDAP (pour plus de performances).

Il suffit de rajouter à la déclaration précédente :

<bean
  id="ldapUserService"
  class="[...].commons.services.ldap.SearchableLdapUserServiceImpl"
  >
  ...

La propriété testFilter est utilisée par la tâche ant test-ldap.

...

<bean id="ldapTemplate" class="net.sf.ldaptemplate.LdapTemplate">
  <property name="contextSource" ref="contextSource" />
</bean>

<bean
    id="contextSource"
    class="net.sf.ldaptemplate.support.LdapContextSource">
  <property name="url" value="ldap://ldap.esup-portail.org:389" />
  <property name="userName" value="" />
  <property name="password" value="" />
  <property name="base" value="ou=people,dc=esup-portail,dc=org"/>
  <property name="baseEnvironmentPropertiescacheManager">
    <map>ref="cacheManager" />
      <entry key="com.sun.jndi.ldap.connect.timeout<property name="cacheName" value="5000" />
    </map>
  </property>
</bean>

Mise en cache des requêtes LDAP

Il est possible d'injecter un gestionnaire de cache aux instances de cette classe pour leur faire cacher le résultat des requêtes afin de moins solliciter l'annuaire LDAP (pour plus de performances).

Il suffit de rajouter à la déclaration précédente :

</bean>

Le bean cacheManager est en général défini dans le fichier de configuration /properties/cache/cache.xml et notamment /properties/cache/ehcache.xml Le nom du cache est optionnel.

 <cache 
    	name="org.esupportail

<bean
  id="ldapUserService"
  class="[...].commons.services.ldap.SearchableLdapUserServiceImplCachingLdapServiceImpl"
    	maxElementsInMemory="1000" >
    ...	eternal="false" 
  <property  name	timeToIdleSeconds="cacheManager300" ref
    	timeToLiveSeconds="cacheManager600" />
   <property name	overflowToDisk="cacheNametrue" value="" />
</bean>

Le bean cacheManager est en général défini dans le fichier de configuration /properties/cache/cache.xml. Le nom du cache est optionnel.

 
    	/>

Accès aux statistiques LDAP

La classe SearchableLdapUserServiceImpl supporte également la récupération de statistiques sur son utilisation, sous forme d'une liste de chaînes de caractères internationalisées (d'où la nécessité du service d'internationalisation i18nService). Ces chaînes peuvent par exemple être affichées sur l'interface d'une application web :

Accès LDAP hors connexion

De la même manière que la classe OfflineFixedUserAuthenticator pour l'authentification,  la classe OfflineLdapServiceImpl permet de travailler hors connexion :

<bean
  id="ldapService"
  class=" [...].commons.services.ldap.OfflineLdapServiceImpl"
  />

Applications sans accès LDAP

Les applications sans accès à l'annuaire LDAP doivent tout simplement ne pas déclarer de bean ldapUserService.

Utilisation du service LDAP depuis du code Java

Exceptions

Les exceptions lancées par les appels aux méthodes de LdapUserService peuvent lancer les exceptions suivantes :

• LdapConnectionException, lorsque l'annuaire LDAP est inaccessible,
• LdapBadFilterException, lorsqu'un mauvais filtre est utilisé,
• LdapMiscException, pour toute autre erreur. Image Removed

Image Added

Il appartient au programmeur d'attraper ou non ces exceptions en fonction du contexte de l'application.

Recherche d'un utilisateur par son identifiant

Pour rechercher un utilisateur LDAP à partir d'un identifiant par programmation, il faut appeler le service LDAP de la manière suivante :

...

private LdapUserService ldapUserService;
public void setLdapUserService(LdapUserService ldapUserService) {
    this.userLdapService = userLdapService;
}
...
public void validateMyInput(
            FacesContext context,
            UIComponent componentToValidate,
            Object value) throws ValidatorException {
    String string = (String) value;
    try {
      LdapUser ldapUser = ldapService.getLdapUser(string);
    } catch (UserNotFoundException e) {
      throw new ValidatorException(
          getFacesErrorMessage(
             "LDAP_SEARCH.MESSAGE.NO_RESULT", string));
        }
    }
}

<bean id="test1Controller" ... >
    <property name="ldapUserService" ref="ldapUserService" />
</bean>

Recherche des utilisateurs correspondant à un motif

Pour rechercher les utilisateurs LDAP à partir d'un motif, il faut appeler le service LDAP de la manière suivante :

...

La liste retournée peut éventuellement être vide.

Recherche des utilisateurs à partir d'un filtre LDAP

Pour rechercher les utilisateurs LDAP correspondant à un filtre LDAP, il faut appeler le service LDAP de la manière suivante :

...

La liste retournée peut éventuellement être vide.

Test d'un filtre LDAP

Pour tester la syntaxe d'un filtre LDAP, il faut appeler le service LDAP de la manière suivante :

...

Le filtre est valide si le message d'erreur retourné est null.

Vérification d'un filtre LDAP pour un utilisateur

Pour savoir si un utilisateur vérifie un filtre LDAP, il faut appeler le service de la manière suivante :

...

La méthode retourne true si l'utilisateur vérifie le filtre.

Récupération des statistiques LDAP

La récupération des statistiques des accès LDAP se fait en appelant le service LDAP de la manière suivante :

...

Intégration de la recherche d'utilisateurs dans les pages JSF

Nous montrons ici comment simplement inclure dans les pages web d'une application la recherche d'un utilisateur LDAP.

...

L'utilisateur doit alors pouvoir sélectionner un des utilisateurs (en cliquant dessus) et revenir sur la page administratorAdd.jsp, en remplissant sa boite de dialogue.Toute cette cinématique est disponible de base dans esup-commons, nous allons détailler cet exemple pour bien comprendre son fonctionnement.

Page appelante

Le contrôleur administratorsControler, chargé de toutes les interactions avec l'utilisateur pour la partie « administration » de l'application, implémente l'interface LdapCaller. Il possède donc une méthode setLdapUid() qui pourra être appelée par le contrôleur de la recherche LDAP en cas de succès. Cela remplira d'ailleurs automatiquement la boîte de dialogue de administratorAdd.jsp puisque celle-ci est liée à la propriété ldapUid du contrôleur administratorsControler :

...

<e:commandButton
    value="#{msgs['_.BUTTON.LDAP']}"
    action="ldapSearch"
    immediate="true">
  <t:updateActionListener
      value="#{administratorsController}"
      property="#{ldapSearchController.caller}" />
  <t:updateActionListener
      value="userSelectedToAdministratorAdd"
      property="#{ldapSearchController.successResult}" />
  <t:updateActionListener
      value="cancelToAdministratorAdd"
      property="#{ldapSearchController.cancelResult}" />
</e:commandButton>

Fonctionnement

Lorsque l'utilisateur appuie sur ce bouton, l'application :

...

La recherche LDAP proposée par esup-commons possède son propre code Java (le contrôleur ldapSearchController) et ses propres pages JSF (ldapSearch.jsp et ldapSearchResults.jsp), dont il n'est pas nécessaire de connaître le contenu pour les utiliser.

Règles de navigation

Il faut néanmoins indiquer à JSF les règles de navigation entre les différentes pages, comme indiqué ci-après (dans /properties/jsf/navigation-rules.xml).L'appui du bouton « Recherche LDAP » depuis la page administratorAdd.jsp envoie vers la page ldapSearch.jsp :

...

En procédant de cette manière, le développeur peut faire appel à la recherche LDAP en utilisant le même contrôleur (ldapSearchController) depuis plusieurs pages différentes (et donc plusieurs contrôleurs associés).

Manipulation des groupes LDAP

La manipulation des groupes LDAP se fait généralement en utilisant un bean ldapGroupService implémentant l'interface LdapGroupService, par exemple de la classe SearchableLdapGroupServiceImpl.

...

LdapGroup getLdapGroup(String id);
boolean groupMatchesFilter(String id, String filter);
List<LdapGroup> getLdapGroupsFromToken(String token);
List<LdapGroup> getLdapGroupsFromFilter(String filterExpr);
List<String> getSearchDisplayedAttributes();

Manipulation des utilisateurs et des groupes LDAP

esup-commons offre une classe qui permet de manipuler en même temps les utilisateurs et les groupes LDAP, SearchableLdapUserAndGroupServiceImpl.

...

List<String> getMemberIds(LdapGroup group);
List<LdapUser> getMembers(LdapGroup group);

Manipulation des entités LDAP quelconques

esup-commons permet enfin de manipuler n'importe quel type d'entité LDAP, à l'aide de la classe CachingLdapEntityServiceImpl.