4.3. LDAP (Lightweight Directory Access Protocol) および Active Directory

Red Hat build of Keycloak は、LDAP からローカルの Red Hat build of Keycloak ユーザーデータベースにユーザーをインポートします。このユーザーデータベースのコピーは、オンデマンドまたは定期的なバックグラウンドタスクを介して同期します。パスワード同期の例外が存在します。Red Hat build of Keycloak がパスワードをインポートすることはありません。パスワードの検証は LDAP サーバーで常に行われます。

同期の利点は、追加で必要なユーザーごとのデータがローカルに保存されるため、すべての Red Hat build of Keycloak 機能が効率的に動作することです。欠点は、Red Hat build of Keycloak が特定のユーザーに初めてクエリーを実行するたびに、Red Hat build of Keycloak が対応するデータベースの挿入を実行することです。

インポートを LDAP サーバーと同期できます。LDAP マッパーがデータベースではなく LDAP から特定の属性を常に読み取る場合、インポート同期は必要ありません。

Red Hat build of Keycloak のユーザーデータベースにユーザーをインポートしなくても、Red Hat build of Keycloak で LDAP を使用できます。LDAP サーバーは、Red Hat build of Keycloak ランタイムが使用する共通ユーザーモデルをバックアップします。Red Hat build of Keycloak の機能に必要なデータを LDAP がサポートしていない場合、その機能は動作しません。このアプローチの利点は、LDAP ユーザーのコピーを Red Hat build of Keycloak のユーザーデータベースにインポートして同期するためのリソースを使用しないことです。

LDAP 設定ページの Import Users スイッチは、このストレージモードを制御します。ユーザーをインポートするには、この切り替えを ON に切り替えます。

ユーザーと管理者はユーザーメタデータを変更できます。ユーザーは Account Console から、管理者は管理コンソールから変更できます。LDAP 設定ページの Edit Mode 設定により、ユーザーの LDAP 更新権限が定義されます。

LDAP ストアへの安全な接続 URL (たとえば、ldaps://myhost.com:636) を設定すると、Red Hat build of Keycloak は SSL を使用して LDAP サーバーと通信します。Red Hat build of Keycloak が LDAP への SSL 接続を信頼できるように、Red Hat build of Keycloak サーバー側でトラストストアを設定します。トラストストアの設定 の章を参照してください。

Use Truststore SPI 設定プロパティーの使用は非推奨です。通常は Always のままにしてください。

Import Users オプションを設定すると、LDAP プロバイダーが Red Hat build of Keycloak ローカルデータベースへの LDAP ユーザーのインポートを処理します。ユーザーが初めてログインするとき、またはユーザークエリーの一部として返されるとき (例: 管理コンソールの検索フィールドを使用する場合)、LDAP プロバイダーは LDAP ユーザーを Red Hat build of Keycloak データベースにインポートします。認証中に、LDAP パスワードが検証されます。

すべての LDAP ユーザーを Red Hat build of Keycloak データベースに同期する場合は、LDAP プロバイダー設定ページで Sync Settings を設定して有効にします。

2 種類の同期が存在します。

同期する最適な方法として、LDAP プロバイダーの初回作成時にすべてのユーザーの同期をクリックし、変更したユーザーの定期的な同期を設定するのが最適です。

LDAP マッパーは LDAP プロバイダーによってトリガーされる listeners です。別の拡張は LDAP 統合を指定します。LDAP マッパーは、以下の場合にトリガーされます。

LDAP フェデレーションプロバイダーを作成すると、Red Hat build of Keycloak がこのプロバイダーの mappers セットを自動的に提供します。これは、ユーザーはマッパーの開発や、既存マッパーの更新/削除を行えます。

ユーザー名、名、姓、メールなどの基本的な Red Hat build of Keycloak ユーザー属性を、対応する LDAP 属性にマッピングするユーザー属性マッパー。これらを拡張し、独自の追加属性マッピングを提供できます。管理コンソールは、対応するマッパーの設定に役立つツールチップを提供します。

Red Hat build of Keycloak は、パスワードを更新するとそのパスワードをプレーンテキスト形式で送信します。このアクションは、Red Hat build of Keycloak がデータベースに送信する前にパスワードをハッシュ化してソルト化する、Red Hat build of Keycloak のビルトインデータベースにおけるパスワード更新とは異なります。LDAP の場合、Red Hat build of Keycloak は LDAP サーバーに依存してパスワードのハッシュ化とソルト化を行います。

デフォルトでは、MSAD、RHDS、FreeIPA ハッシュ、ソルトパスワードなどの LDAP サーバー。RFC3062 で説明されているように LDAPv3 Password Modify Extended Operation を使用しない限り、OpenLDAP や ApacheDS などのその他の LDAP サーバーは、パスワードをプレーンテキストに保存します。LDAP 設定ページで LDAPv3 Password Modify Extended Operation を有効にします。詳細は、お使いの LDAP サーバーのドキュメントを参照してください。

LDAP 接続の管理効率を高め、複数の接続を処理する際のパフォーマンスを向上させるために、接続プールを有効にできます。そうすることで、接続が閉じたときに、将来使用できるようにプールに戻されるため、常に新しい接続を作成するコストが削減されます。

LDAP 接続プールの設定は、次のシステムプロパティーを使用して設定します。

詳細は、Java LDAP Connection Pooling Configuration ドキュメントを参照してください。

これらのプロパティーを設定するには、JAVA_OPTS_APPEND 環境変数を設定します。

export JAVA_OPTS_APPEND=-Dcom.sun.jndi.ldap.connect.pool.initsize=10 -Dcom.sun.jndi.ldap.connect.pool.maxsize=50

カテゴリー org.keycloak.storage.ldap では、ログレベルを TRACE に増やすと便利です。この設定により、多数のロギングメッセージは TRACE レベルの server.log ファイルに送信されます。これには、すべてのクエリーのログが LDAP サーバーとクエリーの送信に使用されたパラメーターが含まれます。ユーザーフォーラムまたは JIRA で LDAP の質問を作成する場合は、TRACE ロギングを有効にしてサーバーログを添付することを検討してください。大きすぎる場合は、操作中にログに追加されたメッセージを含む、サーバーログのスニペットだけを含めるのが良いでしょう。これにより、問題が発生します。

Creating new LDAP Store for the LDAP storage provider: ...

LDAP プロバイダーの設定が表示されます。質問またはバグを報告する前に、このメッセージを LDAP 設定に含めることが推奨されます。最終的には、一部の設定変更 (含めない) をプレースホルダーの値に置き換えることもあると考えられます。1 つ目は bindDn=some-placeholder です。connectionUrl の場合は、自由に置き換えるようにしてください。ただし、一般的には、使用されたプロトコル (ldap vs ldaps) を含めると便利です。同様に、LDAP マッパーの設定の詳細を含めると役に立ちます。これは、DEBUG レベルで以下のようなメッセージと共に表示されます。

Mapper for provider: XXX, Mapper name: YYY, Provider: ZZZ ...

これらのメッセージは、有効になっている DEBUG ロギングとともに表示されることに注意してください。

サーバーの再起動後も接続プールに関するメッセージが表示されない場合は、LDAP サーバーで接続プールが機能していない可能性があります。