最新の安定バージョンについては、Spring LDAP 4.1.1 を使用してください！

構成

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: 最も単純なコンテキストソース宣言

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

前の例では、デフォルト値 (この段落の後の表を参照) と指定された URL および認証資格情報を使用して LdapContextSource を作成します。context-source で構成可能な属性は次のとおりです (* でマークされた必須属性)。

表 1: ContextSource 構成属性
属性	デフォルト	説明
`id`	`contextSource`	作成された Bean の ID。
`username`		LDAP サーバーで認証するときに使用するユーザー名 (プリンシパル)。これは通常、管理ユーザーの識別名 (たとえば、`cn=Administrator`) ですが、サーバーと認証方法によって異なる場合があります。`authentication-source-ref` が明示的に構成されていない場合は必須です。
`password`		LDAP サーバーで認証するときに使用するパスワード (資格情報)。`authentication-source-ref` が明示的に構成されていない場合は必須です。
`url` *		The URL of the LDAP server to use. The URL should be in the following format: `ldap://myserver.example.com:389`. For SSL access, use the `ldaps` protocol and the appropriate port — for example, `ldaps://myserver.example.com:636`. If you want fail-over functionality, you can specify more than one URL, separated by commas (`,`).
`base`	`LdapUtils.emptyLdapName()`	ベース DN。この属性が構成されている場合、LDAP 操作に提供され、LDAP 操作から受信されるすべての識別名は、指定された LDAP パスに関連しています。これにより、LDAP ツリーに対する作業が大幅に簡素化されます。ただし、基本パスにアクセスする必要がある場合がいくつかあります。詳細については、ベース LDAP パスへの参照の取得を参照してください。
`anonymous-read-only`	`false`	匿名 (認証されていない) コンテキストを使用して読み取り専用操作を実行するかどうかを定義します。このパラメーターをカバレッジトランザクションサポートと一緒に `true` に設定することはサポートされておらず、拒否されることに注意してください。
`referral`	`null`	こちら [Oracle] (英語) で説明されているように、参照を処理するための戦略を定義します。有効な値は次のとおりです。 `ignore` `follow` `throw`
`native-pooling`	`false`	ネイティブ Java LDAP 接続プーリングを使用するかどうかを指定します。代わりに Spring LDAP 接続プーリングの使用を検討してください。詳細については、プーリングのサポートを参照してください。
`authentication-source-ref`	`SimpleAuthenticationSource` インスタンス。	使用する `AuthenticationSource` インスタンスの ID ( カスタムプリンシパルと資格情報の管理を参照)。
`authentication-strategy-ref`	`SimpleDirContextAuthenticationStrategy` インスタンス。	使用する `DirContextAuthenticationStrategy` インスタンスの ID ( カスタム `DirContext` 認証処理を参照)。
`base-env-props-ref`		構築時に `DirContext` に送信される環境と共に提供されるカスタム環境プロパティの `Map` への参照。

`DirContext` 認証

LDAP サーバー上で操作を実行するために DirContext インスタンスを作成する場合、これらのコンテキストは認証が必要になることがよくあります。Spring LDAP は、この設定を行うためのさまざまなオプションを提供します。

このセクションでは、LdapClient および LdapTemplate で使用する DirContext インスタンスを構築するための、ContextSource のコア機能におけるコンテキストの認証について説明します。LDAP は一般にユーザー認証のみを目的として使用され、ContextSource も同様に使用される場合があります。このプロセスについては、Spring LDAP を使用したユーザー認証で説明します。

デフォルトでは、読み取り専用操作と読み書き操作の両方に対して認証済みコンテキストが作成されます。context-source 要素で認証に使用する LDAP ユーザーの username および password を指定する必要があります。

username が LDAP ユーザーの識別名 (DN) である場合、context-source 要素で base LDAP パスが指定されているかどうかに関係なく、LDAP ツリーのルートからのユーザーの完全な DN である必要があります。

一部の 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 という 2 つの構成オプションを提供します。どちらの実装もターゲット接続で 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 操作を実行するときに、そのユーザーのプリンシパルと資格情報を使用する必要があるというものです。username および password を明示的に指定する代わりに、authentication-source-ref 要素を使用して、AuthenticationSource 実装への参照を context-source 要素に提供することにより、既定の動作を変更できます。認証された Context が作成されるたびに、AuthenticationSource は ContextSource によってプリンシパルと資格情報を照会されます。

Spring Security を使用する場合、Spring Security に同梱されている SpringSecurityAuthenticationSource のインスタンスを使用して ContextSource を構成することにより、現在ログインしているユーザーのプリンシパルと資格情報が常に使用されるようにすることができます。次の例は、その方法を示しています。

例 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>

username または password の指定はありません。AuthenticationSource を使用する場合は、当社の context-source を使用します。これらのプロパティは、既定の動作を使用する場合にのみ必要です。

SpringSecurityAuthenticationSource を使用する場合、Spring Security の LdapAuthenticationProvider を使用して LDAP に対してユーザーを認証する必要があります。

ネイティブ Java LDAP プーリング

内部 Java LDAP プロバイダーは、いくつかの非常に基本的なプーリング機能を提供します。AbstractContextSource で pooled フラグを使用して、この LDAP 接続プールをオンまたはオフにすることができます。デフォルト値は false (リリース 1.3 以降) です。つまり、ネイティブ Java LDAP プーリングはオフになっています。LDAP 接続プールの構成は System プロパティを使用して管理されるため、Spring コンテキスト構成の外部で手動で処理する必要があります。ネイティブプーリング構成の詳細については、こちら (英語) を参照してください。

組み込みの 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 (context-source 要素のデフォルト) の ID を持つことが期待されます。

LdapClient インスタンスは、特定のチェック例外を処理する方法と、クエリに使用するデフォルトの SearchControls を設定できます。

`LdapTemplate` 設定

LdapTemplate は、<ldap:ldap-template> 要素を使用して定義されます。最も単純な ldap-template 宣言は、要素自体です。

例 4: 最も単純な ldap-template 宣言

<ldap:ldap-template />

この要素自体が、デフォルト ID を持つ LdapTemplate インスタンスを作成し、デフォルトの ContextSource を参照します。これは、contextSource (context-source 要素のデフォルト) の ID を持つことが期待されます。

次の表では、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`	`false`	検索で `NameNotFoundException` を無視するかどうかを指定します。この属性を `true` に設定すると、無効な検索ベースによって引き起こされたエラーが静かに飲み込まれます。
`ignore-partial-result`	`false`	検索で `PartialResultException` を無視するかどうかを指定します。一部の LDAP サーバーでは、リフェラルに問題があります。通常、これらは自動的に実行されます。ただし、これが機能しない場合は、`PartialResultException` で明らかになります。この属性を `true` に設定すると、この問題を回避できます。
`odm-ref`		使用する `ObjectDirectoryMapper` インスタンスの ID。デフォルトは、デフォルト構成の `DefaultObjectDirectoryMapper` です。

ベース LDAP パスへの参照の取得

前述のように、すべての操作が相対的な LDAP ツリーのルートを指定して、ベース LDAP パスを ContextSource に指定できます。これは、システム全体で相対識別名のみを使用していることを意味します。これは通常、かなり便利です。ただし、LDAP ツリーの実際のルートに関連する完全な DN を構築できるようにするために、ベースパスへのアクセスが必要になる場合があります。一例として、LDAP グループ (groupOfNames オブジェクトクラスなど) を操作する場合があります。その場合、各グループメンバーの属性値は、参照されるメンバーの完全な DN である必要があります。

そのため、Spring LDAP には、Spring 制御の Bean が起動時にベースパスを取得できるメカニズムがあります。Bean がベースパスを通知されるには、次の 2 つの条件を満たす必要があります。まず、ベースパス参照を必要とする 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://localhost: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