配置

配置 Spring LDAP 的推薦方法是使用自定義 XML 配置名稱空間。要使其可用，您需要在 bean 檔案中包含 Spring LDAP 名稱空間宣告，如下所示

<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 透過使用 <ldap:context-source> 標籤定義。最簡單的 context-source 宣告要求您指定伺服器 URL、使用者名稱和密碼，如下所示

示例 1. 最簡單的 context-source 宣告

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

上述示例建立一個具有預設值（請參閱本段後的表格）以及指定 URL 和身份驗證憑據的 LdapContextSource。context-source 上可配置的屬性如下（必需屬性標有 *）

表 1. ContextSource 配置屬性
屬性	預設值	描述
`id`	`contextSource`	建立的 bean 的 ID。
`username`		用於與 LDAP 伺服器進行身份驗證的使用者名稱（主體）。這通常是管理員使用者的區分名（例如，`cn=Administrator`），但可能因伺服器和身份驗證方法而異。如果未明確配置 `authentication-source-ref`，則為必需。
`password`		用於與 LDAP 伺服器進行身份驗證的密碼（憑據）。如果未明確配置 `authentication-source-ref`，則為必需。
`url` *		要使用的 LDAP 伺服器的 URL。URL 應採用以下格式：`ldap://myserver.example.com:389`。對於 SSL 訪問，請使用 `ldaps` 協議和適當的埠——例如，`ldaps://myserver.example.com:636`。如果您需要故障轉移功能，可以指定多個 URL，並用逗號 (`,`) 分隔。
`base`	`LdapUtils.emptyLdapName()`	基本 DN。配置此屬性後，所有提供給 LDAP 操作和從 LDAP 操作接收的區分名都將相對於指定的 LDAP 路徑。這可以顯著簡化針對 LDAP 樹的工作。但是，在某些情況下，您需要訪問基本路徑。有關更多資訊，請參閱獲取對基本 LDAP 路徑的引用
`anonymous-read-only`	`假`	定義是否使用匿名（未經身份驗證）上下文執行只讀操作。請注意，將此引數設定為 `true` 並同時使用補償事務支援是不受支援的，並將被拒絕。
`referral`	`null`	定義處理引用的策略，如此處所述。有效值包括 `ignore` `follow` `throw`
`native-pooling`	`假`	指定是否應使用原生 Java LDAP 連線池。考慮改用 Spring LDAP 連線池。有關更多資訊，請參閱連線池支援。
`authentication-source-ref`	一個 `SimpleAuthenticationSource` 例項。	要使用的 `AuthenticationSource` 例項的 ID（請參閱自定義主體和憑據管理）。
`authentication-strategy-ref`	一個 `SimpleDirContextAuthenticationStrategy` 例項。	要使用的 `DirContextAuthenticationStrategy` 例項的 ID（請參閱自定義 `DirContext` 身份驗證處理）。
`base-env-props-ref`		對自定義環境屬性 `Map` 的引用，這些屬性應在構建時隨傳送到 `DirContext` 的環境一起提供。

`DirContext` 身份驗證

當建立 DirContext 例項以執行 LDAP 伺服器上的操作時，這些上下文通常需要進行身份驗證。Spring LDAP 提供了多種配置選項來配置此功能。

本節指的是在 ContextSource 的核心功能中進行上下文身份驗證，以構建 DirContext 例項供 LdapClient 和 LdapTemplate 使用。LDAP 通常僅用於使用者身份驗證，ContextSource 也可以用於此目的。該過程在使用 Spring LDAP 進行使用者身份驗證中討論。

預設情況下，為只讀和讀寫操作都建立經過身份驗證的上下文。您應該在 context-source 元素上指定用於身份驗證的 LDAP 使用者的 username 和 password。

如果 username 是 LDAP 使用者的區分名 (DN)，則需要是 LDAP 樹根目錄中使用者的完整 DN，無論是否在 context-source 元素上指定了 base LDAP 路徑。

某些 LDAP 伺服器設定允許匿名只讀訪問。如果要將匿名上下文用於只讀操作，請將 anonymous-read-only 屬性設定為 true。

自定義 `DirContext` 身份驗證處理

Spring LDAP 中使用的預設身份驗證機制是 SIMPLE 身份驗證。這意味著主體（由 username 屬性指定）和憑據（由 password 指定）在傳送到 DirContext 實現建構函式的 Hashtable 中設定。

在許多情況下，這種處理不足。例如，LDAP 伺服器通常設定為僅接受安全 TLS 通道上的通訊。可能需要使用特定的 LDAP 代理身份驗證機制或其他注意事項。

您可以透過向 context-source 元素提供 DirContextAuthenticationStrategy 實現引用來指定替代身份驗證機制。為此，請設定 authentication-strategy-ref 屬性。

TLS

Spring LDAP 為需要 TLS 安全通道通訊的 LDAP 伺服器提供了兩種不同的配置選項：DefaultTlsDirContextAuthenticationStrategy 和 ExternalTlsDirContextAuthenticationStrategy。這兩種實現都在目標連線上協商 TLS 通道，但它們在實際身份驗證機制上有所不同。DefaultTlsDirContextAuthenticationStrategy 在安全通道上應用 SIMPLE 身份驗證（使用指定的 username 和 password），而 ExternalTlsDirContextAuthenticationStrategy 使用 EXTERNAL SASL 身份驗證，透過使用系統屬性配置的客戶端證書進行身份驗證。

由於不同的 LDAP 伺服器實現對 TLS 通道的顯式關閉響應不同（有些伺服器要求平穩關閉連線，而另一些則不支援），因此 TLS DirContextAuthenticationStrategy 實現支援使用 shutdownTlsGracefully 引數指定關閉行為。如果此屬性設定為 false（預設值），則不會發生顯式 TLS 關閉。如果設定為 true，Spring LDAP 會嘗試在關閉目標上下文之前平穩關閉 TLS 通道。

使用 TLS 連線時，您需要確保原生 LDAP 連線池功能（透過使用 native-pooling 屬性指定）已關閉。如果 shutdownTlsGracefully 設定為 false，這一點尤為重要。但是，由於 TLS 通道協商過程非常耗時，因此透過使用連線池支援中描述的 Spring LDAP 連線池支援，您可以獲得巨大的效能優勢。

自定義主體和憑據管理

雖然用於建立經過身份驗證的 Context 的使用者名稱（即使用者 DN）和密碼預設是靜態定義的（在 context-source 元素配置中定義的那些在 ContextSource 的整個生命週期中都使用），但在某些情況下這不是所需行為。一個常見的場景是，在為該使用者執行 LDAP 操作時，應使用當前使用者的主體和憑據。您可以透過向 context-source 元素提供 AuthenticationSource 實現的引用來修改預設行為，方法是使用 authentication-source-ref 元素，而不是顯式指定 username 和 password。每次建立經過身份驗證的 Context 時，ContextSource 都會查詢 AuthenticationSource 以獲取主體和憑據。

如果您使用 Spring Security，您可以透過使用 Spring Security 隨附的 SpringSecurityAuthenticationSource 例項配置您的 ContextSource 來確保始終使用當前登入使用者的主體和憑據。以下示例顯示瞭如何執行此操作

示例 2. 使用 SpringSecurityAuthenticationSource

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

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

在使用 AuthenticationSource 時，我們沒有為 context-source 指定任何 username 或 password。這些屬性僅在使用預設行為時才需要。

使用 SpringSecurityAuthenticationSource 時，您需要使用 Spring Security 的 LdapAuthenticationProvider 來針對 LDAP 對使用者進行身份驗證。

原生 Java LDAP 連線池

內部 Java LDAP 提供程式提供了一些非常基本的連線池功能。您可以透過 AbstractContextSource 上的 pooled 標誌開啟或關閉此 LDAP 連線池。預設值是 false（自 1.3 版本以來）——即，原生 Java LDAP 連線池已關閉。LDAP 連線池的配置透過 System 屬性進行管理，因此您需要手動處理此問題，而不是透過 Spring Context 配置。您可以在此處找到原生連線池配置的詳細資訊。

內建 LDAP 連線池存在一些嚴重缺陷，這就是 Spring LDAP 提供了一種更復雜的 LDAP 連線池方法的原因，如連線池支援中所述。如果您需要連線池功能，這是推薦的方法。

無論連線池配置如何，ContextSource#getContext(String principal, String credentials) 方法始終明確不使用原生 Java LDAP 連線池，以便儘快生效重置密碼。

高階 `ContextSource` 配置

本節介紹配置 ContextSource 的更高階方法。

自定義 `DirContext` 環境屬性

在某些情況下，除了直接在 context-source 上配置的屬性之外，您可能還需要指定額外的環境設定屬性。您應該將此類屬性設定在 Map 中，並在 base-env-props-ref 屬性中引用它們。

`LdapClient` 配置

LdapClient 是呼叫 LDAP 後端的新介面。它在以下方面改進了 LdapTemplate

提供內建的 Stream 支援
提供圍繞繫結 ©、搜尋 ®、修改 (U)、解綁 (D) 和身份驗證的簡化 API。

LdapClient 尚不支援 ODM。如果您需要此功能，LdapTemplate 具有此能力。如果需要，LdapClient 和 LdapTemplate 可以在同一應用程式中很好地共存。

LdapClient 透過使用 LdapClient#create 工廠方法定義，如下所示

示例 3. 最簡單的 LdapClient 宣告

<bean id="ldapClient" class="org.springframework.ldap.core.LdapClient" factory-method="create">
   <constructor-arg ref="contextSource" />
</bean>

此元素引用預設的 ContextSource，該 ContextSource 預期具有 contextSource 的 ID（context-source 元素的預設值）。

您的 LdapClient 例項可以配置為如何處理某些已檢查的異常以及查詢應使用哪些預設 SearchControls。

`LdapTemplate` 配置

LdapTemplate 透過使用 <ldap:ldap-template> 元素定義。最簡單的 ldap-template 宣告是元素本身

示例 4. 最簡單的 ldap-template 宣告

<ldap:ldap-template />

元素本身會建立一個具有預設 ID 的 LdapTemplate 例項，引用預設的 ContextSource，該 ContextSource 預期具有 contextSource 的 ID（context-source 元素的預設值）。

下表描述了 ldap-template 上可配置的屬性

表 2. LdapTemplate 配置屬性
屬性	預設值	描述
`id`	`ldapTemplate`	建立的 bean 的 ID。
`context-source-ref`	`contextSource`	要使用的 `ContextSource` 例項的 ID。
`count-limit`	`0`	搜尋的預設計數限制。0 表示沒有限制。
`time-limit`	`0`	搜尋的預設時間限制，以毫秒為單位。0 表示沒有限制。
`search-scope`	`SUBTREE`	搜尋的預設搜尋範圍。有效值包括 `OBJECT` `ONELEVEL` `SUBTREE`
`ignore-name-not-found`	`假`	指定在搜尋中是否應忽略 `NameNotFoundException`。將此屬性設定為 `true` 會使由無效搜尋基引起的錯誤被靜默吞噬。
`ignore-partial-result`	`假`	指定在搜尋中是否應忽略 `PartialResultException`。某些 LDAP 伺服器在處理引用時存在問題。這些通常應自動跟隨。但是，如果這不起作用，它會以 `PartialResultException` 的形式出現。將此屬性設定為 `true` 提供了一種解決此問題的方法。
`odm-ref`		要使用的 `ObjectDirectoryMapper` 例項的 ID。預設值是預設配置的 `DefaultObjectDirectoryMapper`。

獲取對基本 LDAP 路徑的引用

如前所述，您可以向 ContextSource 提供一個基本 LDAP 路徑，指定 LDAP 樹中的根目錄，所有操作都相對於該根目錄。這意味著您在整個系統中只使用相對區分名，這通常非常方便。但是，在某些情況下，您可能需要訪問基本路徑，以便能夠構建相對於 LDAP 樹實際根目錄的完整 DN。一個示例是在處理 LDAP 組時（例如，groupOfNames 物件類）。在這種情況下，每個組成員屬性值都需要是引用成員的完整 DN。

因此，Spring LDAP 有一個機制，任何 Spring 控制的 bean 都可以在啟動時提供基本路徑。為了使 bean 收到基本路徑的通知，需要滿足兩個條件。首先，需要基本路徑引用的 bean 需要實現 BaseLdapNameAware 介面。其次，您需要在應用程式上下文中定義一個 BaseLdapPathBeanPostProcessor。以下示例顯示瞭如何實現 BaseLdapNameAware

示例 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();
   }
   ...
}

以下示例顯示瞭如何定義 BaseLdapPathBeanPostProcessor

示例 6. 在您的 ApplicationContext 中指定 BaseLdapPathBeanPostProcessor

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

BaseLdapPathBeanPostProcessor 的預設行為是使用 ApplicationContext 中唯一定義的 BaseLdapPathSource (AbstractContextSource) 的基本路徑。如果定義了多個 BaseLdapPathSource，則需要透過設定 baseLdapPathSourceName 屬性來指定要使用哪一個。

配置

ContextSource 配置

DirContext 身份驗證

自定義 DirContext 身份驗證處理

TLS