LDAP 複数ドメインコントローラー認証（デプロイメントプラン）¶
デプロイメントプランでは、同じ LDAP ID ディレクトリに対して複数のドメインコントローラーアドレスを設定できます。ログイン時は設定順に接続し、ユーザーパスワードを送信する前に切り替え対象となるサービス障害が発生した場合は、次のアドレスを試行します。
この文書でいう「複数ドメインコントローラー」とは、アカウント、ディレクトリ構造、認証ルールを共有する複数のコントローラー（例：同一 AD ドメインのレプリカ）を指します。この機能は、複数の独立した AD ドメイン間のアカウントルーティングを提供せず、ドメインごとにパスワードを試してユーザーを探すこともありません。独立した ID ソースにカスタム認証が必要な場合は、LDAP カスタム認証と Func 属性の加工 を参照してください。
アップグレードと互換性¶
使用前に、デプロイされている Studio バックエンドのバージョンに LDAPClientSet.authMode と LDAPClientSet.server.hosts の設定機能が含まれていることを確認してください。ヘルプドキュメントや Func スクリプトを更新するだけでは、旧バージョンのバックエンドに機能は追加されません。
既存の単一アドレス構成では、設定を変更する必要はありません。authMode が未設定または builtin で、かつ server.hosts が未設定、null、[] の場合は、従来の単一アドレス認証経路が引き続き使用されます。新しく追加された認証の合計タイムアウトと外部関数の設定によって、この認証経路が変わることはありません。単なるアップグレードのために、元のアドレスだけを含む hosts リストを追加しないでください。空でないリストは、新しい認証経路を意図的に有効にしたことを意味します。
有効にする前に、以下を確認してください：
- すべての候補ドメインコントローラーが同じ
baseDN、サービスアカウント、ユーザー検索条件、TLS 設定、mappingを使用していること。また、同じユーザーのexterIdが各レプリカで一致していること。 - 候補のドメインコントローラーにはすべて Studio バックエンドコンテナからアクセスでき、CA ファイルがコンテナにマウントされ、証明書に接続先のドメイン名が含まれていること。
- ディレクトリで、検索結果のユーザー DN を使用した SIMPLE パスワード認証が許可され、LDAPS または StartTLS によってパスワードの転送が保護されていること。サービスアカウントのバインド方法とエンドユーザーのパスワード認証は別々のステップです。
- この機能に対応した公式のサービス起動方法を使用していること。新しい認証経路には、割り込み可能なネットワークと DNS の実行環境が必要です。カスタム起動方法で
gevent_runtimeまたはgevent_dnsの設定エラーが発生した場合は、起動環境を修正してください。
複数ドメインコントローラーの設定¶
アプリケーション設定ガイド に従い、Launcher の forethought-core 名前空間で Core 設定を変更します。以下は LDAPS の例です。ドメイン名、DN、証明書パス、プレースホルダーのパスワードは、実際の設定に置き換えてください。既存ユーザーの ID マッピングは維持してください。
LDAPClientSet:
enable: true
authMode: builtin
authTimeoutSeconds: 20
server:
# 空でない hosts は host を完全に置き換えます。失敗しても host にフォールバックしません。
hosts:
- "ldaps://ldap-a.example.com:636"
- "ldaps://ldap-b.example.com:636"
connect_timeout: 6
use_ssl: true
get_info: SCHEMA
tls:
validate: CERT_REQUIRED
ca_certs_file: "/config/ldap/ca.pem"
connection:
authentication: SIMPLE
client_strategy: SAFE_SYNC
receive_timeout: 5
startTls: false
baseDN: "dc=example,dc=com"
bindDN: "cn=studio-reader,ou=service,dc=example,dc=com"
bindPassword: "<サービスアカウントのパスワード>"
searchAttribute: "uid"
personObjectClass: "inetOrgPerson"
mapping:
exterId: uid
username: uid
email: mail
mobile: mobile
AD 環境では通常、実際のディレクトリに合わせて searchAttribute（例：sAMAccountName）と personObjectClass（例：person）を調整する必要があります。この例をそのまま適用して既存の mapping.exterId を上書きしないでください。
StartTLS を使用する場合は、候補アドレスを ldap://ドメイン名:389 に変更し、server.use_ssl: false と startTls: true を設定して、証明書の検証は維持してください。新しい認証経路では、TLS ハンドシェイクを完了してからサービスアカウントをバインドします。LDAPS と StartTLS を同時に有効にしないでください。
| 設定項目 | 説明 |
|---|---|
server.hosts |
最大 8 つのアドレスを入力順に試行し、同じ文字列は重複排除されます。ドメイン名、ldap://ドメイン名:ポート、ldaps://ドメイン名:ポート に対応します。アカウントのパスワード、パス、クエリパラメータ、フラグメントは含みません。ポートの指定が必要な場合は、アドレスに直接記述してください。 |
server.host |
hosts が空の場合にのみ単一アドレスとして使用されます。空でない hosts がこの値と連結されることはありません。 |
authTimeoutSeconds |
新しい認証経路における認証と属性準備の合計タイムアウトです。整数で 1〜60 秒、デフォルトは 20 秒です。すべての候補アドレスで共有され、各アドレスがそれぞれ 20 秒ずつ持つわけではありません。後続のアカウントトランザクションとログイン認可コードの処理は含みません。 |
server.connect_timeout |
1 回の接続タイムアウトです。デフォルトは 6 秒で、残りの合計タイムアウトの制約を受けます。 |
connection.receive_timeout |
受信タイムアウトです。デフォルトは 5 秒で、残りの合計タイムアウトの制約を受けます。 |
connection.client_strategy |
新しい認証経路では SAFE_SYNC のみがサポートされます。未設定の場合はこの値が使用されます。lazy: true は設定しないでください。auto_bind は設定せず、認証フローが接続、TLS、バインドの順序を制御することを推奨します。 |
| その他の LDAP 設定 | 既存の server.tls、connection、startTls、baseDN、bindDN、bindPassword、検索条件、mapping を引き続き共有します。コントローラーごとに設定を複製する必要はありません。 |
環境変数でリストを設定する場合は、JSON 配列の文字列を使用します。例：
STUDIO__LDAPClientSet__server__hosts='["ldaps://ldap-a.example.com:636","ldaps://ldap-b.example.com:636"]'
設定を変更したら、Launcher の設定変更後に関連サービスを自動再起動にチェックを入れて確定し、ログイン要求を処理するすべてのレプリカが同じ設定を使用するようにしてください。
どのような障害でドメインコントローラーを切り替えるか¶
各認証はリストの最初のアドレスから開始されます。切り替えは、サービスが利用できない場合に対処するためのものであり、認証拒否を回避するためのものではありません。
| 状況 | 次のアドレスに進むか |
|---|---|
| ユーザーパスワードを送信する前に、DNS、接続、ネットワーク通信の障害が発生した | はい。ただし、証明書検証の失敗を除き、合計タイムアウトが残っている場合に限ります |
| サービスアカウントのバインドまたは検索フェーズで LDAP busy/unavailable（51/52）が返された | はい。ただし、合計タイムアウトが残っている場合に限ります |
| サービスアカウントのパスワード誤り、権限不足、検索設定またはスキーマエラー | いいえ。先に設定を修正してください |
| CA が信頼されていない、証明書とドメイン名が一致しない | いいえ。先に証明書またはアドレスを修正してください |
| ユーザーが見つからない、または検索で複数のユーザーが見つかった | いいえ。アカウント同期と一意の検索条件を確認してください |
| ユーザーパスワードが誤り | いいえ。他のコントローラーにパスワードを再送信しません |
| ユーザーパスワードを送信した後にタイムアウト、切断、サービス利用不可が発生した | いいえ。結果が不確定になる可能性があるため、パスワードを自動的に再送信しません |
| 合計タイムアウトに達した | いいえ。この認証は失敗します |
したがって、あるドメインコントローラーにユーザーが存在しない場合でも、他の独立ディレクトリに「同名のアカウント」を探しに行くことはありません。まず、レプリカの同期と ID の整合性を確認してください。
ログインと受け入れ確認¶
ユーザーは引き続きデプロイメントプランのログインページで LDAP ログイン を選択し、既存のユーザー名とパスワードを入力します。ドメインコントローラーを選択する必要はありません。ワークスペースの権限は、引き続き既存の SSO マッピングルール を使用します。
既存ユーザーに開放する前に、専用のテストアカウントで検証することをお勧めします：
- すべてのアドレスが正常な場合にログインが成功し、既存ユーザーが従来どおり元のアカウントにログインでき、ワークスペースとロールが期待どおりになることを確認する。
- 管理されたテストで最初のアドレスへの接続不可をシミュレートし、2 番目のアドレスでログインできること、および全体の所要時間が合計タイムアウトの制約を受けることを確認する。
- 誤ったパスワードを入力し、複数のコントローラーを試してもパスワードの再試行回数が増えないことを確認する。あわせて、ディレクトリ側のアカウントロックアウトポリシーを確認する。
- 証明書エラー、サービスアカウントエラー、ユーザーが見つからない場合のいずれも失敗し、切り替えによってエラーを回避できないことを検証する。
- 2 つのコントローラーで、同じユーザーの ID フィールドと認可に必要なグループ属性をそれぞれ照合し、一致することを確認する。
mapping.exterId は LDAP ユーザーの安定した ID に対応します。マッピングのフィールドまたはフィールド値を変更すると、新しいアカウントが作成される可能性があります。同じメールアドレスやユーザー名で ID が自動的に統合されることを当てにしないでください。
ロールバック¶
アップグレード前の設定を保持してください。従来の単一アドレス認証に戻す必要がある場合は、authMode を builtin に設定し、server.hosts を空にするか削除し、元の server.host と既存の接続、TLS、マッピング設定を復元してから、関連サービスを再起動してください。host だけを変更しても、空でない hosts が残っている場合は有効になりません。
ロールバックの設定によって、すでに作成されたアカウントが自動的に統合されたり、変更されたロールマッピングが復元されたりすることはありません。属性の加工や ID マッピングも同時に変更した場合は、まずアカウントと認可への影響を確認してください。