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搜索（由 teamcity.users.login.filter LDAP 过滤器定义，其中用户输入的用户名通过 $login$ 或 $capturedLogin$ 子字符串在用户基准 LDAP 节点内（由 teamcity.users.base 定义）进行引用），

• 如果搜索成功，将使用在搜索过程中找到的 DN 和用户输入的密码执行身份验证（LDAP 绑定），

• 如果身份验证成功，将根据需要创建 TeamCity 用户，并进行用户登录。 TeamCity 用户的名称是从找到的 LDAP 条目的属性中检索的（属性名称通过 teamcity.users.username 属性定义）

当用户通过 LDAP 登录时，TeamCity 不会储存用户的密码。 在每个用户登录时，都会通过直接登录到 LDAP 进行身份验证，这一身份验证基于登录表单中输入的值进行凭据相关操作。

请注意，在某些配置中（例如，与 java.naming.security.authentication=simple ），登录信息将以未加密的形式发送到 LDAP 服务器。 为了保证连接的安全性，请参考 Sun documentation。 另一种选择是通过 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 到其他服务器去获取这些缺失的数据。 要禁用此行为，取消 java.naming.referral=ignore 行在 ldap-config.properties 文件中的注释：

常见配置

您需要配置 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 用户名。 支持以下版本控制系统类型： svn、 perforce、 jetbrains.git、 cvs、 tfs、 vss、 starteam。

示例属性可以通过在网页用户界面中为用户配置它们，然后通过 REST API 列出这些属性来查看。

在 TeamCity 中存在一个 实验性 功能，允许在用户同步时将用户配置文件属性映射到 LDAP 属性的格式化组合，而不是映射到特定属性。
要启用该映射，请在 ldap-config.properties 中添加 teamcity.users.properties.resolve=true。
然后，您可以在用户属性定义中以 %ldap.userEntry.<attribute>% 的形式使用 % 对 LDAP 属性的引用。

用户组成员资格

TeamCity可以根据LDAP提供的数据自动更新用户在组中的成员资格。

配置 Group 成员资格：

1. 在 TeamCity 中手动创建群组。

2. 在 <TeamCity 数据目录>/config/ldap-mapping.xml 文件中指定 LDAP 组到 TeamCity 组的映射。 以 ldap-mapping.xml.dist 文件 为例：TeamCity 用户组是由 Group Key 确定的，LDAP 组是由组 DN 指定的。

3. 在 ldap-config.properties 文件中设置所需的属性，位于 groups settings 部分：

   • 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 同步的 示例设置。

创建和删除用户

如果在映射的 LDAP 组中找到用户并且通过 teamcity.options.groups.synchronize 选项开启了组同步，TeamCity 可以在 TeamCity 中自动创建用户。

默认情况下，自动用户创建功能已关闭。 要启动它，请在 ldap-config.properties 文件中将 teamcity.options.createUsers 属性设置为 true。

如果在 LDAP 中找不到用户或者用户不属于映射到预定义的“All Users”组的 LDAP 组，TeamCity 可以自动删除 TeamCity 中的用户。 默认情况下，自动用户删除功能也是关闭的；设置 teamcity.options.deleteUsers 属性以开启它。

用户名迁移

现有用户的用户名可以在首次成功登录后进行更新。 例如，假设用户之前使用 'DOMAIN\user' 名称登录，因此字符串 DOMAIN\user 被储存在 TeamCity 作为用户名。 要同步 LDAP 的数据，用户可以使用以下选项将用户名更改为 'user'：

第一个属性允许您从输入登录中捕获用户名，并使用它进行用户认证（当域名 'DOMAIN' 在 LDAP 中未被存储时尤其有用）。 第二个属性 teamcity.users.login.filter 允许您通过指定搜索过滤器从 LDAP 提取用户名（使用此功能的其他必选属性： teamcity.users.base 和 teamcity.users.username）。 第三个属性让您能够在仅使用 'user' 登录时找到 DOMAIN\user 用户名，并将其替换为捕获的登录名或 LDAP 中的用户名。

请注意，如果这些属性中的任何一个未设置或无法应用，用户名将不会被更改（将使用输入的登录名）。

更多的配置示例可以在 这里 找到。

切换至 LDAP 认证

当您在已有用户的 TeamCity 服务器上添加 LDAP 验证模块时，用户仍然可以使用之前的验证模块凭证登录（除非您移除了该模块）。 在成功的 LDAP 登录后，LDAP 会按照 teamcity.users.username 属性的配置检索用户名，如果已经存在具有此类 TeamCity 用户名的用户，则用户以匹配的用户身份登录。 如果不存在现有用户，则会创建一个新用户，用户名从 LDAP 获取。

在 ldap-config.properties 文件中混淆凭据

java.naming.security.credentials 属性可以以明文或混淆形式存储密码。 在进行 LDAP 服务器身份验证时，TeamCity 需要原始密码值，因此应以可逆的形式存储密码。
您可以使用下面的 HTTP 请求获取混淆的值，然后将该属性设置为混淆的值。 当向 java.naming.security.credentials 属性添加混淆值时，需要包含以下请求的完整响应。 混乱的条目应该看起来像： java.naming.security.credentials=scrambled:1234567890abcdef。

为获取混淆的密码值，请以授予系统管理员角色的用户（即您可以在同样用来访问 TeamCity 的浏览器中直接打开 URL）执行以下 HTTP 请求：

GET {teamcity_url}/app/rest/debug/values/password/scrambled?value=<需要打乱的文本>

调试 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 实体的属性），并详细说明预期/实际行为。 包含数据的存档可以通过 这些方法之一 发送给我们。