对于最新的稳定版本，请使用 Spring LDAP 3.2.6！spring-doc.cn

对于最新的稳定版本，请使用 Spring LDAP 3.2.6！spring-doc.cn

配置 Spring LDAP 的推荐方法是使用自定义 XML 配置名称空间。要使其可用，你需要在 Bean 文件中包含 Spring LDAP 名称空间声明，如下所示：spring-doc.cn

<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 https://www.springframework.org/schema/beans/spring-beans.xsd
       http://www.springframework.org/schema/ldap https://www.springframework.org/schema/ldap/spring-ldap.xsd">

ContextSource配置

ContextSource是使用标签定义的。 最简单的声明要求您指定服务器 URL、用户名和密码，如下所示：<ldap:context-source>context-sourcespring-doc.cn

示例 1.最简单的上下文-源声明
<ldap:context-source
    username="cn=Administrator"
    password="secret"
    url="ldap://localhost:389" />

前面的示例使用默认值（请参阅本段后面的表）以及指定的 URL 和身份验证凭据创建。 context-source 上的可配置属性如下（必需属性标有 *）：LdapContextSourcespring-doc.cn

表 1.ContextSource 配置属性
属性 违约 描述

idspring-doc.cn

contextSourcespring-doc.cn

创建的 Bean 的 ID。spring-doc.cn

usernamespring-doc.cn

使用 LDAP 服务器进行身份验证时使用的用户名（主体）。 这通常是 admin 用户的可分辨名称（例如 ），但可能因服务器和身份验证方法而异。 如果未显式配置，则为 Required。cn=Administratorauthentication-source-refspring-doc.cn

passwordspring-doc.cn

使用 LDAP 服务器进行身份验证时使用的密码（凭证）。如果未显式配置，则为 Required。authentication-source-refspring-doc.cn

url *spring-doc.cn

要使用的 LDAP 服务器的 URL。URL 应采用以下格式：. 对于 SSL 访问，请使用协议和相应的端口 — 例如 . 如果需要故障转移功能，可以指定多个 URL，用逗号 （） 分隔。ldap://myserver.example.com:389ldapsldaps://myserver.example.com:636,spring-doc.cn

basespring-doc.cn

LdapUtils.emptyLdapName()spring-doc.cn

基本 DN.配置此属性后，提供给 LDAP 操作和从 LDAP 操作接收的所有可分辨名称都相对于指定的 LDAP 路径。 这可以大大简化处理 LDAP 树的过程。但是，在几种情况下，您需要访问基本路径。 有关更多信息，请参阅获取对基本 LDAP 路径的引用spring-doc.cn

anonymous-read-onlyspring-doc.cn

falsespring-doc.cn

定义是否使用匿名 （未经身份验证） 上下文执行只读操作。 请注意，不支持将此参数与补偿事务支持一起设置，并且会被拒绝。truespring-doc.cn

referralspring-doc.cn

nullspring-doc.cn

定义用于处理引荐的策略，如此处所述。有效值为：spring-doc.cn

native-poolingspring-doc.cn

falsespring-doc.cn

指定是否应使用本机 Java LDAP 连接池。考虑改用 Spring LDAP 连接池。有关更多信息，请参阅 池化支持。spring-doc.cn

authentication-source-refspring-doc.cn

一个实例。SimpleAuthenticationSourcespring-doc.cn

要使用的实例的 ID（请参阅自定义主体和凭证管理）。AuthenticationSourcespring-doc.cn

authentication-strategy-refspring-doc.cn

一个实例。SimpleDirContextAuthenticationStrategyspring-doc.cn

要使用的实例的 ID（请参见自定义 DirContext 身份验证处理）。DirContextAuthenticationStrategyspring-doc.cn

base-env-props-refspring-doc.cn

对自定义环境属性的引用，该属性应随发送到 on 构造的环境一起提供。MapDirContextspring-doc.cn

DirContext认证

当创建实例以用于在 LDAP 服务器上执行操作时，通常需要对这些上下文进行身份验证。 Spring LDAP 提供了各种选项来配置它。DirContextspring-doc.cn

本节引用了 的核心功能中的身份验证上下文，以构造供 和 使用的实例。LDAP 通常用于用户身份验证的唯一目的，也可以用于此目的。该过程在使用 Spring LDAP 进行用户身份验证中进行了讨论。ContextSourceDirContextLdapClientLdapTemplateContextSource

默认情况下，将为只读和读写操作创建经过身份验证的上下文。您应该指定要用于对元素进行身份验证的 LDAP 用户的 and。usernamepasswordcontext-sourcespring-doc.cn

如果 是 LDAP 用户的可分辨名称 （DN），则它必须是 LDAP 树根目录中用户的完整 DN，而不管是否在元素上指定了 LDAP 路径。usernamebasecontext-source

某些 LDAP 服务器设置允许匿名只读访问。如果要将匿名上下文用于只读操作，请将该属性设置为 。anonymous-read-onlytruespring-doc.cn

自定义身份验证处理DirContext

Spring LDAP 中使用的默认身份验证机制是身份验证。这意味着主体（由属性指定）和凭据（由 指定）在发送到实现构造函数的 中设置。SIMPLEusernamepasswordHashtableDirContextspring-doc.cn

在很多情况下，这种处理是不够的。例如，LDAP 服务器通常设置为仅接受安全 TLS 通道上的通信。可能需要使用特定的 LDAP 代理身份验证机制或其他问题。spring-doc.cn

您可以通过提供对元素的实现引用来指定替代身份验证机制。为此，请设置 属性。DirContextAuthenticationStrategycontext-sourceauthentication-strategy-refspring-doc.cn

TLS

Spring LDAP 为需要 TLS 安全通道通信的 LDAP 服务器提供了两种不同的配置选项： 和 。 两种实现都在目标连接上协商 TLS 通道，但它们在实际身份验证机制上有所不同。 在安全通道上应用 SIMPLE 认证（通过使用指定的 和 ）时，使用 EXTERNAL SASL 认证，应用使用系统属性配置的客户机证书进行认证。DefaultTlsDirContextAuthenticationStrategyExternalTlsDirContextAuthenticationStrategyDefaultTlsDirContextAuthenticationStrategyusernamepasswordExternalTlsDirContextAuthenticationStrategyspring-doc.cn

由于不同的 LDAP 服务器实现对 TLS 通道的显式关闭的响应不同（一些服务器要求正常关闭连接，而其他服务器不支持），因此 TLS 实现支持使用参数指定关闭行为。如果此属性设置为 （默认） ，则不会发生显式 TLS 关闭。如果是，则 Spring LDAP 会尝试在关闭目标上下文之前正常关闭 TLS 通道。DirContextAuthenticationStrategyshutdownTlsGracefullyfalsetruespring-doc.cn

使用 TLS 连接时，您需要确保本机 LDAP 池功能（使用属性指定）已关闭。如果设置为 ，则这一点尤其重要。但是，由于 TLS 通道协商过程非常昂贵，因此您可以通过使用 Spring LDAP 池支持来获得巨大的性能优势，如池支持中所述。native-poolingshutdownTlsGracefullyfalse

自定义委托人和凭证管理

虽然用于创建已验证的用户名（即用户 DN）和密码默认是静态定义的（元素配置中定义的用户名和密码在 的整个生命周期内使用 ），但在某些情况下，这不是所需的行为。一种常见情况是，在为该用户执行 LDAP 操作时，应使用当前用户的主体和凭证。您可以通过使用元素向元素提供对实现的引用来修改默认行为，而不是显式指定 and 。每次创建经过身份验证的 for principal 和 credentials 都会查询 。Contextcontext-sourceContextSourceAuthenticationSourcecontext-sourceauthentication-source-refusernamepasswordAuthenticationSourceContextSourceContextspring-doc.cn

如果使用 Spring Security，则可以通过使用 Spring Security 附带的实例进行配置，确保始终使用当前登录用户的主体和凭据。以下示例显示了如何执行此操作：ContextSourceSpringSecurityAuthenticationSourcespring-doc.cn

示例 2.使用 SpringSecurityAuthenticationSource
<beans>
...
    <ldap:context-source
        url="ldap://localhost:389"
        authentication-source-ref="springSecurityAuthenticationSource"/>

    <bean id="springSecurityAuthenticationSource"
        class="org.springframework.security.ldap.authentication.SpringSecurityAuthenticationSource" />
...
</beans>
我们没有指定 any 或 for。our 在使用 .仅当使用默认行为时，才需要这些属性。usernamepasswordcontext-sourceAuthenticationSource
使用 时，您需要使用 Spring Security 的 来根据 LDAP 对用户进行身份验证。SpringSecurityAuthenticationSourceLdapAuthenticationProvider

本机 Java LDAP 池

内部 Java LDAP 提供程序提供了一些非常基本的池功能。您可以使用标志 on 来打开或关闭此 LDAP 连接池。默认值为 （自版本 1.3 起） — 即，本机 Java LDAP 池已关闭。LDAP 连接池的配置是使用属性来管理的，因此您需要在 Spring Context 配置之外手动处理此问题。您可以在此处找到本机池配置的详细信息。pooledAbstractContextSourcefalseSystemspring-doc.cn

内置的 LDAP 连接池存在几个严重的缺陷，这就是为什么 Spring LDAP 提供了一种更复杂的 LDAP 连接池方法，如池支持中所述。如果您需要池功能，这是推荐的方法。
无论池配置如何，该方法始终显式不使用本机 Java LDAP 池，以便重置密码尽快生效。ContextSource#getContext(String principal, String credentials)

高级配置ContextSource

本节介绍配置 .ContextSourcespring-doc.cn

自定义环境属性DirContext

在某些情况下，除了在 上直接配置的属性之外，您可能还需要指定其他环境设置属性。您应该在 a 中设置此类属性，并在 attribute 中引用它们。context-sourceMapbase-env-props-refspring-doc.cn

表 1.ContextSource 配置属性
属性 违约 描述

idspring-doc.cn

contextSourcespring-doc.cn

创建的 Bean 的 ID。spring-doc.cn

usernamespring-doc.cn

使用 LDAP 服务器进行身份验证时使用的用户名（主体）。 这通常是 admin 用户的可分辨名称（例如 ），但可能因服务器和身份验证方法而异。 如果未显式配置，则为 Required。cn=Administratorauthentication-source-refspring-doc.cn

passwordspring-doc.cn

使用 LDAP 服务器进行身份验证时使用的密码（凭证）。如果未显式配置，则为 Required。authentication-source-refspring-doc.cn

url *spring-doc.cn

要使用的 LDAP 服务器的 URL。URL 应采用以下格式：. 对于 SSL 访问，请使用协议和相应的端口 — 例如 . 如果需要故障转移功能，可以指定多个 URL，用逗号 （） 分隔。ldap://myserver.example.com:389ldapsldaps://myserver.example.com:636,spring-doc.cn

basespring-doc.cn

LdapUtils.emptyLdapName()spring-doc.cn

基本 DN.配置此属性后，提供给 LDAP 操作和从 LDAP 操作接收的所有可分辨名称都相对于指定的 LDAP 路径。 这可以大大简化处理 LDAP 树的过程。但是，在几种情况下，您需要访问基本路径。 有关更多信息，请参阅获取对基本 LDAP 路径的引用spring-doc.cn

anonymous-read-onlyspring-doc.cn

falsespring-doc.cn

定义是否使用匿名 （未经身份验证） 上下文执行只读操作。 请注意，不支持将此参数与补偿事务支持一起设置，并且会被拒绝。truespring-doc.cn

referralspring-doc.cn

nullspring-doc.cn

定义用于处理引荐的策略，如此处所述。有效值为：spring-doc.cn

native-poolingspring-doc.cn

falsespring-doc.cn

指定是否应使用本机 Java LDAP 连接池。考虑改用 Spring LDAP 连接池。有关更多信息，请参阅 池化支持。spring-doc.cn

authentication-source-refspring-doc.cn

一个实例。SimpleAuthenticationSourcespring-doc.cn

要使用的实例的 ID（请参阅自定义主体和凭证管理）。AuthenticationSourcespring-doc.cn

authentication-strategy-refspring-doc.cn

一个实例。SimpleDirContextAuthenticationStrategyspring-doc.cn

要使用的实例的 ID（请参见自定义 DirContext 身份验证处理）。DirContextAuthenticationStrategyspring-doc.cn

base-env-props-refspring-doc.cn

对自定义环境属性的引用，该属性应随发送到 on 构造的环境一起提供。MapDirContextspring-doc.cn
本节引用了 的核心功能中的身份验证上下文，以构造供 和 使用的实例。LDAP 通常用于用户身份验证的唯一目的，也可以用于此目的。该过程在使用 Spring LDAP 进行用户身份验证中进行了讨论。ContextSourceDirContextLdapClientLdapTemplateContextSource
如果 是 LDAP 用户的可分辨名称 （DN），则它必须是 LDAP 树根目录中用户的完整 DN，而不管是否在元素上指定了 LDAP 路径。usernamebasecontext-source
使用 TLS 连接时，您需要确保本机 LDAP 池功能（使用属性指定）已关闭。如果设置为 ，则这一点尤其重要。但是，由于 TLS 通道协商过程非常昂贵，因此您可以通过使用 Spring LDAP 池支持来获得巨大的性能优势，如池支持中所述。native-poolingshutdownTlsGracefullyfalse
我们没有指定 any 或 for。our 在使用 .仅当使用默认行为时，才需要这些属性。usernamepasswordcontext-sourceAuthenticationSource
使用 时，您需要使用 Spring Security 的 来根据 LDAP 对用户进行身份验证。SpringSecurityAuthenticationSourceLdapAuthenticationProvider
内置的 LDAP 连接池存在几个严重的缺陷，这就是为什么 Spring LDAP 提供了一种更复杂的 LDAP 连接池方法，如池支持中所述。如果您需要池功能，这是推荐的方法。
无论池配置如何，该方法始终显式不使用本机 Java LDAP 池，以便重置密码尽快生效。ContextSource#getContext(String principal, String credentials)

LdapClient配置

LdapClient是调用 LDAP 后端的新接口。它通过以下方式进行了改进：LdapTemplatespring-doc.cn

  • 提供内置支持Streamspring-doc.cn

  • 提供以 bind © 、 search ® 、 modify （U）、解绑 （D） 和鉴权为中心的简化 API。spring-doc.cn

LdapClient尚不支持 ODM。 如果这是您需要的，请具有此容量。 如果需要，两者可以很好地共存于同一个应用程序中。LdapTemplateLdapClientLdapTemplate

An 使用工厂方法定义，如下所示：LdapClientLdapClient#createspring-doc.cn

例 3.最简单的 LdapClient 声明
<bean id="ldapClient" class="org.springframework.ldap.core.LdapClient" factory-method="create">
   <constructor-arg ref="contextSource" />
</bean>

此元素引用 default ，该 ID 应为 （元素的默认值）。ContextSourcecontextSourcecontext-sourcespring-doc.cn

可以配置实例，以了解如何处理某些选中的异常，以及应将任何默认值用于查询。LdapClientSearchControlsspring-doc.cn

LdapClient尚不支持 ODM。 如果这是您需要的，请具有此容量。 如果需要，两者可以很好地共存于同一个应用程序中。LdapTemplateLdapClientLdapTemplate

LdapTemplate配置

这是通过使用元素定义的。最简单的声明是元素本身：LdapTemplate<ldap:ldap-template>ldap-templatespring-doc.cn

示例 4.最简单的 ldap-template 声明
<ldap:ldap-template />

元素本身会创建一个具有 default ID 的实例，并引用 default ，该实例应具有 ID （元素的默认值）。LdapTemplateContextSourcecontextSourcecontext-sourcespring-doc.cn

下表描述了 上的可配置属性：ldap-templatespring-doc.cn

表 2.LdapTemplate 配置属性
属性 违约 描述

idspring-doc.cn

ldapTemplatespring-doc.cn

创建的 Bean 的 ID。spring-doc.cn

context-source-refspring-doc.cn

contextSourcespring-doc.cn

要使用的实例的 ID。ContextSourcespring-doc.cn

count-limitspring-doc.cn

0spring-doc.cn

搜索的默认计数限制。0 表示无限制。spring-doc.cn

time-limitspring-doc.cn

0spring-doc.cn

搜索的默认时间限制，以毫秒为单位。0 表示无限制。spring-doc.cn

search-scopespring-doc.cn

SUBTREEspring-doc.cn

搜索的默认搜索范围。有效值为：spring-doc.cn

ignore-name-not-foundspring-doc.cn

falsespring-doc.cn

指定是否应在搜索中忽略 a。设置此属性可使由无效搜索库引起的错误以静默方式吞噬。NameNotFoundExceptiontruespring-doc.cn

ignore-partial-resultspring-doc.cn

falsespring-doc.cn

指定是否应在搜索中忽略。某些 LDAP 服务器存在引用问题。通常应自动遵循这些内容。但是，如果这不起作用，它将以 .将此属性设置为可显示此问题的解决方法。PartialResultExceptionPartialResultExceptiontruespring-doc.cn

odm-refspring-doc.cn

要使用的实例的 ID。默认值是默认配置的 .ObjectDirectoryMapperDefaultObjectDirectoryMapperspring-doc.cn
表 2.LdapTemplate 配置属性
属性 违约 描述

idspring-doc.cn

ldapTemplatespring-doc.cn

创建的 Bean 的 ID。spring-doc.cn

context-source-refspring-doc.cn

contextSourcespring-doc.cn

要使用的实例的 ID。ContextSourcespring-doc.cn

count-limitspring-doc.cn

0spring-doc.cn

搜索的默认计数限制。0 表示无限制。spring-doc.cn

time-limitspring-doc.cn

0spring-doc.cn

搜索的默认时间限制，以毫秒为单位。0 表示无限制。spring-doc.cn

search-scopespring-doc.cn

SUBTREEspring-doc.cn

搜索的默认搜索范围。有效值为：spring-doc.cn

ignore-name-not-foundspring-doc.cn

falsespring-doc.cn

指定是否应在搜索中忽略 a。设置此属性可使由无效搜索库引起的错误以静默方式吞噬。NameNotFoundExceptiontruespring-doc.cn

ignore-partial-resultspring-doc.cn

falsespring-doc.cn

指定是否应在搜索中忽略。某些 LDAP 服务器存在引用问题。通常应自动遵循这些内容。但是，如果这不起作用，它将以 .将此属性设置为可显示此问题的解决方法。PartialResultExceptionPartialResultExceptiontruespring-doc.cn

odm-refspring-doc.cn

要使用的实例的 ID。默认值是默认配置的 .ObjectDirectoryMapperDefaultObjectDirectoryMapperspring-doc.cn

获取对基本 LDAP 路径的引用

如前所述，您可以向 指定 LDAP 树中所有操作都对应的根 ，从而提供基本 LDAP 路径。这意味着您在整个系统中仅使用相对可分辨的名称，这通常非常方便。但是，在某些情况下，您可能需要访问基本路径，以便能够相对于 LDAP 树的实际根构造完整的 DN。一个示例是使用 LDAP 组（例如，对象类）时。在这种情况下，每个组成员属性值都需要是被引用成员的完整 DN。ContextSourcegroupOfNamesspring-doc.cn

因此， Spring LDAP 具有一种机制，通过该机制，可以在启动时为任何 Spring 控制的 bean 提供基本路径。 要使 bean 收到基本路径的通知，需要具备两件事。首先，需要基本路径引用的 bean 需要实现接口。 其次，您需要在应用程序上下文中定义 a。 以下示例显示如何实现 ：BaseLdapNameAwareBaseLdapPathBeanPostProcessorBaseLdapNameAwarespring-doc.cn

例 5.实施BaseLdapNameAware
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();
   }
   ...
}

以下示例演示如何定义 ：BaseLdapPathBeanPostProcessorspring-doc.cn

例 6.在 ApplicationContext 中指定 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>

的默认行为是使用 .如果定义了多个，则需要通过设置属性来指定要使用的 1 个。BaseLdapPathBeanPostProcessorBaseLdapPathSourceAbstractContextSourceApplicationContextBaseLdapPathSourcebaseLdapPathSourceNamespring-doc.cn