LDAP の統合

ldap-config.properties の構成

LDAP 統合設定は、サーバー上の <TeamCity Data Directory>/config/ldap-config.properties ファイルで構成されます。

<TeamCity Data Directory>/config/ldap-config.properties.dist ファイルをコピーして <TeamCity Data Directory>/config/ldap-config.properties に名前を変更して、ファイルを作成します。ファイル内のコメントに従って、必要に応じてデフォルト設定を編集します。

このファイルは標準の Java プロパティファイル構文を使用しているため、ファイル内のすべての値を適切にエスケープ(英語)する必要があります。例: 次の java.naming.security.principal=DOMAIN\user パラメーターは java.naming.security.principal=DOMAIN\\user としてエスケープする必要があります。

ファイルは変更時に再読み込みされます。変更を適用するためにサーバーを再起動する必要はありません。

以前のバージョンのファイルをバックアップすることを強くお勧めします。LDAP 統合を誤って構成すると、TeamCity にログインできなくなる可能性があります。すでにログインしているユーザーは、ログイン時にのみ認証されるため、変更された LDAP 統合設定の影響を受けません。

ldap-config.properties ファイルの必須プロパティは、サーバーとルート DN を構成する java.naming.provider.url です。このプロパティには、次の LDAP クエリで使用される LDAP サーバーノードへの URL が格納されます。例: ldaps://dc.example.com:636/CN=Users,DC=Example,DC=Com プロパティの値は、必要に応じて URL エスケープを使用する必要があることに注意してください。たとえば、スペース文字が必要な場合は、%20 を使用します。

ユーザーログインの設定

一般的なログインシーケンスは次のとおりです。

• ユーザーがログインフォームに入力したユーザー名に基づいて、LDAP 検索が実行されます（ユーザーが入力したユーザー名は、ユーザーベース LDAP ノード内の $login$ または $capturedLogin$ 部分文字列を介して参照される teamcity.users.login.filter LDAP フィルターによって定義されます（teamcity.users.base によって定義されます）

• 検索が成功すると、検索中に見つかった DN とユーザーが入力したパスワードを使用して認証（LDAP バインド）が実行されます。

• 認証が成功した場合、必要に応じて TeamCity ユーザーが作成され、ユーザーがログインします。TeamCity ユーザーの名前は、見つかった LDAP エントリの属性から取得されます (属性名は teamcity.users.username プロパティを介して定義されます)

ユーザーが LDAP 経由でログインすると、TeamCity はユーザーのパスワードを保存しません。ユーザーがログインするたびに、ログインフォームに入力された値に基づく資格情報を使用して LDAP に直接ログインすることにより、認証が実行されます。

特定の構成（java.naming.security.authentication=simple など）では、ログイン情報は暗号化されていない形式で LDAP サーバーに送信されることに注意してください。接続の固定については、Sun のドキュメント(英語)を参照してください。別のオプションは、LDAPS プロトコルを介して通信を構成することです。

詳細な構成

LDAP 接続設定を微調整する必要がある場合は、java.naming オプションを ldap-config.properties ファイルに追加できます。これらは基礎となる Java ライブラリに渡されます。デフォルトのオプションは、java.naming.factory.initial=com.sun.jndi.ldap.LdapCtxFactory を使用して取得されます。プロパティの名前と値の詳細については、Java のドキュメントページ(英語)を参照してください。

LDAP エクスプローラーを使用して、LDAP ディレクトリをブラウズし、設定（たとえば、http://www.jxplorer.org/(英語) または http://www.ldapbrowser.com/softerra-ldap-browser.htm(英語)）を確認できます。

次のパターンを使用してフェールオーバーサーバーを指定する機能があります。

サーバーは、いずれかが応答するまで接続されます。アドレスリストが処理される特定の順序はありません。

紹介の追跡

LDAP クライアントが、必要なすべてのデータを持っていない LDAP サーバーからの情報を要求すると、サーバーは他のサーバーに参照 URL を返して、この不足しているデータを取得することができます。この動作を無効にするには、ldap-config.properties ファイルの java.naming.referral=ignore 行のコメントを外します。

共通の構成

同期を機能させるには、LDAP 認証を構成する必要があります。

デフォルトでは、同期はオフになっています。オンにするには、ldap-config.properties ファイルに次のオプションを追加します。

また、次の必須プロパティを指定する必要があります。

• java.naming.security.principal および java.naming.security.credentials — これらは TeamCity が LDAP に接続してデータを取得するために使用するユーザー資格情報を指定します。

• teamcity.users.base および teamcity.users.filter - これらはユーザーを検索するための設定を指定します

• teamcity.users.username - TeamCity ユーザーのユーザー名を含む LDAP 属性の名前。この設定に基づいて、LDAP エントリは TeamCity ユーザーにマップされます。

ユーザーの同期を有効にしてもユーザーは作成または削除されません。関連する構成については、ユーザーの作成と削除セクションを確認してください。

ユーザープロファイルデータ

同期が適切に構成されている場合、TeamCity は LDAP からユーザー関連情報（メール、フルネーム、任意のカスタムプロパティ）を取得し、TeamCity ユーザーの詳細として保存できます。LDAP で更新された場合、データは TeamCity のユーザーのプロファイルで更新されます。TeamCity のユーザーのプロファイルで変更された場合、変更されたフィールドのデータは LDAP から更新されなくなります。すべてのユーザーフィールド同期プロパティには、情報を取得する LDAP フィールドの名前が格納されます。

ユーザーのプロファイルの同期は、ユーザーの作成時に実行され、すべてのユーザーに対して定期的に実行されます。

サポートされているユーザー設定のリスト:

• teamcity.users.username

• teamcity.users.property.displayName

• teamcity.users.property.email

• teamcity.users.property.plugin:vcs:<VCS type>:anyVcsRoot — すべての <VCS タイプ> ルートの VCS ユーザー名。次の VCS タイプがサポートされています: svn、perforce、jetbrains.git、cvs、tfs、vss、starteam

プロパティの例は、Web UI でユーザー用に設定し、REST API を介してプロパティを一覧表示することで確認できます。

TeamCity のユーザープロファイルプロパティを、ユーザー同期の特定のプロパティではなく、フォーマットされた LDAP プロパティの組み合わせにマッピングできる実験的な機能があります。
マッピングを有効にするには、teamcity.users.properties.resolve=true を ldap-config.properties に追加します。
次に、ユーザープロパティ定義で、% -references を %ldap.userEntry.<attribute>% の形式で LDAP 属性に使用できます。

ユーザーグループのメンバーシップ

TeamCity は、LDAP が提供するデータに基づいて、グループのユーザーメンバーシップを自動的に更新できます。

グループメンバーシップを構成するには:

1. TeamCity でグループを手動で作成します。

2. <TeamCity Data Directory>/config/ldap-mapping.xml ファイルで、LDAP グループの TeamCity グループへのマッピングを指定します。ldap-mapping.xml を使用します。例として dist file :TeamCity ユーザーグループはグループキーによって決定され、LDAP グループはグループ DN によって指定されます。

3. ldap-config.properties ファイルのグループ設定セクションで必要なプロパティを設定します。

   • teamcity.options.groups.synchronize — ユーザーグループのメンバーシップの同期を有効にします

   • teamcity.groups.base および teamcity.groups.filter — LDAP ベースノードを指定し、LDAP 内のグループを検索するためのフィルターを指定します (ldap-mapping.xml ファイルで設定されたものは、これらの設定で見つかったグループのサブセットである必要があります)

   • teamcity.groups.property.member は、グループのメンバーを保持する LDAP 属性を指定します。LDAP グループのすべてのメンバーは、指定された属性にリストされている必要があります。

TeamCity は teamcity.users.base および teamcity.users.filter 設定に一致するユーザーでのみ動作するため、これらのプロパティで見つかったユーザーのみがグループメンバーシップの同期プロセス中に処理されることに注意してください。

同期の実行ごとに、TeamCity はマッピングで構成されたグループ内のユーザーのメンバーシップを更新します。
デフォルトでは、TeamCity はグループに直接属するユーザーのみのメンバーシップを同期します。

ネストされた LDAP グループを TeamCity にマップするには:

• ldap-config.properties ファイルで teamcity.groups.retrieveUsersFromNestedGroups=true を指定し、すべてのグループ階層が teamcity.groups.base/teamcity.groups.filter 設定と一致していることを確認してください

• または、TeamCity グループの LDAP グループ構造を、グループの包含とともにコピーします。次に、TeamCity グループと対応する LDAP グループ間のマッピングを構成します。

マッピングで構成されている LDAP グループまたは TeamCity グループのいずれかが見つからない場合は、エラーが報告されます。サーバー設定の管理 | LDAP 同期セクションで、前回の同期実行中に見つかったエラーを確認できます。

Active Directory 同期の設定例も参照してください。

ユーザーの作成と削除

TeamCity は、マッピングされた LDAP グループのいずれかでユーザーが見つかり、teamcity.options.groups.synchronize オプションを介してグループ同期がオンになっている場合、TeamCity でユーザーを自動的に作成できます。

デフォルトでは、自動ユーザー作成はオフになっています。オンにするには、ldap-config.properties ファイルで teamcity.options.createUsers プロパティを true に設定します。

TeamCity は、LDAP で見つからないか、事前定義された「すべてのユーザー」グループにマップされている LDAP グループに属していない場合、TeamCity のユーザーを自動的に削除できます。デフォルトでは、自動ユーザー削除もオフになっています。teamcity.options.deleteUsers プロパティを設定してオンにします。

ユーザー名の移行

既存のユーザーのユーザー名は、最初のログイン成功時に更新できます。たとえば、ユーザーが以前に「ドメイン \ ユーザー」名を使用してログインしたため、文字列 DOMAIN\user がユーザー名として TeamCity に保存されたとします。データを LDAP と同期するために、ユーザーは次のオプションを使用してユーザー名を「user」に変更できます。

最初のプロパティを使用すると、入力ログインからユーザー名を取得し、それを使用してユーザーを認証できます（ドメイン「ドメイン」が LDAP のどこにも保存されていない場合に特に役立ちます）。2 番目のプロパティ teamcity.users.login.filter では、検索フィルターを指定してこのユーザーを見つけることにより、LDAP からユーザー名を取得できます（この機能を使用する他の必須プロパティ: teamcity.users.base および teamcity.users.username）。3 番目のプロパティを使用すると、「user」だけでログインしたときに DOMAIN\user ユーザー名を見つけ、キャプチャーしたログインまたは LDAP のユーザー名に置き換えることができます。

これらのプロパティのいずれかが設定されていないか適用できない場合、ユーザー名は変更されないことに注意してください（入力ログイン名が使用されます）。

さらなる設定例については、こちらを参照してください。

LDAP 認証への切り替え

すでにユーザーがいる TeamCity サーバーに LDAP 認証モジュールを追加する場合、ユーザーは以前の認証モジュールの資格情報を使用してログインできます（モジュールを削除しない限り）。LDAP ログインが成功すると、LDAP は teamcity.users.username プロパティで設定されたユーザー名を取得し、そのような TeamCity ユーザー名を持つユーザーがすでに存在する場合、ユーザーは一致するユーザーとしてログインします。既存のユーザーがいない場合は、LDAP から取得したユーザー名で新しいユーザーが作成されます。

ldap-config.properties ファイル内の資格情報のスクランブル

java.naming.security.credentials プロパティは、パスワードをプレーンテキストまたはスクランブル / 暗号化された形式で保存できます。TeamCity は LDAP サーバーで認証する際に生のパスワード値を必要とするため、java.naming.security.credentials がスクランブルされた値を保存した場合でも、TeamCity は元の値を復元できるはずです。

これを確実にするために、TeamCity も使用して値を処理する必要があります。TeamCity は、内部メカニズムを使用して機密データをスクランブルするか、（設定されている場合）カスタム暗号化キーを使用して暗号化します。どちらの場合も、POST REST API リクエストを /app/rest/debug/values/password/scrambled?value=<text to scramble> エンドポイントに送信することで、安全な値を取得できます。

その後、サーバー応答を必須プロパティ java.naming.security.credentials=1234567890abcdef に割り当てることができます。

LDAP 統合のデバッグ

内部 LDAP ログは、サーバーログの logs/teamcity-ldap.log* ファイルに保存されます。LDAP 構成で問題が発生した場合は、ログを調べることをお勧めします。ログ内のメッセージから問題を特定できる場合が多いためです。LDAP ログインおよび同期プロセスの詳細なログを取得するには、「debug-ldap」ログプリセットを使用します。

LDAP の問題を報告する場合は、LDAP 設定（<TeamCity Data Directory>/config/ldap-config.properties および ldap-mapping.xml ファイル、パスワードは ldap-config.properties でマスクされています）を含め、ログイン / 同期シーケンスを完全にカバーする LDAP ログをデバッグしてください（すべての teamcity-ldap.log* ファイルを含めてください）。LDAP の関連する構造（関連する LDAP エンティティの属性に注意）と、予想される / 実際の動作の詳細を必ず説明してください。データを含むアーカイブは、これらの方法のいずれかを介して送信できます。