LDAP ネームサービスプロバイダ
Java Naming and Directory Interface™ (JNDI)

はじめに
適合性
環境プロパティー
名前
Attributes
URL
Java オブジェクト
Schema
例外
API マッピング
連合
イベント通知
SASL 認証
SSL および Start TLS
接続プール
セキュリティーについて

1. はじめに

Lightweight Directory Access Protocol (LDAP) は、ディレクトリサービスにアクセスするときのインターネット標準です。JNDI/LDAP サービスプロバイダを使用して、LDAP のプロトコルが実装されているサーバーにアクセスできます。

このドキュメントでは、LDAP サービスプロバイダの機能について説明します。主に、LDAP サービスプロバイダの動作を中心に説明します。詳細は、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」を参照してください。このプロバイダの例および使用方法の説明については、JNDI チュートリアルを参照してください。

LDAP サービスプロバイダには、LDAP アクセスの基本機能が実装されます。多数の一般的な LDAP コントロールのサポート、RMI オブジェクトと CORBA オブジェクトの格納および読み取りに対するサポートなどを基本プロバイダに追加するには、「ブースターパック」をインストールします。ブースターパックは、JNDI の Web サイトからダウンロードできます。

2. 適合性

LDAP サービスプロバイダは、次の標準に準拠しています。

標準	サポート	備考
LDAPv3 (RFC 2251)	はい
LDAPv3 属性 (RFC 2252)	はい
LDAPv3 識別名 (RFC 2253)	はい
LDAP 検索フィルタ (RFC 2254)	はい
LDAP URL 形式 (RFC 2255)	はい
LDAPv3 スキーマ (RFC 2256)	はい
LDAPv2 (RFC 1777)	はい
LDAP 認証 (RFC 2829)	はい
Start TLS 拡張機能 (RFC 2830)	はい
DIGEST-MD5 (RFC 2831)	はい
Manage Referral Control (参照コントロール) (RFC 3296)	はい
Paged Results Control (ページング結果コントロール) (RFC 2696)	はい
Sort Control (ソートコントロール) (RFC 2891)	はい

3. 環境プロパティー

JNDI プロパティー、LDAP 固有のプロパティー、および SASL 固有のプロパティーについては、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」を参照してください。

3.1 JNDI プロパティー

LDAP サービスプロバイダは、次の JNDI 環境プロパティーをサポートします。

プロパティー	サポート	備考
`java.naming.batchsize`	はい	デフォルト値は `1` です。
`java.naming.factory.control`	はい
`java.naming.factory.initial`	はい	LDAP サービスプロバイダを初期コンテキストとして使用するには、`com.sun.jndi.ldap.LdapCtxFactory` を指定します。
`java.naming.factory.object`	はい
`java.naming.factory.state`	はい
`java.naming.language`	いいえ	プロバイダによって無視されます。
`java.naming.provider.url`	はい	Java 2 SDK、v 1.4.1 以前のシステムでは、単一の URL のみ含まれます。Java 2 SDK、v 1.4.2 より前のシステムでは、LDAPS URL を含めることができません。
`java.naming.referral`	はい
`java.naming.security.authentication`	はい	`simple`、`none`、SASL メカニズムのリスト
`java.naming.security.credentials`	はい
`java.naming.security.principal`	はい
`java.naming.security.protocol`	はい	`ssl`

3.2 LDAP 固有のプロパティー

このプロバイダは、次の LDAP 固有の環境プロパティーをサポートします。

プロパティー	サポート	備考
`java.naming.ldap.attributes.binary`	はい
`java.naming.ldap.control.connect`	はい
`java.naming.ldap.deleteRDN`	はい
`java.naming.ldap.derefAliases`	はい
`java.naming.ldap.factory.socket`	はい	`java.naming.security.protocol` プロパティーが `ssl` に設定されている場合、デフォルト値は `javax.net.ssl.SSLSocketFactory`。詳細は、「SSL」を参照してください。
`java.naming.ldap.ref.separator`	はい
`java.naming.ldap.referral.limit`	はい
`java.naming.ldap.typesOnly`	はい
`java.naming.ldap.version`	はい

3.3 SASL 固有のプロパティー

このプロバイダは、次の SASL 固有の環境プロパティーをサポートします。

プロパティー	サポート	備考
`java.naming.security.sasl.authorizationId`	はい
`java.naming.security.sasl.callback`	はい
`java.naming.security.sasl.realm`	はい
`javax.security.sasl.qop`	はい
`javax.security.sasl.strength`	はい	選択される暗号化方式は、Java プラットフォームの Java 暗号化拡張機能 (JCE) サービスプロバイダで使用可能な暗号化方式に依存します。
`javax.security.sasl.maxbuffer`	はい
`javax.security.sasl.server.authentication`	はい
`javax.security.sasl.policy.forward`	はい
`javax.security.sasl.policy.credentials`	はい
`javax.security.sasl.policy.noplaintext`	はい
`javax.security.sasl.policy.noactive`	はい
`javax.security.sasl.policy.nodictionary`	はい
`javax.security.sasl.policy.noanonymous`	はい

3.4 プロバイダ固有のプロパティー

LDAP サービスプロバイダでは、次のプロバイダ固有の環境プロパティーが定義されています。

com.sun.jndi.ldap.connect.pool

このプロパティーを使用して、初期コンテキストインスタンスを作成するときに、プールされた接続を使用する必要があることを指定します。その値が「true」である場合、接続を作成するためのパラメータ (接続要求と呼ばれる) が接続プール構成で規定される基準を満たしていれば、プロバイダはプールされた接続を使用します。このプロパティーが設定されていない場合、またはほかの値に設定されている場合、あるいは接続要求が基準に一致しない場合、プロバイダはプールされた接続を使用しません。接続プールについては、「接続プール」を参照してください。

たとえば、次のコードを実行したとします

env.put("com.sun.jndi.ldap.connect.pool",
"true");

LDAP プロバイダに、初期コンテキストの作成時にプールされた接続を使用するように指示します。

注:Java 2 SDK、v 1.4.1 より前のシステムでは、接続プールはサポートされていません。そのため、このプロパティーは無視されます。

com.sun.jndi.ldap.connect.timeout

このプロパティーの値は、接続タイムアウトのミリ秒数を示す整数を文字列で表現したものです。LDAP プロバイダがこの値の期間中に接続を確立できないと、接続の試行は中止されます。整数は 0 より大きい必要があります。0 以下の整数を指定した場合は、TCP などのネットワークプロトコルのタイムアウト値が使用されます。

このプロパティーが指定されない場合は、接続が確立されるのを待機するか、またはベースとなるネットワークのタイムアウトまで待機します。

次に例を示します。

env.put("com.sun.jndi.ldap.connect.timeout", "500"); を指定すると、0.5 秒以内に接続を確立できない場合、LDAP サービスプロバイダは接続試行を中止します。

接続のために接続プールが要求されている場合、プール内のすべての接続が使用され、かつ最大プールサイズに到達しているときの、接続の最大待機時間がこのプロパティーにより決定されます。このような状況下で、このプロパティーの値がゼロ以下に設定されている場合、プロバイダは接続が可能になるまで無限に待機することになります。それ以外の値に設定されている場合は、プロバイダは最大待機時間を超えた時点で、待機を中断します。詳細は、「接続プール」を参照してください。

注:Java 2 SDK の v 1.4 より前のシステムでは、接続タイムアウトが SDK でサポートされないため、このプロパティーは無視されます。

com.sun.jndi.ldap.read.timeout

このプロパティーの値は、LDAP 操作のための読み取りタイムアウトのミリ秒数を示す整数を文字列で表現したものです。LDAP プロバイダがこの値の期間中に LDAP 応答を取得できないと、読み取りの試行は中止されます。整数は 0 より大きい必要があります。0 以下の整数は、読み取りタイムアウトが指定されていないことを表し、応答があるまで無限に待機するということです。

このプロパティーを指定しないと、デフォルトは応答があるまで待つという設定になります。

次に例を示します。

env.put("com.sun.jndi.ldap.read.timeout", "5000"); を指定すると、サーバーが 5 秒以内に応答しない場合、LDAP サービスプロバイダは読み取りの試行を中止します。

注:Java 2 SDK の v 6.0 より前のシステムでは、読み取りタイムアウトが SDK でサポートされないため、このプロパティーは無視されます。

com.sun.jndi.ldap.netscape.schemaBugs

Netscape Directory Server 4.0 以前のリリースでは、RFC 2252 に準拠しているスキーマエントリはサポートされていません。特に、Netscape サーバーでは RFC 2252 と異なり、OID (SUP および SYNTAX の OID など) は単一引用符で区切り、MUST/MAY リストは括弧で囲む必要があります。Netscape Directory Server 4.0 のスキーマを更新する場合は、このプロパティーを使用してこれらの問題を回避する必要があります。

次の値は、このプロパティー用に定義されたものです。

        true
           回避策を有効にします。
        false
           回避策を有効にしません。

このプロパティーが設定されない場合、デフォルト値は false になります。

次に例を示します。

env.put("com.sun.jndi.ldap.netscape.schemaBugs", "true");

この場合は、回避策が有効になります。

注 1: このプロパティーは、初期コンテキストにだけ渡され、そのプロバイダで固定されます。addToEnvironment または removeFromEnvironment メソッドには影響されません。

注 2: Netscape Directory Server 4.1 を使用している場合は、このプロパティーを使用しないでください。4.1 サーバーでは、括弧の付かない MUST/MAY 句を含むオブジェクトクラス定義を構文解析する際に問題が発生します。単一の MUST/MAY 項目を含むオブジェクトクラス定義を作成または変更する場合、MUST/MAY リストに余分の値 (objectClass など) を追加することにより、このバグを回避してください。

com.sun.jndi.ldap.trace.ber

このプロパティーの値は、java.io.OutputStream オブジェクトです。ここには、受信および送信 LDAP ASN.1 BER パケットの 16 進数ダンプが書き込まれます。このプロパティーのデフォルトは定義されていません。

次に例を示します。

env.put("com.sun.jndi.ldap.trace.ber",
System.out);

この場合、LDAP プロトコルトレースは標準の出力ストリームに書き込まれます。

注:このプロパティーは、初期コンテキストにだけ渡され、そのプロバイダで固定されます。addToEnvironment または removeFromEnvironment メソッドには影響されません。

4. 名前

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」の説明に従った名前をサポートします。次の形式の LDAP 識別名がサポートされています。

識別名の形式	備考
`String`	合成名とみなされます。合成名の最初のコンポーネントは、識別名として処理されます。残りのコンポーネントは連合されます。
`名前`	`CompositeName` のインスタンスの場合は、合成名として処理します。つまり、合成名の最初のコンポーネントを識別名として処理し、残りを連合に使用します。それ以外の場合は、解析された LDAP 名として処理します。ここで、`Name` の各コンポーネントは、RFC 2253 で定義されている LDAP 名のコンポーネントです。
LDAP URL 文字列	初期コンテキストに渡されると、LDAP URL 文字列は RFC 2255 に基づいて解釈され、その識別名コンポーネントは RFC 2253 に基づいて解釈されます。
LDAPS URL 文字列	LDAPS URL 文字列は、初期コンテキストに渡されると、サーバーとの通信に SSL 接続が使用される点を除き、LDAP URL と同じように解釈されます。注:Java 2 SDK、v. 1.4.2 より前のシステムでは、LDAP サービスプロバイダは LDAPS URL を認識しません。

getNameParser() の呼び出しによって返された名前パーサーは、パーサーを返します。このパーサーは文字列名を受け取ると、それを RFC 2253 に基づいてコンポーネントに構文解析します。

5. Attributes

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」の説明に従った属性をサポートします。LDAP 属性値を指定するための次の形式がサポートされています。

属性値の形式	サポート	備考
`String` 値	はい
`byte[]` 値	はい

一部の LDAP サーバーでは、属性値に対して言語の優先順位を指定するときに、属性の部分型、属性名の類語、および言語コードを使用できます。この場合、LDAP サーバーから返された属性名は、要求した属性名と異なることがあります。

LDAP では、属性名の大文字小文字が区別されます。このため、パラメータとして JNDI 操作に渡す属性のまとまりを作成するときは、大文字小文字が区別される属性クラスを使用することをお勧めします。次に例を示します。

Attributes attrs = new BasicAttributes(true); // ignoreCase=true

すべての属性値について、それが String か byte[] かには関係なく、その属性値の構文と形式がわかっている必要があります。属性値の構文と形式は、これらの情報が定義されているスキーマドキュメントで確認できます。

属性が引数として JNDI 呼び出しに渡される場合、それらの属性は、LDAP ディレクトリで適用されるすべてのスキーマを満たしている必要があります。特に、新しい LDAP エントリを作成している場合 (たとえば、Context.bind、Context.rebind、または DirContext.createSubcontext を使用している場合) は通常、objectClass 属性が必要です。

6. URL

6.1 使用法

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」の説明に従った URL をサポートします。LDAP と LDAPS の両方の URL が使用できます。

URL の次の使用がサポートされています。

URL の使用法	サポート	備考
LDAP URL と LDAPS URL を使用して LDAP サービスプロバイダを設定する。	はい
`InitialDirContext` メソッドに名前として渡される URL。	はい
LDAP 照会で URL を使用する	はい	LDAP/LDAPS URL のスコープコンポーネントはサポートされます。属性、フィルタ、および拡張コンポーネントは無視されます。
`list`、`listBindings`、および `search` 列挙内の名前として返される URL。	はい
連合された名前空間に URL をリンクする。	はい

注:Java 2 SDK、v. 1.4.2 より前のシステムでは、LDAP サービスプロバイダは LDAPS URL を認識することも返すこともありません。

6.2 LDAP サービスの自動検出

LDAP サービスプロバイダは、DNS 設定を使用した LDAP サービスの自動検出をサポートします。上記の使用例の LDAP/LDAPS URL にホスト名とポートがないが、空でない識別名が含まれている場合、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」で説明されているように、LDAP サービスプロバイダは使用する LDAP サーバーの検出を試みます。

たとえば、ldap:///dc=example,dc=com の URL が指定されている場合、サービスプロバイダは、DNS SRV レコードで _ldap._tcp.example.com の検出を試みます。プロバイダがこのようなレコードを検出した場合、このレコードから LDAP サーバーのホスト名とポートを抽出し、これらを使用します。これらのレコードが使用される順序は、インターネットドラフト draft-ietf-ldapext-locate-08.txt で説明されているアルゴリズムに従います。

LDAP サービスの DNS SRV レコードを検出する場合、LDAP サービスプロバイダは基本プラットフォームに設定された DNS サービスを使用します (たとえば、Solaris または Linux では、DNS クライアント設定は /etc/resolv.conf ファイルから読み込まれる)。基本プラットフォームに DNS が構成されていない場合、LDAP サービスプロバイダは、DNS サーバーのホスト名とポートとして localhost と 53 を使用します。DNS サービスが使用できない場合、または DNS サービスに LDAP サービスの SRV レコードが存在しない場合、LDAP サービスプロバイダはホスト名として localhost を使用し、プレーン接続ではポートとして 389 を、SSL 接続ではポートとして 636 を使用します。

注 1: Java 2 SDK、v 1.4.1 より前のシステムでは、ホスト名とポートが指定されていない場合は常に、デフォルトでそれぞれ localhost と 389 になります。DNS を使用する試みは行われません。

注 2: Java 2 SDK、v 1.4.2 より前のシステムでは、SSL の使用とは関係なく、デフォルトのポートは常に 389 です。

7. Java オブジェクト

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」で指定されている次の種類のオブジェクトの格納と読み取りをサポートします。

格納および読み取りが可能なオブジェクト	サポート	備考
`Reference` オブジェクト	はい
`Referenceable` オブジェクト	はい
`Serializable` オブジェクト	はい
`DirContext` オブジェクト	はい

例については、JNDI チュートリアルを参照してください。

8. Schema

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」で指定されている次のスキーマバインディングをサポートします。

スキーマツリー	サポート	備考
AttributeDefinition	はい
ClassDefinition	はい
SyntaxDefinition	はい
MatchingRule	はい
ExtensionDefinition	いいえ
ControlDefinition	いいえ
SASLMechanism	いいえ

9. 例外

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」に従って、LDAP エラーコードを JNDI 例外にマップします。

10. API マッピング

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」に従って、次の JNDI API メソッドを LDAP にマップします。

`Context` メソッドのマッピング	サポート	備考
`addToEnvironment`	はい
`bind`	はい
`close`	はい
`composeName`	はい
`destroySubcontext`	はい
`getEnvironment`	はい
`getNameInNamespace`	はい
`getNameParser`	はい
`list`	はい
`listBindings`	はい
`lookup`	はい	`LinkRef` は対象外。
`lookupLink`	はい
`rebind`	はい
`removeFromEnvironment`	はい
`rename`	はい
`unbind`	はい

`DirContext` メソッドのマッピング	サポート	備考
`bind`	はい
`createSubcontext`	はい
`destroySubcontext`	はい
`getAttributes`	はい
`getSchema`	はい
`getSchemaClassDefinition`	はい
`modifyAttributes`	はい
`rebind`	はい
`search`	はい

`LdapContext` メソッドのマッピング	サポート	備考
`extendedOperation`	はい
`getRequestControls`	はい
`getResponseControls`	はい
`newInstance`	はい
`reconnect`	はい
`setRequestControls`	はい

`EventDirContext` メソッドのマッピング	サポート	備考
`addNamingListener`	はい
`removeNamingListener`	はい
`targetMustExist`	はい

11. 連合

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」の説明に従った連合をサポートします。次の連合方法がサポートされています。

連合方法	サポート	備考
連結	はい	下位のネーミングシステムが別の LDAP システムの場合は除く
暗黙的な次のネーミングシステムポインタ	はい

LDAP サービスプロバイダでは、合成名は強く区分されているとみなされます。つまり、合成名の最初のコンポーネントが識別名として処理され、残りのコンポーネントは次のネーミングシステムの名前として処理されます。たとえば、次の例では、次のネーミングシステムのルートのリストを出力しています。このネーミングシステムは、LDAP コンテキストを超えて連合されています。次に、マルチコンポーネントの合成名を使用して名前が参照されます。

// List the root of the nns, 
// Note use of the trailing slash to indicate traversal into the nns
NamingEnumeration enum = ctx.list("cn=objects,ou=Sales/");

// A composite name lookup
Object obj = ctx.lookup("cn=objects,ou=Sales/some/x/y/z");

12. イベント通知

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」の説明に従ったイベント通知をサポートします。次のイベントがサポートされています。

Event	サポート	備考
名前空間の変更の通知	はい	持続的検索コントロールを使用*
オブジェクトの変更の通知	はい	持続的検索コントロールを使用*
非要請通知	はい

* 持続的検索コントロールは、IETF インターネットドラフト draft-ietf-ldapext-psearch-03.txt で定義されています。

13. SASL 認証

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」の説明に従った SASL 認証をサポートします。

LDAP サービスプロバイダでは、次の SASL メカニズムがサポートされます。

EXTERNAL (RFC 2222)。このメカニズムは、SSL/TSL や IPsec などの外部ソースから認証情報を取得する。
DIGEST-MD5 (RFC 2831) は、ダイジェスト認証用です。
GSSAPI (RFC 2222) は、Kerberos V5 認証用です。

これらのメカニズムに加えて、このプロバイダは、Java SASL API (JSR 28 Public Review Draft) で定義されているフレームワーク経由で使用可能になる追加の SASL メカニズムをサポートします。ただし、パッケージの名前は javax.security.sasl ではなく com.sun.security.sasl.preview になっています。

14. SSL および Start TLS

14.1 SSL

LDAP サービスプロバイダは、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」の説明に従った SSL をサポートします。java.naming.ldap.factory.socket プロパティーがほかのソケットファクトリのクラス名に設定されていないかぎり、デフォルトのソケットファクトリ javax.net.ssl.SSLSocketFactory が使用されます。

SSL が使用され、ポートが指定されていない場合、デフォルトポートとして 636 が使用されます。

注:Java 2 SDK、v 1.4.1 より前のシステムでは、SSL の使用とは関係なく、デフォルトのポートは常に 389 です。

14.2 TLS の起動

LDAP プロバイダは、StartTlsResponse 抽象クラスの固定実装を指定することにより、「Start TLS」拡張機能 (「1.3.6.1.4.1.1466.20037」) をサポートします。ホスト名の検証は、「LDAP サービスプロバイダに対する JNDI 実装側のガイドライン」に従って実行されます。

15. 接続プール

注:接続プールは、Java 2 SDK、v 1.4.1 以降のリリースでのみサポートされます。

15.1 概要

LDAP サービスプロバイダは、以前に使用された接続のプールを維持することで接続プールをサポートします。LDAP プロバイダが接続を必要とする場合は常に (およびアプリケーションからプールが要求されている場合)、プールから接続を取得します。既存の接続が使用できる場合は、これが使用されます。既存の接続が使用できない場合、新しい接続が作成され、使用されます。プロバイダが接続を終了すると、接続はアイドルのマークが付けられ、再利用できます。

アプリケーションは、初期コンテキストコンストラクタに渡される環境プロパティーに com.sun.jndi.ldap.connect.pool プロパティーを追加することによって、接続プールを要求します。アプリケーションは、環境プロパティーをこのプロパティーとともに使用するか、またはこのプロパティーなしで使用することによって、プールをコンテキスト単位に使用するかどうかを決定できます。初期コンテキストに渡される LDAP/LDAPS の両 URL の参照処理に、プールされた接続を使用するかどうかも、同じメカニズムを使用して制御されます。たとえば、プロバイダが参照を処理する場合に、環境プロパティーにこのプロパティーが含まれているとき、プロバイダは参照にプールされた接続を使用します。

次のコード例では、新しい初期コンテキストと、ここから導出されるすべてのコンテキストに接続プールを使用するように要求しています。

Hashtable env = new Hashtable();
env.put("com.sun.jndi.ldap.connect.pool", "true");
env.put(Context.PROVIDER_URL, url);
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
DirContext ctx = new InitialDirContext(env);
...

1 つのプロパティー com.sun.jndi.ldap.connect.pool を追加するだけで済みます。アプリケーションへのその他の変更は必要ありません。

LDAP プロバイダは、アプリケーションからの情報を元に接続が使用されているかどうかを追跡します。アプリケーションのコンテキストハンドルが開いている場合、そのアプリケーションが接続を使用しているものと見なします。そのため、LDAP プロバイダがプールされた接続を正しく管理するには、必要なくなったコンテキストでアプリケーションが必ず Context.close() を呼び出す必要があります。

無効な接続は自動的に検出され、プールから削除されます。コンテキストが無効な接続により終了する確率は、接続プールを使用しているかどうかにかかわらず同じです。

15.2 プールを使用しない場合

プールされた接続は再利用を目的としています。したがって、コンテキストで基本接続の状態を変えるような操作を実行することが予定されるアプリケーションでは、コンテキストに接続プールを使用すべきではありません。特に、アプリケーションがコンテキストで Start TLS 拡張操作を使用する予定があるか、または初期コンテキストが作成されたあとにセキュリティー関連のプロパティー (java.naming.security.principal や java.naming.security.protocol など) を変更する予定がある場合は、そのコンテキストに接続プールを使用すべきではありません。このような状況で接続プールを使用した場合、アプリケーションのセキュリティーが損なわれたり、予期しない動作が起こる場合があります。

15.3 グローバル設定

接続プールは、Java ランタイムごとに設定および管理されます。接続は異なるランタイム間で共有されません。接続プールを使用する場合、設定を変更する必要はありません。設定が必要になるのは、プールのサイズの制御、およびプールされる接続の指定など、プールの設定をカスタマイズする場合だけです。

接続プールは、ランタイム起動時にいくつかのシステムプロパティーにより設定されます。これらは環境プロパティーではなく、システムプロパティーであるため、すべての接続プール要求に影響を与えることに注意してください。

次にシステムプロパティーのサマリーを示します。以降ではシステムプロパティーについて詳細に説明します。

システムプロパティー名	説明	デフォルト
`com.sun.jndi.ldap.connect.pool.authentication`	プールできる接続の、スペース区切りの認証タイプのリスト。「none」、「simple」、「DIGEST-MD5」のいずれかのタイプが使用できる	`「none simple」`
`com.sun.jndi.ldap.connect.pool.debug`	生成されるデバッグ出力のレベルを示す文字列。有効な値は、`"fine"` (接続の作成および削除のトレース) と "all" (すべてのデバッグ情報) です。
`com.sun.jndi.ldap.connect.pool.initsize`	接続 ID の接続を最初に作成するときに作成する、その ID あたりの接続数を表す整数の文字列表現。	1
`com.sun.jndi.ldap.connect.pool.maxsize`	同時に保持できる接続 ID あたりの最大接続数を表す整数の文字列表現。	最大サイズはなし
`com.sun.jndi.ldap.connect.pool.prefsize`	同時に保持するべき接続 ID あたりの優先的接続数を表す整数の文字列表現。	優先的サイズはなし
`com.sun.jndi.ldap.connect.pool.protocol`	プールできる接続の、スペース区切りのプロトコルタイプのリスト。「plain」と「ssl」のタイプが有効	`「plain」`
`com.sun.jndi.ldap.connect.pool.timeout`	アイドル接続が閉じられず、プールからも削除されることなくプール内に残ることのできるミリ秒数を表す整数の文字列表現。	タイムアウトはなし

次のプールされた接続の例では、最大プールサイズを 20、優先的なプールサイズを 10、アイドルタイムアウトを 5 分に設定しています。

# java -Dcom.sun.jndi.ldap.connect.pool.maxsize=20 \
       -Dcom.sun.jndi.ldap.connect.pool.prefsize=10 \
       -Dcom.sun.jndi.ldap.connect.pool.timeout=300000 \
    YourProgram

15.3.1 プールの結果

LDAP プロバイダがプールされた接続を使用するのは、アプリケーションがそれを要求し、接続の要求がプール基準を満たしている場合だけです。アプリケーションは、com.sun.jndi.ldap.connect.pool 環境プロパティーを使用して、接続がプールされることを要求します。デフォルトのプール基準では、簡単な認証を使用するか、まったく認証を用いないプレーンな (非 SSL) 接続のプールが許可されています。システムプロパティーを使用してプール基準を変更し、SSL 接続および DIGEST-MD5 認証タイプを追加することも可能です。プロトコルトレースが有効になっている接続 (com.sun.jndi.ldap.trace.ber 環境プロパティーを介して) はプールできません。カスタムソケットファクトリからの接続のプールについては、「カスタムソケットファクトリの接続のプール」を参照してください。

SSL 接続をプールできるようにするには、com.sun.jndi.ldap.connect.pool.protocol システムプロパティーに文字列 "ssl" を含めます。たとえば、プレーン接続と SSL 接続の両方をプールできるようにするには、このシステムプロパティーを文字列 "plain ssl" に設定します。

DIGEST-MD5 接続をプールできるようにするには、com.sun.jndi.ldap.connect.pool.authentication システムプロパティーに文字列 "DIGEST-MD5" を含めます。たとえば、認証タイプが anonymous、simple、および DIGEST-MD5 の接続をプールできるようにするには、このシステムプロパティーを文字列 "none simple DIGEST-MD5" に設定します。

15.3.2 接続のプール方法

LDAP プロバイダは、プールされた接続を再利用できるように保持します。アプリケーションからプールされた接続の使用が要求された場合、LDAP プロバイダは既存のプールされた接続で要求を満たすことが可能かどうかを判断する必要があります。それを行うために、プールされた各接続に接続 ID を割り当て、着信要求の接続 ID がプールされた接続のいずれかと同じかどうかをチェックします。

接続 ID は認証が予測される LDAP 接続を作成するのに必要なパラメータセットです。その構成は、次の表に示すように要求の認証タイプにより異なります。

認証タイプ接続 ID の内容

なし

認証タイプ	接続 ID の内容
なし	接続コントロール `java.naming.provider.url` プロパティー、参照、または初期コンテキストに指定された URL で指定されているホスト名、ポート番号、およびスキーム次のプロパティーの内容: java.naming.security.protocol java.naming.ldap.version
simple	anonymous にリストされたすべての情報次のプロパティーの内容: java.naming.security.principal java.naming.security.credentials
DIGEST-MD5	simple にリストされたすべての情報次のプロパティーの内容: java.naming.security.sasl.authorizationId java.naming.security.sasl.realm javax.security.sasl.qop javax.security.sasl.strength javax.security.sasl.server.authentication javax.security.sasl.maxbuffer javax.security.sasl.policy.noplaintext javax.security.sasl.policy.noactive javax.security.sasl.policy.nodictionary javax.security.sasl.policy.noanonymous javax.security.sasl.policy.forward javax.security.sasl.policy.credentials

接続コントロール
java.naming.provider.url プロパティー、参照、または初期コンテキストに指定された URL で指定されているホスト名、ポート番号、およびスキーム

次のプロパティーの内容:

java.naming.security.protocol
java.naming.ldap.version

simple

anonymous にリストされたすべての情報

次のプロパティーの内容:

java.naming.security.principal
java.naming.security.credentials

DIGEST-MD5

simple にリストされたすべての情報

次のプロパティーの内容:

java.naming.security.sasl.authorizationId
java.naming.security.sasl.realm
javax.security.sasl.qop
javax.security.sasl.strength
javax.security.sasl.server.authentication
javax.security.sasl.maxbuffer
javax.security.sasl.policy.noplaintext
javax.security.sasl.policy.noactive
javax.security.sasl.policy.nodictionary
javax.security.sasl.policy.noanonymous
javax.security.sasl.policy.forward
javax.security.sasl.policy.credentials

15.3.3 カスタムソケットファクトリの接続のプール

java.naming.ldap.factory.socket 環境プロパティーが設定されている場合は、カスタムソケットファクトリからの接続のプールが許可されます。カスタムソケットファクトリをプールするには、ソケットファクトリクラスが Comparator インタフェースを実装する必要があります。LDAP サービスプロバイダは、プールメカニズムによって接続の同等性がチェックされているソケットファクトリの同等性を比較するために Comparator.compare() メソッドを呼び出します。ソケットファクトリの比較では必ず、接続の同等性に影響を及ぼすソケットファクトリのパラメータが比較されるようにします。この比較は、「接続のプール方法」で説明した接続 ID の比較と合わせて行われます。カスタムソケットファクトリクラスは、その接続がプールされる場合、必ず次のような構造となります。

    public class CustomSocketFactory extends SocketFactory
                implements Comparator<SocketFactory> { 
       :
       :
       public int compare(SocketFactory sf1, SocketFactory sf2) {
           :
           :
           // do whatever comparison that's required
       }
    }

ソケットファクトリクラスが Comparator インタフェースを実装しない場合、ソケットファクトリクラスの接続はプールできません。この Comparator インタフェースの実装要件は、LDAP サービスプロバイダが実装を認識していない別のソケットファクトリの接続を比較する場合、必ず LDAP サービスプロバイダが必要なチェックを行うことです。

15.3.4 プールのサイズ

LDAP プロバイダは接続のプールを管理します。各プールには同じ接続 ID を持つ (使用中かアイドル中の) 接続が格納されます。各プールの 3 つのサイズにより、管理方式が異なります。これらのサイズはグローバルであり、すべてのプールに影響します。

初期プールサイズは、LDAP サービスプロバイダがプールを最初に作成するときに作成する、接続 ID あたりの接続数です。(これは、アプリケーションがその接続 ID で、プールされた接続を最初に要求したときの接続数に対応します)。プール内の各接続の認証は、接続が使用される時点で実行されます。デフォルトでは、初期プールサイズは 1 であり、com.sun.jndi.ldap.connect.pool.initsize システムプロパティーを使用して変更できます。通常、このサイズはアプリケーションの起動時に、一定の数のサーバー接続をプールに確保するために使用されます。

最大プールサイズは、LDAP サービスプロバイダが同時に保持できる、接続 ID あたりの接続の最大数です。このサイズには、使用中の接続とアイドル状態の接続が関係します。プールサイズがこの数に達した場合、プール内の接続が削除されるまで (つまり物理的な接続が切断されるまで)、対応する接続 ID の接続が新規に作成されることはありません。プールサイズが最大に達し、プール内のすべての接続が使用中の場合、プール内の接続がアイドル状態になるか削除されるまで、そのプールの接続に対するアプリケーションの要求は拒絶されます。最大プールサイズを 0 にすると、最大サイズがなくなります。プールされた接続への要求があれば、プールされた既存のアイドル状態の接続か、新規に作成されプールされた接続が使用されます。

優先的プールサイズは、LDAP サービスプロバイダが保持するべき、接続 ID あたりの優先的接続数です。このサイズには、使用中の接続とアイドル状態の接続が関係します。アプリケーションがプールされた接続の使用を要求し、プールサイズが優先的サイズよりも小さい場合、LDAP プロバイダはアイドル状態の接続が利用できるかどうかにかかわらず、新しく接続を作成し、新しくプールされた接続を使用します。アプリケーションが (接続を共有するすべてのコンテキストで Context.close() を呼び出すことによって) プールされた接続の使用を完了したときに、プールサイズが優先的サイズを超えている場合、LDAP プロバイダはプールされた接続を閉じてプールから削除します。優先的プールサイズを 0 にすると、優先的サイズがなくなります。プールされた接続への要求があれば、アイドル状態の接続が使用できない場合にかぎり、接続が新規に作成されます。

最大プールサイズは初期プールサイズおよび優先的プールサイズよりも優先されることに注意してください。たとえば、優先的プールサイズを最大プールサイズよりも大きく設定しても、実際には最大プールサイズに設定されます。

15.3.5 アイドル接続

アプリケーションが (接続を共有するすべてのコンテキストで Context.close() を呼び出すことによって) プールされた接続の使用を終了すると、基になるプールされた接続はアイドルとしてマークされ、再利用を待機します。デフォルトでは、アイドル接続はガーベージコレクトされるまでプール内に無限に存在し続けます。"com.sun.jndi.ldap.connect.pool.timeout" システムプロパティーが設定されている場合、LDAP プロバイダは、指定された期間を超えてアイドル状態になっているプールされた接続を自動的に閉じて削除します。

15.4 コンテキスト別設定

15.4.1 プールの有効化

プールを使用するには、初期コンテキストコンストラクタに渡される環境プロパティーの com.sun.jndi.ldap.connect.pool プロパティーを "true" に設定します。プロバイダは設定された環境プロパティーにプール基準を適用し、そのコンテキストにプールを使用するかどうかを判断します。プロバイダが接続をプールできないと判断した場合、そのコンテキストに対して、プールされていない接続を作成し、使用します。

このプロパティーを省略した場合、コンテキストで接続プールが使用されません。

15.4.2 接続タイムアウト

com.sun.jndi.ldap.connect.timeout 環境プロパティーは、LDAP 接続を確立するためのタイムアウト期間を指定するために使用されます。このプロパティーは、LDAP サーバーへの接続を開始する場合には TCP タイムアウトに影響します。接続プールが要求されている場合、プール内のすべての接続が使用され、最大プールサイズに到達しているときの最大待機時間もこのプロパティーにより決定されます。

このプロパティーが指定されていない場合、LDAP プロバイダはプールされた接続が利用できるまで無限に待機します。また新しい接続を作成するときにはデフォルトの TCP タイムアウトが有効になるのを待機します。

このプロパティーは、アイドル状態のプールされた接続の削除に関連する com.sun.jndi.ldap.connect.pool.timeout システムプロパティーとは異なることに注意してください。

16. セキュリティーについて

セキュリティーマネージャーがインストールされている場合は、JNDI を使用するアプリケーションおよび LDAP サービスプロバイダに対して、次のアクセス権を割り当てる必要があります。

permission java.net.SocketPermission "host[:port]", "connect";

java.naming.factory.initial プロパティー、およびコンテキストメソッドに指定されている URL 文字列名で識別される各ホスト/ポート用のアクセス権です。

permission java.net.SocketPermission "host[:port]", "connect,accept";

Serializable オブジェクトを使用して格納されている References および javaCodebase 属性内の URL 文字列で指定される各ホスト/ポート用のアクセス権です。

SASL 認証を使用中に SASL クライアントファクトリをプログラムによって設定する場合は、アプリケーションに次のアクセス権を割り当ててください。

permission java.lang.RuntimePermission "setFactory"

さらに、「GSSAPI」SASL メカニズムを使用する場合は、次のアクセス権も必要になります。

permission javax.security.auth.AuthPermission "createLoginContext.appClassName";
permission javax.security.auth.AuthPermission "doAsPrivileged";

ログインして doAsPrivileged メソッドを呼び出そうとしているアプリケーションクラス用のアクセス権です。

permission java.net.SocketPermission "host[:port]", "connect";

Kerberos Key Distribution Center (KDC) のホスト/ポート用のアクセス権です。

permission javax.security.auth.kerberos.ServicePermission "krbtgt/realm@realm", "initiate";
permission javax.security.auth.kerberos.ServicePermission "ldap/fully-qualified-hostname@realm", "initiate";

LDAP サービスと KDC の範囲とホスト用のアクセス権です。

連絡先

LDAP ネームサービスプロバイダ Java Naming and Directory Interface™ (JNDI)

1. はじめに

2. 適合性

3. 環境プロパティー

3.1 JNDI プロパティー

3.2 LDAP 固有のプロパティー

3.3 SASL 固有のプロパティー

3.4 プロバイダ固有のプロパティー

4. 名前

5. Attributes

6. URL

6.1 使用法

6.2 LDAP サービスの自動検出

7. Java オブジェクト

8. Schema

9. 例外

10. API マッピング

11. 連合

12. イベント通知

13. SASL 認証

14. SSL および Start TLS

14.1 SSL

14.2 TLS の起動

15. 接続プール

15.1 概要

15.2 プールを使用しない場合

15.3 グローバル設定

15.3.1 プールの結果

15.3.2 接続のプール方法

15.3.3 カスタムソケットファクトリの接続のプール

15.3.4 プールのサイズ

15.3.5 アイドル接続

15.4 コンテキスト別設定

15.4.1 プールの有効化

15.4.2 接続タイムアウト

16. セキュリティーについて

LDAP ネームサービスプロバイダ
Java Naming and Directory Interface™ (JNDI)