4.3. LDAP (Lightweight Directory Access Protocol) および Active Directory
Red Hat build of Keycloak には LDAP/AD プロバイダーが含まれています。1 つの Red Hat build of Keycloak レルム内で複数の異なる LDAP サーバーをフェデレーションし、LDAP ユーザー属性を Red Hat build of Keycloak の共通ユーザーモデルにマッピングできます。
デフォルトでは、Red Hat build of Keycloak はユーザーアカウントのユーザー名、メール、名、姓をマッピングしますが、追加の マッピング を設定することもできます。Red Hat build of Keycloak の LDAP/AD プロバイダーは、LDAP/AD プロトコルとストレージ、編集、同期モードを使用したパスワード検証をサポートしています。
4.3.1. フェデレーションされた LDAP ストレージの設定
手順
メニューの User Federation をクリックします。
ユーザーフェデレーション
Add LDAP providers をクリックします。
Red Hat build of Keycloak により、LDAP 設定ページが表示されます。
4.3.2. ストレージモード
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 に切り替えます。
Import Users を無効にすると、Red Hat build of Keycloak データベースにユーザープロファイル属性を保存できなくなります。また、LDAP にマッピングされたユーザープロファイルメタデータ以外のメタデータを保存することはできません。このメタデータには、LDAP マッパーの設定に基づくロールマッピング、グループマッピング、およびその他のメタデータを含めることができます。
LDAP 以外のマッピングユーザーデータを変更しようとすると、ユーザーの更新ができません。たとえば、ユーザーの enabled フラグが LDAP 属性にマッピングされていない限り、LDAP マッピングされたユーザーを無効にすることはできません。
4.3.3. モードの編集
ユーザーと管理者はユーザーメタデータを変更できます。ユーザーは Account Console から、管理者は管理コンソールから変更できます。LDAP 設定ページの Edit Mode 設定により、ユーザーの LDAP 更新権限が定義されます。
- READONLY
- ユーザー名、メール、名、姓、他のマップされた属性を変更することはできません。Red Hat build of Keycloak では、ユーザーがこれらのフィールドを更新しようとするたびにエラーが表示されます。パスワードの更新はサポートされていません。
- WRITABLE
- ユーザー名、メール、名、姓、他のマップされた属性を変更し、LDAP ストアと自動的に同期することはできません。
- UNSYNCED
- Red Hat build of Keycloak はユーザー名、メール、名、姓、パスワードの変更を Red Hat build of Keycloak のローカルストレージに保存するため、管理者はこのデータを LDAP に同期する必要があります。このモードでは、Red Hat build of Keycloak デプロイメントは読み取り専用 LDAP サーバー上のユーザーメタデータを更新できます。このオプションは、LDAP からローカルの Red Hat build of Keycloak ユーザーデータベースにユーザーをインポートするときにも適用されます。
Red Hat build of Keycloak は、LDAP プロバイダーを作成する際に最初の LDAP マッパー セットも作成します。Red Hat build of Keycloak は、Vendor、Edit Mode、Import Users スイッチの組み合わせに基き、これらのマッパーを設定します。たとえば、編集モードが UNSYNCED の場合、Red Hat build of Keycloak は LDAP サーバーからではなくデータベースから特定のユーザー属性を読み取るようにマッパーを設定します。ただし、後で編集モードを変更すると、設定が UNSYNCED モードで変更されたかどうかを検出できないため、マッパーの設定は変更できません。LDAP プロバイダーの作成時に Edit Mode を決定します。この注記は、ユーザーのインポート スイッチにも適用されます。
4.3.4. その他の設定オプション
- コンソール表示名
- 管理コンソールで表示するプロバイダーの名前。
- 優先度
- ユーザーを検索したり、ユーザーを追加したりする際のプロバイダーの優先順位です。
- 登録の同期
- Red Hat build of Keycloak によって作成された新しいユーザーを LDAP に追加する場合は、このスイッチを ON に切り替えます。
- Kerberos 認証を許可
- LDAP からプロビジョニングされたユーザーデータを使用して、レルムで Kerberos/SPNEGO 認証を有効にします。詳細については、Kerberos セクション を参照してください。
- その他のオプション
- マウスポインターを管理コンソールのツールチップの上に置き、これらのオプションの詳細を表示します。
4.3.5. SSL 経由での 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 のままにしてください。
4.3.6. LDAP ユーザーを Red Hat build of Keycloak に同期する
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 種類の同期が存在します。
- 定期的な完全同期 (Periodic Full)
- このタイプでは、すべての LDAP ユーザーが Red Hat build of Keycloak データベースに同期されます。LDAP ユーザーはすでに Red Hat build of Keycloak に存在しますが、LDAP とは異なり、Red Hat build of Keycloak データベースで直接更新されます。
- 定期的な変更したユーザー同期 (Periodic Changed)
- 同期する場合、Red Hat build of Keycloak は、最後の同期後に作成または更新されたユーザーのみを作成または更新します。
同期する最適な方法として、LDAP プロバイダーの初回作成時にすべてのユーザーの同期をクリックし、変更したユーザーの定期的な同期を設定するのが最適です。
4.3.7. LDAP マッパー
LDAP マッパーは LDAP プロバイダーによってトリガーされる listeners です。別の拡張は LDAP 統合を指定します。LDAP マッパーは、以下の場合にトリガーされます。
- ユーザーは LDAP を使用してログインします。
- ユーザーは最初に登録されます。
- 管理コンソールはユーザーにクエリーを実行します。
LDAP フェデレーションプロバイダーを作成すると、Red Hat build of Keycloak がこのプロバイダーの mappers セットを自動的に提供します。これは、ユーザーはマッパーの開発や、既存マッパーの更新/削除を行えます。
- ユーザー属性マッパー
-
このマッパーは、どの LDAP 属性が Red Hat build of Keycloak ユーザーの属性にマッピングされるかを指定します。たとえば、
mailLDAP 属性を Red Hat build of Keycloak データベースのemail属性に設定できます。このマッパーの実装では、1 対 1 のマッピングが常に存在します。 - fullName マッパー
-
このマッパーはユーザーのフルネームを指定します。Red Hat build of Keycloak は、名前を LDAP 属性 (通常は
cn) に保存し、その名前を Red Hat build of Keycloak データベースのfirstNameおよびlastname属性にマッピングします。ユーザーのフルネームを含むcnは LDAP デプロイメントで共通です。
Red Hat build of Keycloak で新規ユーザーを登録し、Sync Registrations が LDAP プロバイダー用に ON になっている場合、fullName マッパーはユーザー名へのフォールバックを許可します。このフォールバックは、Microsoft Active Directory (MSAD) を使用する際に役に立ちます。MSAD の一般的なセットアップでは、cn LDAP 属性を fullName として設定し、同時に LDAP プロバイダー設定の RDN LDAP Attribute として cn LDAP 属性を使用します。この設定では、Red Hat build of Keycloak はユーザー名にフォールバックします。たとえば、"john123" という Red Hat build of Keycloak ユーザーを作成し、firstName と lastName を空のままにすると、フルネームマッパーは LDAP の cn 値として "john123" を保存します。firstName および lastName に "John Doe" を入力すると、fullName マッパーは LDAP cn を "John Doe" の値に更新し、ユーザー名へのフォールバックが必要ありません。
- ハードコードされた属性マッパー
-
このマッパーは、LDAP にリンクされた各 Red Hat build of Keycloak ユーザーにハードコーディングされた属性値を追加します。また、このマッパーは
enabledまたはemailVerified ユーザープロパティーの値を強制的に実行することもできます。 - ロールマッパー
-
このマッパーは、LDAP から Red Hat build of Keycloak ロールマッピングにロールマッピングを設定します。単一のロールマッパーは LDAP ロール (通常は LDAP ツリーの特定ブランチからのグループ) を、指定されたクライアントのレルムロールまたはクライアントロールに対応するロールにマップできます。同じ LDAP プロバイダーに追加のロールマッパーを設定できます。たとえば、
ou=main,dc=example,dc=org下のグループからのロールマッピングをレルムロールマッピングにマッピングし、ou=finance,dc=example,dc=org下のグループから、クライアントfinanceのクライアントロールマッピングへマップするように指定できます。 - ハードコードされたロールマッパー
- このマッパーは、LDAP プロバイダーから各 Red Hat build of Keycloak ユーザーに指定された Red Hat build of Keycloak ロールを付与します。
- グループマッパー
- このマッパーは、LDAP ツリーのブランチから、Red Hat build of Keycloak 内のグループに LDAP グループをマッピングします。また、LDAP からのユーザーグループのマッピングを Red Hat build of Keycloak のユーザーグループのマッピングに伝播します。
- MSAD ユーザーアカウントマッパー
-
このマッパーは、Microsoft Active Directory (MSAD) に固有のものです。MSAD ユーザーアカウントの状態を、有効なアカウントや期限切れのパスワードなどの Red Hat build of Keycloak アカウントの状態に統合できます。このマッパーは
userAccountControlおよびpwdLastSetLDAP 属性を使用します。これは MSAD に固有で、LDAP 標準ではありません。たとえば、pwdLastSetの値が0の場合KRed Hat build of Keycloak ユーザーはパスワードを更新する必要があります。結果として、UPDATE_PASSWORD の必要なアクションがユーザーに追加されます。userAccountControlの値が514(無効なアカウント) の場合、Red Hat build of Keycloak は無効になります。 - 証明書マッパー
-
このマッパーは X.509 証明書をマッピングします。Red Hat build of Keycloak はこれを、X.509 認証および
Full certificate in PEM formatと組み合わせてアイデンティティソースとして使用します。このマッパーはUser Attribute Mapperと同様に機能しますが、Red Hat build of Keycloak は PEM または DER 形式の証明書を保存する LDAP 属性をフィルタリングできます。このマッパーを使用して、Always Read Value From LDAPを有効にします。
ユーザー名、名、姓、メールなどの基本的な Red Hat build of Keycloak ユーザー属性を、対応する LDAP 属性にマッピングするユーザー属性マッパー。これらを拡張し、独自の追加属性マッピングを提供できます。管理コンソールは、対応するマッパーの設定に役立つツールチップを提供します。
4.3.8. パスワードのハッシュ
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 サーバーのドキュメントを参照してください。
ldapsearch を使用して変更したディレクトリーエントリーを検査することで、ユーザーパスワードが正しくハッシュ化され、プレーンテキストとして保存されていることと、base64 が userPassword 属性値をデコードしていることを常に確認します。
4.3.9. トラブルシューティング
カテゴリー org.keycloak.storage.ldap では、ログレベルを TRACE に増やすと便利です。この設定により、多数のロギングメッセージは TRACE レベルの server.log ファイルに送信されます。これには、すべてのクエリーのログが LDAP サーバーとクエリーの送信に使用されたパラメーターが含まれます。ユーザーフォーラムまたは JIRA で LDAP の質問を作成する場合は、TRACE ロギングを有効にしてサーバーログを添付することを検討してください。大きすぎる場合は、操作中にログに追加されたメッセージを含む、サーバーログのスニペットだけを含めるのが良いでしょう。これにより、問題が発生します。
- LDAP プロバイダーを作成すると、次で始まるメッセージがサーバーログの INFO レベルに表示されます。
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 プロバイダーのプロパティー
Connection Pool Debug Levelの値をallの値に設定することを検討してください。これにより、LDAP 接続プールのロギングが含まれるサーバーログに多くの追加メッセージがサーバーログに追加されます。これは、接続プールまたはパフォーマンスに関連する問題を追跡するために使用できます。
接続プールの設定を変更した後に、Red Hat build of Keycloak サーバーを再起動して LDAP プロバイダー接続の再初期化を適用する必要がある場合があります。
サーバーの再起動後も接続プールに関するメッセージが表示されない場合は、LDAP サーバーで接続プールが機能していない可能性があります。
-
LDAP の問題をご報告いただく際には、お客様の環境で問題を引き起こしているターゲットデータに LDAP ツリーの一部を添付することを検討してください。たとえば、あるユーザーのログインに時間がかかる場合、さまざまな "グループ" エントリーの
member属性の数を示す LDAP エントリーを添付することを推奨します。このような場合、これらのグループエントリーが Red Hat build of Keycloak などのグループ LDAP マッパー (またはロール LDAP マッパー) にマップされているかどうかを追記すると役に立つ場合があります。
