Voir la source de Java:Accès à un LDAP

== But ==
Un [[Linux:Configuration d'OpenLDAP|serveur LDAP]] est avant tout une base de données, mais dont le modèle de données est standardisé. Grâce à cela, plusieurs applications peuvent partager les mêmes données. L'exemple le plus parlant sont les comptes et les groupes d'utilisateurs: dans un réseau d'entreprise, une application qui gère ses utilisateurs à partir d'un [[Linux:Configuration d'OpenLDAP|LDAP]] est un plus.

== Préliminaire ==
Avant de commencer à développer des accès à un [[Linux:Configuration d'OpenLDAP|LDAP]], il est impératif de procéder à [[Linux:Configuration d'OpenLDAP|l'installation d'un serveur LDAP]].

== Connexion/Déconnexion à un serveur LDAP ==
Pour se connecter à un [[Linux:Configuration d'OpenLDAP|serveur LDAP]]:
 final Hashtable<String, String> env = new Hashtable<String, String> ();
 env.put (Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
 env.put (Context.PROVIDER_URL, "ldap://ldap.minetti.org/ou=people,ou=localnet,dc=minetti,dc=org");
 env.put (Context.SECURITY_AUTHENTICATION, "simple");
 env.put (Context.SECURITY_PRINCIPAL, "cn=admin,ou=sysaccount,ou=localnet,dc=minetti,dc=org");
 env.put (Context.SECURITY_CREDENTIALS, "mypassword");
 final LdapContext context = new InitialLdapContext (env, null);
Ici, on se connecte au serveur '''ldap.minetti.org''' à partir du noeud '''ou=people,ou=localnet,dc=minetti,dc=org''' et sous le compte '''admin''' (cn=admin,ou=sysaccount,ou=localnet,dc=minetti,dc=org).

La connexion sera encapsulé dans une instance de la classe [http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/InitialLdapContext.html javax.naming.ldap.InitialLdapContext] (qui implémente l'interface [http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/LdapContext.html javax.naming.ldap.LdapContext]).

Pour se déconnecter:
 context.close ();

== Recherche d'entités ==
La plupart des recherches retournent une instance de [http://docs.oracle.com/javase/6/docs/api/javax/naming/NamingEnumeration.html javax.naming.NamingEnumeration] représentant une énumération de [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/SearchResult.html javax.naming.directory.SearchResult]. Chaque [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/SearchResult.html SearchResult] embarque une entité à travers une instance de [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/Attributes.html javax.naming.directory.Attributes]. C'est à travers cette instance que l'on pourra récupérer toutes les données d'une entité.
 final NamingEnumeration<SearchResult> resultEnumeration = context.search (...);
 while (resultEnumeration.hasMore ()) {
    final SearchResult entry = resultEnumeration.next ();
    final LdapName dn = new LdapName (Rdn.unescapeValue (entry.getNameInNamespace ()).toString ());
    final Attributes attributes = entry.getAttributes ();
    ...
 }

=== Par le distinguished name (DN) ===
Pour rechercher une entitée par son DN:
 final Attributes attributes = context.getAttributes (new LdapName("uid=" + Rdn.escapeValue (uid)));

La recherche par DN est la seule qui nous garantie un résultat unique: c'est la seule recherche qui retourne directement une instance [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/Attributes.html javax.naming.directory.Attributes].

Le DN indiqué ne doit pas contenir la base DN mentionnée lors de la [[Java:Accès à un LDAP#Connexion/Déconnexion à un serveur LDAP|connexion]] (dans notre exemple: ''ou=people,ou=localnet,dc=minetti,dc=org''). La recherche commencera à partir des noeuds enfants de la base DN.

Il est vivement recommandé de placer les DN dans une instance [http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/LdapName.html javax.naming.ldap.LdapName] et de formater sa valeur à l'aide de la méthode [http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/Rdn.html#escapeValue(java.lang.Object) escapeValue(...)] de [http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/Rdn.html javax.naming.ldap.Rdn]. En effet, certains caractères (comme espace , = + < > # ; " \) sont réservé et ne peuvent se trouver dans la valeur d'un attribut du DN. Pour rappel un DN est de la forme: attribut1=valeur1,attribut2=valeur2,attribut3=valeur3 (exemple: ou=people,ou=localnet,dc=minetti,dc=org).

=== Par type d'entités uniquement ===
Pour retourner toutes les entités d'un même type (par exemple: inetOrgPerson):
 final SearchControls searchControls = new SearchControls ();
 searchControls.setSearchScope (SearchControls.ONELEVEL_SCOPE);
 final NamingEnumeration<SearchResult> resultEnumeration = context.search ("", "(objectClass=inetOrgPerson)", searchControls);
Ici, l'instance [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/SearchControls.html javax.naming.directory.SearchControls] permet d'indiquer où se fera notre recherche. On peut ainsi paramétrer notre recherche sur:
* ONELEVEL_SCOPE pour rechercher uniquement au niveau de notre base DN indiquée lors de la [[Java:Accès à un LDAP#Connexion/Déconnexion à un serveur LDAP|connexion]] (dans notre exemple: ''ou=people,ou=localnet,dc=minetti,dc=org''),
* SUBTREE_SCOPE pour rechercher au niveau de notre base DN et dans les noeuds enfants.

=== Par type d'entités et attributs ===
Pour retourner toutes les entités d'un même type '''ET''' qui ont un ou plusieurs attributs avec des valeurs données (par exemple: uid=jp):
 final String filterExpression = "(&(uid=jp)(objectClass=inetOrgPerson))";
 final SearchControls searchControls = new SearchControls ();
 searchControls.setSearchScope (SearchControls.ONELEVEL_SCOPE);
 final NamingEnumeration<SearchResult> resultEnumeration = context.search ("", filterExpression, searchControls);
'''Attention:''' La recherche est possible uniquement sur les attributs indexés (se reporter à la [[Linux:Administration d'OpenLDAP#Ajout de nouveaux index|configuration du LDAP]] pour paramétrer les indexes).

== Lecture des attributs d'une entité ==
Pour lire un attribut d'une entité:
 final Attribute attribute = attributes.get ("givenName");
 if (attribute != null) {
    Object value = attribute.get ();
    ...
 }

Chaque attribut de l'entité est encapsulé dans un objet implémentant l'interface [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/Attribute.html javax.naming.directory.Attribute].

Pour lire un attribut de type tableau de valeurs:
 final Attribute attribute = attributes.get ("uniqueMember");
 if ((attribute != null) && (attribute.size () > 0)) {
    final NamingEnumeration<?> enumeration = attribute.getAll ();
    while (enumeration.hasMore ()) {
       final String value = (String) enumeration.next ();
       ...
    }
 }

Ici, nous faisons une lecture de l'attribut '''uniqueMember''' (que l'on trouve dans les entités '''groupOfUniqueNames'''). Les valeurs de cet attribut sont de type DN (distinguished name). Il est vivement recommandé de placer les DN dans une instance [http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/LdapName.html javax.naming.ldap.LdapName]:
 final LdapName dn = new LdapName (value);

== Création d'une entité ==
Pour créer une nouvelle entité dans le [[Linux:Configuration d'OpenLDAP|LDAP]] (par exemple, un inetOrgPerson):
 final Attributes attributes = new BasicAttributes ();
 
 // Attribut objectClass
 final BasicAttribute objectClassAttribute = new BasicAttribute ("objectClass");
 objectClassAttribute.add ("top");
 objectClassAttribute.add ("inetOrgPerson");
 attributes.put (objectClassAttribute);
 
 // Attribut UID
 final String uid = ...
 attributes.put (new BasicAttribute ("uid", uid));
 
 // Attribut postalAddress (tableau de valeurs)
 final String address1 = ...
 final String address2 = ...
 final BasicAttribute addressAttribute = new BasicAttribute ("postalAddress", true);
 addressAttribute.add (address1);
 addressAttribute.add (address2);
 attributes.put (addressAttribute);
 
 ...
 
 // DN
 final LdapName name = new LdapName ("uid=" + Rdn.escapeValue (uid));
 
 // Création
 context.createSubcontext (name, attributes);

Chaque attribut de l'entité sera placé dans une instance de [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/BasicAttribute.html javax.naming.directory.BasicAttribute]. Cette instance sera à son tour placé dans une instance [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/BasicAttributes.html javax.naming.directory.BasicAttributes].

La création de la nouvelle entité se fera grâce à la méthode [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/InitialDirContext.html#createSubcontext(javax.naming.Name,%20javax.naming.directory.Attributes) createSubcontext(Name, Attributes)] de l'objet connexion ([http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/InitialLdapContext.html javax.naming.ldap.InitialLdapContext]).

== Modification d'une entité ==
Pour modifier un ou plusieurs attributs d'une entité:
 final Attributes attributesToReplace = new BasicAttributes ();
 final Attributes attributesToRemove = new BasicAttributes ();
 
 // Ajout/Modification d'un attribut
 final String sn = ...
 attributesToReplace.put (new BasicAttribute ("sn", sn));
 
 // Suppression d'un attribut (valeur NULL)
 attributesToRemove.put (new BasicAttribute ("givenName"));
 
 ...
 
 // DN
 final LdapName name = new LdapName ("uid=" + Rdn.escapeValue (uid));
 
 // Modification
 context.modifyAttributes (name, DirContext.REPLACE_ATTRIBUTE, attributesToReplace);
 context.modifyAttributes (name, DirContext.REMOVE_ATTRIBUTE, attributesToRemove);

'''Attention:''' Les attributs à supprimer doivent exister. S'ils n'existent pas une erreur se produit.

La modification d'une entité se fera grâce à la méthode [http://docs.oracle.com/javase/6/docs/api/javax/naming/directory/InitialDirContext.html#modifyAttributes(javax.naming.Name,%20int,%20javax.naming.directory.Attributes) modifyAttributes(Name, int, Attributes)] de l'objet connexion ([http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/InitialLdapContext.html javax.naming.ldap.InitialLdapContext]) et peut porter sur:
* une modification d'un ou plusieurs attributs de l'entité (REPLACE_ATTRIBUTE),
* ou une suppression d'un ou plusieurs attributs de l'entité (REMOVE_ATTRIBUTE).

== Suppression d'une entité ==
Pour supprimer une entité du [[Linux:Configuration d'OpenLDAP|LDAP]]:
 // DN
 final LdapName name = new LdapName ("uid=" + Rdn.escapeValue (uid));
 
 // Suppression
 context.destroySubcontext (name);

La suppression d'une entité se fera grâce à la méthode [http://docs.oracle.com/javase/6/docs/api/javax/naming/InitialContext.html#destroySubcontext(javax.naming.Name) destroySubcontext(Name)] de l'objet connexion ([http://docs.oracle.com/javase/6/docs/api/javax/naming/ldap/InitialLdapContext.html javax.naming.ldap.InitialLdapContext]).

== Chiffrement d'attributs ==
Certains attributs, comme les mots de passe (userPassword), doivent être chiffrés:
 final String password = ...
 final MessageDigest sha = MessageDigest.getInstance ("SHA");
 sha.update (password.getBytes ("UTF-8"));
 final String encodedPassword = "{SHA}" + (new BASE64Encoder ()).encode (sha.digest ());

== Quelques entités et attributs les plus utilisées ==
=== Hiérarchie des utilisateurs et personnes ===
{|style="color:black;background-color:#ffffcc;" cellpadding="2" cellspacing="0" border="1" width="100%"
!colspan="2"|Entités
!colspan="4"|Attributs
|-
!Nom
!Type
!Nom
!Requis
!Longueur
!Explication
|- style="background-color:white;"
|align="center"|top
|align="center"|abstract
|align="center"|objectClass
|align="center"|oui
|
|Classe d'une entité (tableau de valeurs).
|- style="background-color:white;"
|align="center" rowspan="5"|person
(hérite de top)
|align="center" rowspan="5"|structural
|align="center"|cn
|align="center"|oui
|align="right"|32 768
|Nom complet de la personne (prénom et nom de famille).
|- style="background-color:white;"
|align="center"|sn
|align="center"|oui
|
|Nom de famille de la personne.
|- style="background-color:white;"
|align="center"|description
|align="center"|non
|align="right"|1 024
|Description de la personne.
|- style="background-color:white;"
|align="center"|telephoneNumber
|align="center"|non
|align="right"|32
|Numéro de téléphone.
|- style="background-color:white;"
|align="center"|userPassword
|align="center"|non
|align="right"|128
|Mot de passe.
|- style="background-color:white;"
|align="center" rowspan="7"|organizationalPerson
(hérite de person)
|align="center" rowspan="7"|structural
|align="center"|facsimileTelephoneNumber
|align="center"|non
|
|Numéro de fax.
|- style="background-color:white;"
|align="center"|l
|align="center"|non
|
|Localité où réside la personne.
|- style="background-color:white;"
|align="center"|postOfficeBox
|align="center"|non
|align="right"|40
|Boite postale de la personne.
|- style="background-color:white;"
|align="center"|postalAddress
|align="center"|non
|
|Ligne complémentaire d'adresse où réside la personne (tableau de valeurs).
|- style="background-color:white;"
|align="center"|postalCode
|align="center"|non
|align="right"|40
|Code postal où réside la personne.
|- style="background-color:white;"
|align="center"|st
|align="center"|non
|
|Etat ou province où réside la personne.
|- style="background-color:white;"
|align="center"|street
|align="center"|non
|align="right"|128
|Numéro et nom de la rue où réside la personne.
|- style="background-color:white;"
|align="center" rowspan="4"|inetOrgPerson
(hérite de organizationalPerson)
|align="center" rowspan="4"|structural
|align="center"|givenName
|align="center"|non
|
|Prénom de la personne.
|- style="background-color:white;"
|align="center"|mail
|align="center"|non
|align="right"|256
|Adresse e-mail de la personne.
|- style="background-color:white;"
|align="center"|o
|align="center"|non
|
|Nom de la société où travail la personne.
|- style="background-color:white;"
|align="center"|uid
|align="center"|non
|align="right"|256
|Identifiant de la personne (utilisateur).
|}

=== Hiérarchie des groupes d'utilisateurs ===
{|style="color:black;background-color:#ffffcc;" cellpadding="2" cellspacing="0" border="1" width="100%"
!colspan="2"|Entités
!colspan="4"|Attributs
|-
!Nom
!Type
!Nom
!Requis
!Longueur
!Explication
|- style="background-color:white;"
|align="center"|top
|align="center"|abstract
|align="center"|objectClass
|align="center"|oui
|
|Classe d'une entité (tableau de valeurs).
|- style="background-color:white;"
|align="center" rowspan="3"|groupOfUniqueNames
(hérite de top)
|align="center" rowspan="3"|structural
|align="center"|cn
|align="center"|oui
|align="right"|32 768
|Nom du groupe d'utilisateurs.
|- style="background-color:white;"
|align="center"|uniqueMember
|align="center"|oui
|
|Distinguished name (DN) d'un utilisateur membre du groupe (tableau de valeurs).
|- style="background-color:white;"
|align="center"|description
|align="center"|non
|align="right"|1 024
|Description du groupe d'utilisateurs.
|}