必威国际有限公司詹金斯LDAP插件

注:这个插件是Jenkins核心的一部分，直到1.468。必威国际有限公司在那之后，它被分割成一个独立的可更新插件。然而，出于向后兼容的目的，后续核心版本仍然将其捆绑在一起。如果你根本不使用这个插件，你可以简单地禁用它。

描述

这个插件提供了另一种使用LDAP认证用户的方法。它可以用于像Active Directory或OpenLDAP等LDAP服务器。支持的配置可以在这些行下面找到。

兼容性的笔记

各种LDAP服务器使用不同的操作属性来决定和公开概念的配置，这些概念包括禁用帐户、锁定帐户和指定帐户有效的时间间隔。在执行用户身份验证时，这些策略通常由LDAP服务器本身执行。必威国际有限公司Jenkins提供了不直接执行LDAP身份验证的替代身份验证机制(如API令牌和SSH密钥);相反，Jenkin必威国际有限公司s会检查用户的详细信息属性，以确定用户是启用、锁定还是过期。这些用户属性由slapo-ppolicy(5)从OpenLDAP，Active Directory应用程序模式（ADAM）、classic Active Directory和eDirectory LDAP。这些功能的支持完全取决于LDAP服务器实现是否正确公开这些操作属性，而这些操作属性取决于所使用的LDAP服务器的确切版本和分布。作为操作属性，LDAP服务器实现并不总是公开这些操作属性向客户发送通知的方式与内部使用的方式相同。

管理禁用帐户

被管理员禁用的帐户通常会公开一个操作属性来表明这一点。支持以下属性:

• pwdAccountLockedTime的价值000001010000 z:使用密码策略覆盖的常见LDAP属性;
• msDS-UserAccountDisabled的价值真正的:现代活动目录属性;
• userAccountControl(UAC)或msDS-User-Account-Control-Computed位标志为ADS_UF_ACCOUNTDISABLE(0 x2);和
• loginDisabled的价值真正的: eDirectory属性。

过期的账户

帐户可以有一个特定的开始或结束时间与帐户可以验证相关联。该功能允许管理员自动启动和终止帐户日期，而不必手动禁用或删除帐户。以下属性支持此功能:

• pwdStartTime未来的时间戳，或者pwdEndTime过去的时间戳（LDAP密码策略）；
• 帐户到期过去的时间戳(Active Directory);和
• loginExpirationTime过去时间戳(eDirectory)。

注意，虽然这些时间戳都包含时区信息，但它们是与Jenkins系统时钟进行比较的。必威国际有限公司

密码过期

Active Directory提供一些属性来指示帐户已过期的凭据。布尔属性msDS UserPasswordExpired（ADAM）或UAC标志ADS_UF_PASSWORD_EXPIRED检查。

锁定帐户

帐户可以被入侵者检测系统锁定。以下属性支持此功能:

• pwdLockout的价值真正的: LDAP密码策略;
• UAC国旗ADS_UF_LOCK_OUT(0x10)存在(Active Directory);和
• lockedByIntruder的价值真正的(eDirectory)。

配置

为安全领域选择LDAP。您很可能需要配置一些Advanced选项。每个选项都有在线帮助。

服务器

指定LDAP服务器主机名的名称(例如ldap.acme.org)．

如果LDAP服务器使用的端口不是389（这是LDAP的标准），您还可以在此处附加端口号，如ldap.acme.org: 1389．

要通过SSL连接到LDAP (AKA LDAPS)，可以使用ldap: / /协议,如ldap: / / ldap.acme.org或ldap: / / ldap.acme.org: 1636(如果端口不是默认的636)．

从1.6版开始，您可以指定一个由空格分隔的服务器列表，以便在第一个服务器不可用时提供回退，例如。ldap1.acme.org ldap2.acme.org: 1389或ldaps://ldap1.acme.org:1636 ldap1.acme.org:1389 ldap://ldap2.acme.org ldap3.acme.org

测试LDAP设置

此按钮将允许您检查已定义的完整LDAP配置设置（与仅验证配置子集的字段验证相比）

点击此按钮将显示一个模态对话框，提示您提供用户名和密码:

在保存新的/修改的安全配置之前，您应该执行一些测试:

• 输入您自己的用户名和密码，以验证您仍然能够登录后应用安全设置=>你不想把自己关在外面
• 理想情况下，让几个其他用户尝试他们的用户名和密码，以确保其他用户可以登录。如果您不能让其他用户访问您的计算机，您至少可以验证Jenkins可以通过使用他们的用户名和空密码=>来解析他们的帐户必威国际有限公司您不想将合法用户锁定在外
• 在大多数情况下，您将使用LDAP组，因此请确保通过使用至少一个组的成员用户帐户进行测试来验证反向组查找（不要忘记执行查找时使用的空密码技巧）。如果Jenkins实例中存在重要组，请尝试为每个重要组使用至少一个用户=>以确保组查找功能正确。必威国际有限公司

⚠️请注意很可能现有安装在组解析方面存在细微的问题，建议您在将LDAP插件升级到1.15后使用新的按钮功能验证组解析，因为它很可能会发现您不知道的问题！

根专有名称

为了验证用户身份并确定赋予该用户的角色，Jenkins执行多个LDAP查询。必威国际有限公司

因为LDAP数据库在概念上是一棵大树，而且搜索是递归执行的，所以从理论上讲，如果我们可以从子节点(而不是根节点)开始搜索，您将获得更好的性能，因为它缩小了搜索的范围。

此字段指定此类子树的DN。

但是在实践中，LDAP服务器在数据上维护一个广泛的索引，所以很少需要指定这个字段—您应该让Jenkins通过与LDAP对话来解决这个问题。必威国际有限公司

如果您指定了这个值，该字段通常看起来像这样dc=acme，dc=org

用户搜索基地

Jenkins在LDAP上进行的搜索之一必威国际有限公司是根据用户名定位用户记录。

如果您在这里指定一个相对DN（从根DN开始），Jenkins将进一步缩小到子树的搜索范围。必威国际有限公司

但是在实践中，LDAP服务器在数据上维护广泛的索引，因此很少需要指定这个字段。

如果您指定了这个值，该字段通常看起来像这样ou =人

用户搜索过滤器

Jenkins在LDAP上进行的搜索之一必威国际有限公司是根据用户名定位用户记录。

该字段确定要运行的查询以标识用户记录。

查询几乎总是uid = {0}按照RFC 2798中定义的，所以在大多数情况下，应该让这个字段为空，让这个默认值生效。

如果您的LDAP服务器没有液体或者不用有意义的液体值,试一试邮件= {0}，用户可以通过电子邮件地址登录。

如果指定了不同的查询，则使用标记令牌指定LDAP查询字符串{0}，将被用户输入的用户名字符串替换。

组搜索库

Jenkins在LDAP上所做的搜索之一必威国际有限公司是查找用户的组列表。

此字段确定要运行的查询，以标识包含组的组织单元。

查询几乎总是ou =组所以先尝试一下，尽管这个字段可能为空，以便从根DN进行搜索。

如果登录尝试导致“超过管理限制”或类似的错误，请尝试使此设置尽可能针对您的LDAP结构，以减少查询的范围。

如果错误持续存在，则可能需要将Group成员筛选器从默认的（|（member={0}）（uniqueMember={0}）（memberUid={1}））更改为仅查询LDAP中用于组成员的字段，例如:(会员= {0})．

您将需要登录和注销，以验证您的组成员身份是否保留了经过修改的组成员身份筛选器。

组搜索筛选器

当Jenk必威国际有限公司ins被要求确定一个命名组是否存在时，它使用默认过滤器:
(& (cn={0}) (| (objectclass=groupOfNames) (objectclass=groupOfUniqueNames) (objectclass=posixGroup))))

以确定是否存在具有指定名称的组({0}被要搜索的名称替换。)

如果您知道LDAP服务器只将组信息存储在一个特定的对象类中，那么您可以通过将筛选器限制为所需的对象类来提高组搜索性能。

注意:如果您正在使用LDAP安全域连接到活动目录(而不是使用活动目录插件的安全域)，那么您需要将此筛选器更改为:
(& (cn={0}) (objectclass=group)))

注意:如果您将此设置为空，将使用默认的搜索过滤器。

组成员

当Jenk必威国际有限公司ins解析用户时，解析过程的下一步是确定用户所属的LDAP组。

有一个扩展点，用于提供解析用户所属LDAP组的策略。LDAP插件中提供了两种实现：

• 搜索包含用户的组(默认)
• 解析组列表的用户属性

搜索包含用户的组

组成员资格筛选器字段控制用于确定组成员资格的搜索筛选器。

如果留空，将使用默认筛选器。默认筛选器为：（|（member={0}）（uniqueMember={0}）（memberUid={1}））．不管默认值是什么，将这个过滤器设置为非空白值将决定使用的过滤器。

通常情况下，保持该字段不变是安全的，但对于大型LDAP服务器，当您试图登录时，会定期看到“OperationNotSupportedException - Function Not Implemented”、“Administrative Limit Exceeded”或类似的消息，那么，这将表明您应该为您的LDAP服务器更改为更优的筛选器，即只查询所需字段的筛选器，例如:(会员= {0})

LDAP服务器可以使用查询提示来优化搜索。例如:

• 如果您感兴趣的所有组都在一个特定的子树中，那么将子树信息添加到筛选器中应该会提高性能。

• 如果Active Directory的查询优化器知道对象类别是group，那么它可以进行显著的优化:(& (objectCategory =集团)(会员= {0}))如果在链扩展中使用Active Directory的匹配规则，这可能是相关的，例如。(& (objectCategory =集团)(成员:1.2.840.113556.1.4.1941:= {0}))

注:在这个领域有两个可用的替代:
{0}—用户的完全限定DN
{1.} -用户的用户名部分

解析组列表的用户属性

一些LDAP服务器可以提供memberOf属性在用户记录内:

• 活动目录
• OpenLDAP的覆盖件活动（未测试，并且由于memberof是OpenLDAP中的一个操作属性，必须显式请求它，因此可能有效，也可能无效）
• （如果您知道其他人，请在此提供详细信息）

此属性可用于简化组搜索并立即返回组成员，而不需要进行第二个LDAP查询。但是请注意，这可能只会导致直接组成员的支持。

这个组成员属性字段控制用于确定用户所属组的属性名称。

管理员DN和管理员密码

如果您的LDAP服务器不支持匿名绑定(IOW，如果您的LDAP服务器甚至不允许不进行身份验证的查询)，那么Jenkins必须首先根据LDAP服务器对自己进行身份验证，Jenkins通过发送“manager”DN和密码来实现这一点。必威国际有限公司

DN通常是这样的CN = MyUser, CN =用户,DC = mydomain, DC = com尽管令牌的确切顺序取决于LDAP服务器配置。

它可以是任何有效的DN，只要LDAP允许该用户查询数据。

当您从Unix机器连接到Active Directory时，此配置也很有用，因为AD默认不允许匿名绑定。但是如果您不能弄清楚这一点，您也可以更改AD设置以允许匿名绑定。

禁用LDAP邮件解析器

控制是否使用LDAP来尝试和解析用户的电子邮件地址。

启用缓存

一些LDAP服务器可能很慢，或者速率限制了客户端请求。

在这种情况下，启用缓存可能会提高Jenkins的性能，但存在从LDAP传播用户更改的延迟和Jenkins控制器上内存必威国际有限公司使用量增加的风险。

注意:默认配置是关闭缓存。

环境属性

从LDAP插件的1.7开始，您现在可以指定额外的Environment属性来提供支持Java LDAP客户端API。看到甲骨文的文档有关哪些属性可用以及它们提供哪些功能的详细信息。至少，您应该强烈考虑提供以下内容

故障排除

以下Groovy脚本当试图确定是否正确配置了组搜索时，可以是有用的:

一串[]姓名=["组名称","用户名","不存在的名称"]；对于(name in names) {println("检查名称的"+的名字+"“…")试一试{println ("它是一个用户:"+必威国际有限公司．实例．securityRealm．loadUserByUsername(名称))println ("组织/部门:"+必威国际有限公司．实例．securityRealm．loadUserByUsername(名字)．getAuthorities ())}抓(异常e) {试一试{println ("它是一个团体:"+必威国际有限公司．实例．securityRealm．loadGroupByGroupname（name））println("")继续}抓(异常e1）{println("它不是一个群体，原因是:"+e1．getMessage ())} println ("它不是用户，原因:"+E．getMessage ())} println (""）;}

• 如果登录尝试导致“OperationNotSupportedException - Function Not Implemented”，“Administrative Limit Exceeded”或类似的错误，确定用户组成员的LDAP查询可能会触发此错误。首先尝试为您的LDAP结构尽可能具体地设置“Group search base”设置，以减少查询的范围。如果错误持续存在，则可能需要自定义组搜索筛选器．将筛选器更改为仅查询LDAP中用于组成员关系的字段，例如groupSearchFilter = "(={0})”;(然后重启Jenkins)。必威国际有限公司
• LDAP组在Jenkins中以ROLE_Uppercasedgrou必威国际有限公司pname的格式可用，因此开发者LDAP组将是Jenkins中的ROLE_开发者，但由于1.404，它们可以按原样使用：通过检查，没有前缀或大写禁用角色的向后兼容性．
• 如果你正在使用这个插件而不是活动目录的插件要连接到Active Directory，您需要将“组搜索筛选器”更改为:(& (cn={0}) (objectclass=group)))并将组成员筛选器更改为:(会员= {0})．如果你想要AD返回嵌套的组成员，那么将组成员筛选器更改为:(成员:1.2.840.113556.1.4.1941:= {0})

性能调整

以下是帮助提高性能的清单:

• 确保您使用的是LDAP插件的最新版本
• 确保已启用缓存。首先将缓存大小设置为略大于预期的最大并发用户数，然后将TTL设置为您可以接受的最长时间间隔…（即，在密码更改开始前多长时间…，在大多数情况下，5或10分钟是一个好的TTL）

这两个更改将立即显著提高性能（即使TTL为30秒，只要缓存大小大于最大预期并发用户数……但TTL越长越好）

• 接下来是确保你得到了正确的最具体的信息用户搜索基地和组搜索基地为LDAP树定义。做对了有两个副作用…你会得到更快的查询结果;您的LDAP服务器管理员将感谢您为他们的服务器减少了大量的负载。
• 最后，您应该确保已经为用户搜索筛选器和组搜索筛选器．．．用户一个通常是好的，因为是…默认情况下，第一组是典型查询的组合。通过从默认状态切换，可以获得显著的性能改进或过滤器(& (cn={0}) (| (objectclass=groupOfNames) (objectclass=groupOfUniqueNames) (objectclass=posixGroup))))到正确的LDAP树查询，即它将是(& (cn = {0}) (objectclass = groupOfNames)),(& (cn = {0}) (objectclass = groupOfUniqueNames)))或(& (cn = {0}) (objectclass = posixGroup))．(．..和if it is not one of them then your LDAP server is most likely Active Directory and Kohsuke makes me ask why you are using the LDAP plugin and not the Active Directory plugin in that case! Note that必威国际有限公司詹金斯- 16429可能是一个支持LDAP插件而不是Active Directory插件的好理由，但如果在阅读本文时这个问题已经解决，那么就没有理由选择LDAP插件而不是Active Directory插件了。

提示和技巧

如果您正在使用LDAP插件连接到活动目录，您可能应该阅读这一页广告的语法笔记．特别注意注释10和19。下面的设置被报告与Active Directory和嵌套组一起工作，尽管它们应该带有一个警告，即它们可能会影响登录性能，而且它们还没有经过完整性测试:

• 用户搜索筛选器：sAMAccountName = {0}
• 组搜索过滤器:(& (objectclass =集团)(cn = {0}))
• 团体成员，其中之一
  • 搜索包含用户的组（如果需要嵌套组成员资格）
    • 组成员资格筛选器：(& (objectCategory =集团)(成员:1.2.840.113556.1.4.1941:= {0}))
  • 解析组列表的用户属性(如果不需要嵌套的组成员关系，将会更快)
    • 组成员属性:memberOf

此外，如果您正在使用/以某些人的名义组织单位你的一些用户或组就在里面组织单位您可能会面临一些身份验证问题，这是由于Java8如何处理principalDN．你会知道你将面临这个问题，因为你可以在Jenkins日志中看到以下异常:必威国际有限公司

org.acegisecurity.ldap.LdapDataAccessException:无法获得第一个元素;嵌套异常是javax.naming.InvalidNameException: Invalid name: "XXXXXXX / XXXXXXX"，dc=example,dc=org

为了避免这种身份验证错误，您不应该使用/字符的名字组织单位用于包含用户或组。

发展

启动本地Jenkins实例：必威国际有限公司

运行mvn现病史:

如何安装

运行

mvn清洁包

创建插件。hpi文件。

如何安装:

1. 复制生成的。/target/ldap。hpi文件到$JENKINS_HO必威国际有限公司ME/plugins目录。别忘了之后重启Jenkins。必威国际有限公司

2. 或者使用插件管理控制台(http://example.com:8080/pluginManager/advanced)上载hpi文件。你必须重新启动Jenkins才能在已安装必威国际有限公司的插件列表中找到该插件。

配置与JCasC

必威国际有限公司:securityRealm:ldap:配置: -服务器:ldap.acme.com根DN:dc=acme，dc=frmanagerDN:"经理"managerPasswordSecret:${LDAP_密码}userSearch:"(& (objectCategory =用户)(sAMAccountName = {0}))"groupSearchFilter:"(& (cn ={0})组(objectclass =))"集团成员战略:fromGroupSearch:过滤器:"(& (objectClass =集团)(| (cn = GROUP_1) (cn = GROUP_2)))"缓存:大小:One hundred.ttl:10userIdStrategy:CaseInsensitive集团战略:区分大小写

要获得更多的例子，请看测试中使用的Yaml文件

插件版本

mvn释放:准备释放:执行-B

许可证

版权所有(c) 2004-2013, Sun Microsystems, Inc.， Kohsuke Kawaguchi, Seiji Sogabe, Olivier Lamy, CloudBees, Inc.， Stephen Connolly，及其他不受限制地经营本软件，包括但不限于使用、复制、修改、合并、出版、分发、再许可和/或销售本软件副本的权利，并允许提供本软件的人这样做，但须遵守下列条件:上述版权声明和本许可声明应包括在软件的所有副本或实质性部分中。本软件是“按现状”提供的，没有任何明示或暗示的保证，包括但不限于适销性、适用于特定目的和不侵权的保证。在任何情况下，作者或版权持有人都不对任何索赔、损害赔偿或其他责任负责，无论是在合同、侵权行为或其他行为中，由软件或使用或其他交易引起的，或与软件有关的，或与软件有关的。