2017.4.10 spring-ldap官方文檔學習

官網：http://www.springframework.org/ldap

官方文檔及例子（重要）：http://docs.spring.io/spring-ldap/docs/2.1.0.RELEASE/reference/

JAVA文檔（重要）：http://docs.spring.io/spring-ldap/docs/2.1.0.RELEASE/apidocs/

GitHub（大量例子）：https://github.com/spring-projects/spring-ldap

 

Spring LDAP Reference

2.基本使用

2.1 使用AttributesMapper進行search和lookup

（1）通過search返回一個屬性值

import static org.springframework.ldap.query.LdapQueryBuilder.query;

public class PersonRepoImpl implements PersonRepo{
    private LdapTemplate ldapTemplate;  5 
    public void setLdapTemplate(LdapTemplate ldapTemplate){
        this.ldapTemplate = ldapTemplate;
    }

    public List<String> getAllPersonNames(){
        return ldapTemplate.search({
            query().where("objectclass").is("person"),
            new AttributeMapper<String>(){ 14                 public String mapFromAttributes(Attribute attrs)throws NamingException{
                        return (String) attrs.get("cn").get();
                    }
                }
            }
        });
    }
}

 

（2）通過search返回一個Person對象

package com.example.repo;
import static org.springframework.ldap.query.LdapQueryBuilder.query;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;
   ...
   private class PersonAttributesMapper implements AttributesMapper<Person> {
      public Person mapFromAttributes(Attributes attrs) throws NamingException {
         Person person = new Person();
         person.setFullName((String)attrs.get("cn").get());
         person.setLastName((String)attrs.get("sn").get());
         person.setDescription((String)attrs.get("description").get());
         return person;
      }
   }

   public List<Person> getAllPersons() {
      return ldapTemplate.search(query()
          .where("objectclass").is("person"), new PersonAttributesMapper());
   }
}

 

（3）通過lookup返回一個Person對象

在ldap中，有兩個"查詢"概念，search和lookup。search是ldaptemplate對每一個entry進行查詢，lookup是通過DN直接找到某個條目。

"Entries in LDAP are uniquely identified by their distinguished name (DN). If you have the DN of an entry, you can retrieve（找回） the entry directly without searching for it. This is called a lookup in Java LDAP."

在下面的lookup代碼中，ldap會跳過為AttributesMapper查找屬性。

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;
   ...
   public Person findPerson(String dn) {
      return ldapTemplate.lookup(dn, new PersonAttributesMapper());
   }
}

 

2.2 創建LDAP Queries

ldap的search 包含許多參數，比如：

Base LDAP path 基本路徑（search應該從LDAP樹的哪里開始）
Search scope 查詢范圍（search應該進行到LDAP樹的哪一層）
returned attributes要返回的屬性
Search filter 查詢過濾器

 

spring-ldap為我們提供了 LdapQueryBuilder來創建LDAP Queries。

假設現在需要執行一個查詢：

base DN為"dc=261consulting，dc=com"，返回的屬性為"cn"和"sn"，filter為" (&(objectclass=person)(sn=?))"，此處? 用lastName的值。

為了簡化復雜的search參數，LdapQueryBuilder及其相關類，也提供了避開某些字符的搜索。AttributesMapper也只是其中一個可用的callback interfaces。更多的使用方法可以查看ldapTemplate的方法。

package com.example.repo;
import static org.springframework.ldap.query.LdapQueryBuilder.query;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;
   ...
   public List<String> getPersonNamesByLastName(String lastName) {

      LdapQuery query = query()
         　　　　　　　　　　　　.base("dc=261consulting,dc=com")
         　　　　　　　　　　　　.attributes("cn", "sn")   //返回的屬性
         　　　　　　　　　　　　.where("objectclass").is("person")
         　　　　　　　　　　　　.and("sn").is(lastName);

      return ldapTemplate.search(query, new AttributesMapper<String>() {
                                            public String mapFromAttributes(Attributes attrs)throws NamingException {
                                                  return attrs.get("cn").get(); //查詢每一個entry的"cn"值 21                                             }
                                 });
    }
}

 

2.3 動態創建 Distinguished Names（DN）

為了簡化對DN的使用，spring-ldap提供了LdapNameBuilder，和工具類LdapUtils。

假設一個Person有如下的屬性：

Attribute Name                 Attribute Value
  country                          Sweden
  company                        Some Company
  fullname                       Some Person

 

（1）使用 LdapNameBuilder 動態創建 LdapName

package com.example.repo;
import org.springframework.ldap.support.LdapNameBuilder;
import javax.naming.Name;

public class PersonRepoImpl implements PersonRepo {
  public static final String BASE_DN = "dc=example,dc=com";

  protected Name buildDn(Person p) {
    return LdapNameBuilder.newInstance(BASE_DN)
                          .add("c", p.getCountry())
                          .add("ou", p.getCompany())
                          .add("cn", p.getFullname())
                          .build();
  }
  ...

 

（2）用 LdapUtils 獲取屬性值

package com.example.repo;
import org.springframework.ldap.support.LdapNameBuilder;
import javax.naming.Name;
public class PersonRepoImpl implements PersonRepo {
...
protected Person buildPerson(Name dn, Attributes attrs) {
  Person person = new Person();
  person.setCountry(LdapUtils.getStringValue(dn, "c"));
  person.setCompany(LdapUtils.getStringValue(dn, "ou"));
  person.setFullname(LdapUtils.getStringValue(dn, "cn"));
  // Populate rest of person object using attributes.

  return person;
}

 

2.4 綁定和解綁

在Ldap中，新增與刪除叫做綁定和解綁。

2.4.1 新增數據

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;
   ...
   public void create(Person p) {
      Name dn = buildDn(p);  8       ldapTemplate.bind(dn, null, buildAttributes(p));
   }

   private Attributes buildAttributes(Person p) {
      Attributes attrs = new BasicAttributes();
      BasicAttribute ocattr = new BasicAttribute("objectclass");
      ocattr.add("top");
      ocattr.add("person");
      attrs.put(ocattr);
      attrs.put("cn", "Some Person");
      attrs.put("sn", "Person");
      return attrs;
   }
}

 

2.4.2 刪除數據

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;
   ...
   public void delete(Person p) {
      Name dn = buildDn(p);
      ldapTemplate.unbind(dn);
   }
}

 

2.4.3 更新數據

（1）使用 rebind 更新數據

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;
   ...
   public void update(Person p) {
      Name dn = buildDn(p);
      ldapTemplate.rebind(dn, null, buildAttributes(p));
   }
}

 

（2）使用 modifyAttributes 更新數據

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;
   ...
   public void updateDescription(Person p) {
      Name dn = buildDn(p);
      Attribute attr = new BasicAttribute("description", p.getDescription())
      ModificationItem item = new ModificationItem(DirContext.REPLACE_ATTRIBUTE, attr);
      ldapTemplate.modifyAttributes(dn, new ModificationItem[] {item});
   }
}

 

3.簡化 Attribute 的獲取和 DirContextAdapter 的操作

3.1 介紹

Java LDAP API 可以注冊一個DirContextAdapter來自動創建對象。spring-ldap使用了這個特點，在search和lookup中返回DirContextAdapter實例。

 

3.2 通過ContextMapper來search 和lookup

任何時候，想要在LDAP數據樹中查找entry，spring-ldap都會使用這個entry的DN和Attributes來構建一個DirContextAdapter，這使得我們不再需要使用 AttributesMapper，而是使用ContextMapper來對獲取的屬性值進行轉換。

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   ...
   private static class PersonContextMapper implements ContextMapper {
      public Object mapFromContext(Object ctx) {
         DirContextAdapter context = (DirContextAdapter)ctx;
         Person p = new Person();
         p.setFullName(context.getStringAttribute("cn"));
         p.setLastName(context.getStringAttribute("sn"));
         p.setDescription(context.getStringAttribute("description"));
         return p;
      }
   }

   public Person findByPrimaryKey(String name, String company, String country) {
      Name dn = buildDn(name, company, country);
      return ldapTemplate.lookup(dn, new PersonContextMapper());
   }
}

 

這里特別方便的一點是：當屬性具有多值時，可以通過getStringAttributes（）來獲取。

private static class PersonContextMapper implements ContextMapper {
   public Object mapFromContext(Object ctx) {
      DirContextAdapter context = (DirContextAdapter)ctx;
      Person p = new Person();
      p.setFullName(context.getStringAttribute("cn"));
      p.setLastName(context.getStringAttribute("sn"));
      p.setDescription(context.getStringAttribute("description"));
      // The roleNames property of Person is an String array
      p.setRoleNames(context.getStringAttributes("roleNames"));
      return p;
   }
}

 

3.2.1 AbstactContextMapper

spring-ldap提供了一個ContextMapper的抽象的基礎實現類：AbstractContextMapper。自定義的的PersonContextMapper可以這樣寫：

private static class PersonContextMapper extends AbstractContextMapper {
  public Object doMapFromContext(DirContextOperations ctx) { //ctx沒有用到？？ 3      Person p = new Person();
     p.setFullName(context.getStringAttribute("cn"));
     p.setLastName(context.getStringAttribute("sn"));
     p.setDescription(context.getStringAttribute("description"));
     return p;
  }
}

 

3.3 使用DirContextAdapter新增和更新數據

注意新增的時候用的是：DirContextAdapter。更新的時候用的是：DirContextOperations。二者的關系：DirContextAdapter實現了DirContextOperations接口。

3.3.1 新增數據

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   ...
   public void create(Person p) {
      Name dn = buildDn(p);
      DirContextAdapter context = new DirContextAdapter(dn);
      //和獲取一樣，set也可以有多值
      context.setAttributeValues("objectclass", new String[] {"top", "person"});
      context.setAttributeValue("cn", p.getFullname());
      context.setAttributeValue("sn", p.getLastname());
      context.setAttributeValue("description", p.getDescription());

      ldapTemplate.bind(context);
   }
}

 

3.3.2 更新數據

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   ...
   public void update(Person p) {
      Name dn = buildDn(p);
      DirContextOperations context = ldapTemplate.lookupContext(dn);

      context.setAttributeValue("cn", p.getFullname());
      context.setAttributeValue("sn", p.getLastname());
      context.setAttributeValue("description", p.getDescription());

      ldapTemplate.modifyAttributes(context);
   }
}

 

3.3.3 合並新增和更新數據的代碼

從前面兩段代碼可知，新增和更新有重復的代碼，因此合並重復代碼，整理如下：

package com.example.repo;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;

   ...
   public void create(Person p) {
      Name dn = buildDn(p);
      DirContextAdapter context = new DirContextAdapter(dn);
      context.setAttributeValues("objectclass", new String[] {"top", "person"});
 mapToContext(p, context);
      ldapTemplate.bind(context);
   }

   public void update(Person p) {
      Name dn = buildDn(p);
      DirContextOperations context = ldapTemplate.lookupContext(dn);
 mapToContext(person, context);
      ldapTemplate.modifyAttributes(context);
   }

   protected void mapToContext (Person p, DirContextOperations context) {
      context.setAttributeValue("cn", p.getFullName());
      context.setAttributeValue("sn", p.getLastName());
      context.setAttributeValue("description", p.getDescription());
   }
}

 

3.4 DirContextAdapter和作為屬性值的DN

When managing security groups in LDAP it is very common to have attribute values that represent distinguished names. Since distinguished name equality differs from String equality (例如，空格和大小寫在DN的判等中是無視的), calculating attribute modifications using string equality will not work as expected.

 

假設一個member屬性值為：cn=John Doe，ou=People。如果代碼寫作如下，會被認為是兩個值，實際上它代表了同一個DN。

ctx.addAttributeValue("member", "CN=John Doe, OU=People")

 

要寫作如下：

ctx.addAttributeValue("member", LdapUtils.newLdapName("CN=John Doe, OU=People"))

 

使用DirContextAdapter來修改group membership：

public class GroupRepo implements BaseLdapNameAware {
    private LdapTemplate ldapTemplate;
    private LdapName baseLdapPath;

    public void setLdapTemplate(LdapTemplate ldapTemplate) {
        this.ldapTemplate = ldapTemplate;
    }

    public void setBaseLdapPath(LdapName baseLdapPath) {
        this.setBaseLdapPath(baseLdapPath);
    }

    public void addMemberToGroup(String groupName, Person p) {
        Name groupDn = buildGroupDn(groupName);
        Name userDn = buildPersonDn(person.getFullname(),person.getCompany(), person.getCountry());

        DirContextOperation ctx = ldapTemplate.lookupContext(groupDn);
        ctx.addAttributeValue("member", userDn);

        ldapTemplate.update(ctx);
    }

    public void removeMemberFromGroup(String groupName, Person p) {
        Name groupDn = buildGroupDn(String groupName);
        Name userDn = buildPersonDn(person.getFullname(),person.getCompany(),person.getCountry());

        DirContextOperation ctx = ldapTemplate.lookupContext(groupDn);
        ctx.removeAttributeValue("member", userDn);

        ldapTemplate.update(ctx);
    }

    private Name buildGroupDn(String groupName) {
        return LdapNameBuilder.newInstance("ou=Groups").add("cn", groupName).build();
    }

    private Name buildPersonDn(String fullname, String company, String country) {
        return LdapNameBuilder.newInstance(baseLdapPath).add("c", country).add("ou", company).add("cn", fullname).build();
   }
}

 

3.5 使用spring-ldap和DirContextAdapter的完整代碼

package com.example.repo;
import java.util.List;

import javax.naming.Name;
import javax.naming.NamingException;
import javax.naming.directory.Attributes;
import javax.naming.ldap.LdapName;

import org.springframework.ldap.core.AttributesMapper;
import org.springframework.ldap.core.ContextMapper;
import org.springframework.ldap.core.LdapTemplate;
import org.springframework.ldap.core.DirContextAdapter;
import org.springframework.ldap.filter.AndFilter;
import org.springframework.ldap.filter.EqualsFilter;
import org.springframework.ldap.filter.WhitespaceWildcardsFilter;

import static org.springframework.ldap.query.LdapQueryBuilder.query;

public class PersonRepoImpl implements PersonRepo {
   private LdapTemplate ldapTemplate;

   public void setLdapTemplate(LdapTemplate ldapTemplate) {
      this.ldapTemplate = ldapTemplate;
   }

   public void create(Person person) {
      DirContextAdapter context = new DirContextAdapter(buildDn(person));
      mapToContext(person, context);
      ldapTemplate.bind(context);
   }

   public void update(Person person) {
      Name dn = buildDn(person);
      DirContextOperations context = ldapTemplate.lookupContext(dn);
      mapToContext(person, context);
      ldapTemplate.modifyAttributes(context);
   }

   public void delete(Person person) {
      ldapTemplate.unbind(buildDn(person));
   }

   public Person findByPrimaryKey(String name, String company, String country) {
      Name dn = buildDn(name, company, country);
      return ldapTemplate.lookup(dn, getContextMapper());
   }

   public List findByName(String name) {
      LdapQuery query = query()
         .where("objectclass").is("person")
         .and("cn").whitespaceWildcardsLike("name");

      return ldapTemplate.search(query, getContextMapper());
   }

   public List findAll() {
      EqualsFilter filter = new EqualsFilter("objectclass", "person");
      return ldapTemplate.search(LdapUtils.emptyPath(), filter.encode(), getContextMapper());
   }

   protected ContextMapper getContextMapper() {
      return new PersonContextMapper();
   }

   protected Name buildDn(Person person) {
      return buildDn(person.getFullname(), person.getCompany(), person.getCountry());
   }

   protected Name buildDn(String fullname, String company, String country) {
      return LdapNameBuilder.newInstance()
        .add("c", country)
        .add("ou", company)
        .add("cn", fullname)
        .build();
   }

   protected void mapToContext(Person person, DirContextOperations context) {
      context.setAttributeValues("objectclass", new String[] {"top", "person"});
      context.setAttributeValue("cn", person.getFullName());
      context.setAttributeValue("sn", person.getLastName());
      context.setAttributeValue("description", person.getDescription());
   }

   private static class PersonContextMapper extends AbstractContextMapper<Person> {
      public Person doMapFromContext(DirContextOperations context) {
         Person person = new Person();
         person.setFullName(context.getStringAttribute("cn"));
         person.setLastName(context.getStringAttribute("sn"));
         person.setDescription(context.getStringAttribute("description"));
         return person;
      }
   }
}

 

4. ODM（Object-Directory Mapping）

4.1 介紹

對象-關系映射框架比如Hibernate和JPA，都可以使用注解來將數據庫的表關系映射成java的對象。spring-ldap也提供類似的功能。

LdapPerations里有這些方法：

    <T> T findByDn(Name dn, Class<T> clazz)
    <T> T findOne(LdapQuery query, Class<T> clazz)
    <T> List<T> find(LdapQuery query, Class<T> clazz)
    <T> List<T> findAll(Class<T> clazz)
    <T> List<T> findAll(Name base, SearchControls searchControls, Class<T> clazz)
    <T> List<T> findAll(Name base, Filter filter, SearchControls searchControls, Class<T> clazz)

    void create(Object entry)
    void update(Object entry)
    void delete(Object entry)

 

4.2 注解

每個注解的含義暫時先不詳細解釋。//todo

@Entry （required）
@Id （required）
@Attribute
@DnAttribute
@Transient

 

4.3 執行

@Entry(objectClasses = { "person", "top" }, base="ou=someOu")
public class Person {
 @Id  4    private Name dn;

   @Attribute(name="cn")
   @DnAttribute(value="cn", index=1)
   private String fullName;

   // No @Attribute annotation means this will be bound to the LDAP attribute with the same value
   private String description;

   @DnAttribute(value="ou", index=0)
 @Transient 16    private String company;

   @Transient
   private String someUnmappedField;
   // ...more attributes below
}

 

24 public class OdmPersonRepo {
25    @Autowired
26    private LdapTemplate ldapTemplate;
27 
28    public Person create(Person person) {
29       ldapTemplate.create(person);
30       return person;
31    }
32 
33    public Person findByUid(String uid) {
34       return ldapTemplate.findOne(query().where("uid").is(uid), Person.class);
35    }
36 
37    public void update(Person person) {
38       ldapTemplate.update(person);
39    }
40 
41    public void delete(Person person) {
42       ldapTemplate.delete(person);
43    }
44 
45    public List<Person> findAll() {
46       return ldapTemplate.findAll(Person.class);
47    }
48 
49    public List<Person> findByLastName(String lastName) {
50       return ldapTemplate.find(query().where("sn").is(lastName), Person.class);
51    }
52 }

 

4.4 ODM和作為屬性值的DN

 ldap中的安全組通常包含多值屬性，每一個屬性值都是一個user的DN。這些屬性值的處理在前面的 3.4 DirContextAdapter和作為屬性值的DN 中提到過。ODM同樣有簡單的處理辦法。

@Entry(objectClasses = {"top", "groupOfUniqueNames"}, base = "cn=groups")
public class Group {

    @Id
    private Name dn;

    @Attribute(name="cn")
    @DnAttribute("cn")
    private String name;

    @Attribute(name="uniqueMember") 12     private Set<Name> members; 13 
    public Name getDn() {return dn;}
    public void setDn(Name dn) {this.dn = dn;}

    public Set<Name> getMembers() {return members;}
    public void setMembers(Set<Name> members) {this.members = members;}

    public String getName() { return name;}
    public void setName(String name) {this.name = name;}

    public void addMember(Name member) {members.add(member);}
    public void removeMember(Name member) {members.remove(member);}
}

 

 5.高級LDAP Queries

//todo 暫略。

 

6.配置

6.1 介紹

采用xml文件方式配置時，需要加入如下xml的命名空間。

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:ldap="http://www.springframework.org/schema/ldap"
       xsi:schemaLocation="http://www.springframework.org/schema/beans 
                           http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/ldap 
http://www.springframework.org/schema/ldap/spring-ldap.xsd">

 

 6.2 ContextSource 配置

最簡單的配置至少需要：username，password，url。完整的屬性參看官方文檔的說明。

<ldap:context-source
    username="cn=Administrator"
    password="secret"
    url="ldap://localhost:389" />

 

6.2.1 DirContextAuthentication

創建並使用DirContext實例時，通常需要認證這些contexts，有不同的配置方式可供選擇。

在這一節里（12. User Authentication using Spring LDAP）討論了使用spring ldap進行用戶驗證。

authenticated contexts可以默認創建為read-only和read-write兩種。在context-source的配置中指定username和password。如果username是一個LDAP 用戶的dn，那么不管在context-source中是否配置了base LDAP path，這個user的DN也必須是username。（沒看懂）

有些LDAP服務器支持匿名read-only訪問。如果需要支持這個功能，將屬性anonymous-read-only設置為true即可。

 

（1）自定義DirContext的認證過程

spring ldap中的默認認證策略是簡單的。它將principal（這里是username）和credentials（這里是password）放在哈希表里傳遞給DirContext的構造函數。這通常是不夠的。因此可以在context-source里配置 authentication-strategy-ref，來指定自定義策略。 

 

（2）使用SpringSecurityAuthenticationSource我們前面的配置，直接將username和password寫死了。但是一個更常見的場景是，當為某個用戶執行LDAP操作時，應該使用的是當前用戶的principals和credentials，而不是顯式指定。這可以通過配置SpringSecurityAuthenticationSource實現動態配置。

<beans>
...
    <ldap:context-source
        url="ldap://localhost:389"
        authentication-source-ref="springSecurityAuthenticationSource/>

    <bean id="springSecurityAuthenticationSource"      
      class="org.springframework.security.ldap.authentication.SpringSecurityAuthenticationSource" />
...
</beans>

 

6.2.2 本地java LDAP Pooling//todo 

 

6.2.3 高級ContextSource配置//todo 

 

6.3 LdapTemplate Configuration

<ldap:ldap-template />

可供配置的屬性有：

屬性	默認值	說明
id	ldapTemplate
context-source-ref	contextSource	使用的contextSource
count-limit	0	search的默認個數限制，0指的是沒有限制。
time-limit	0	search的默認時間限制，0指的是沒有限制。
search-scope	SUBTREE	可選值有：OBJECT,ONELEVEL,SUBTREE
ignore-name-not-found	false	指明search時異常NameNotFoundException是否被忽視。
ignore-partial-result	false	指明search時異常PartialResultException是否被忽視。
odm-ref		使用的ObjectDirectoryMapper的bean id。默認是DefaultObjectDirectoryMapper

 

6.4 獲取base LDAP path的值

通常情況下，在contextSource里定義了base LDAP path，然后操作時都是用的相對路徑。但也有某些情況下，需要用到base LDAP path的完整值。比如，操作LDAP groups時，在這里group member的屬性值必須是member的完整DN。

step1：實現接口BaseLdapNameAware

package com.example.service;
public class PersonService implements PersonService, BaseLdapNameAware {
   ...
   private LdapName basePath;

   public void setBaseLdapPath(LdapName basePath) {
      this.basePath = basePath;
   }
   ...
   private LdapName getFullPersonDn(Person person) {
      return LdapNameBuilder.newInstance(basePath)
          .add(person.getDn())
          .build();
   }
   ...
}

 

 step2：配置BaseLdapPathBeanPostProcessor

<beans>
   ...
   <ldap:context-source
          username="cn=Administrator"
          password="secret"
          url="ldap://localhost:389"
          base="dc=261consulting,dc=com" />
   ...
   <bean class="org.springframework.ldap.core.support.BaseLdapPathBeanPostProcessor" />
</beans>