LDAP 統合

ldap-config.properties 構成

LDAP 統合設定は、サーバー上の <TeamCity データディレクトリ>/config/ldap-config.properties ファイルで構成されます。

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

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

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

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

ldap-config.properties ファイルの必須プロパティは java.naming.provider.url で、サーバーとルート DN を構成します。 このプロパティには、以降の 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 接続設定を微調整する必要がある場合は、 ldap-config.properties ファイルに java.naming オプションを追加できます。これらは基盤となる 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 タイプ>: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 に追加します。
その後、ユーザープロパティ定義で、LDAP 属性への % 参照を %ldap.userEntry.<attribute>% の形式で使用できます。

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

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

グループメンバーシップを設定するには：

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

2. <TeamCity データディレクトリ>/config/ldap-mapping.xml ファイルで、LDAP グループから TeamCity グループへのマッピングを指定します。 例として ldap-mapping.xml. dist ファイル を使用します: 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 設定と一致していることを確認してください

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

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

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

ユーザーの作成と削除

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

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

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

ユーザー名の移行

既存のユーザーのユーザー名は、最初のログイン成功時に更新できます。 たとえば、ユーザーが以前に 'DOMAIN\user' というお名前でログインしていたため、文字列 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 データディレクトリ>/config/ldap-config.properties および ldap-mapping.xml ファイル、 ldap-config.properties ではパスワードをマスク) と、ログイン/同期シーケンス全体を完全に含むデバッグ LDAP ログ (すべての teamcity-ldap.log* ファイルを含む) を必ず含めてください。 LDAP の関連する構造（関連する LDAP エンティティの属性に注意）と、予想される / 実際の動作の詳細を必ず説明してください。 データを含むアーカイブは、 これらの方法のいずれかを介して送信できます。