使用 LDAP

关于 GitHub Enterprise Server 的 LDAP 身份验证

LDAP 是一种用于访问和维护目录信息服务的热门应用程序协议，是将第三方软件与大型公司用户目录集成时使用的最常见协议之一。 有关详细信息，请参阅 Wikipedia 上的轻型目录访问协议。

如果使用 LDAP 目录进行集中身份验证，则可以为使用 你的 GitHub Enterprise Server 实例的用户配置 LDAP 身份验证。

如果想要允许对某些在你的外部验证提供程序上无帐户的人员进行身份验证，可以允许对 你的 GitHub Enterprise Server 实例 上的本地帐户进行回退身份验证。 有关详细信息，请参阅“允许对提供程序覆盖范围之外的用户进行内置身份验证”。

支持的 LDAP 服务

GitHub Enterprise Server 与以下 LDAP 服务集成：

• Active Directory
• FreeIPA
• Oracle Directory Server Enterprise Edition
• OpenLDAP
• 打开目录
• 389-ds

使用 LDAP 时的用户名考量因素

GitHub 规范化 外部身份验证提供程序 中的值，以确定 上 你的 GitHub Enterprise Server 实例 上每个新个人帐户的用户名。 有关详细信息，请参阅 外部身份验证的用户名注意事项。

使用 你的 GitHub Enterprise Server 实例 配置 LDAP

在您配置 LDAP 后，用户将能够使用他们的 LDAP 凭据登录您的实例。 在用户首次登录时，他们个人资料中的姓名、电子邮件地址和 SSH 密钥将使用您的目录中的 LDAP 属性进行设置。

当您通过 管理控制台 为用户配置 LDAP 访问时，在用户首次登录到您的实例之前，不会占用您的用户许可证。 但是，如果您通过站点管理员设置手动创建帐户，用户许可将被立即计入。

1. 在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击“”。

2. 如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。

3. 在“ 站点管理”边栏中，单击“管理控制台”****。

4. 在“设置”边栏中，单击“身份验证”。

5. 在“身份验证”下选择“LDAP”。

6. （可选）若要允许外部身份验证系统上没有帐户的人员使用内置身份验证登录，请选择“允许内置身份验证”。 有关详细信息，请参阅“允许对提供程序覆盖范围之外的用户进行内置身份验证”。

7. 添加您的配置设置。

LDAP 属性

使用这些属性完成为 你的 GitHub Enterprise Server 实例. 的 LDAP 配置。

特性名	必需的	说明
Host		LDAP 主机，例如 ldap.example.com 或 10.0.0.30。 如果该主机名仅能从您的内部网络访问，则您可能需要先配置 你的 GitHub Enterprise Server 实例
的 DNS，使其能够使用您的内部名称服务器解析该主机名。
Port		主机的 LDAP 服务侦听的端口。 示例包括：389 和 636（适用于 LDAPS）。
Encryption		用于确保与 LDAP 服务器之间的通信安全的加密方法。 示例包括明文（无加密）、SSL/LDAPS（从一开始就加密）和 StartTLS（在连接后升级为加密通信）。
Domain search user		查找其他登录用户的 LDAP 用户，以允许身份验证。 这一般是一个专为第三方集成创建的服务帐户。 使用完全限定的名称，例如 cn=Administrator,cn=Users,dc=Example,dc=com。 使用 Active Directory，还可以将 [DOMAIN]\[USERNAME] 语法（例如WINDOWS\Administrator）用于具有 Active Directory 的域搜索用户。
Domain search password		域搜索用户的密码。
Administrators group		登录您的设备后，此组中的用户将被升级为站点管理员。 如果您不配置 LDAP 管理员组，则登录您的设备的第一个 LDAP 用户帐户将被自动升级为站点管理员。
Domain base		想要搜索其用户和组的 LDAP 子树的完全限定 Distinguished Name (DN)。 每个组和它所包含的用户都必须在相同的基础域中定义。 如果您指定受限的用户组，那么只有属于这些组的用户将在作用域内。 我们建议您将 LDAP 目录树的顶级指定为您的基础域，并使用受限的用户组来控制权限。 可以配置多个域基础。 但是， GitHub Enterprise Server 按顺序搜索每个已配置的域基础的用户和组成员身份，因此配置多个域基可以增加执行的 LDAP 查询数。 为了确保实例的性能和稳定性，我们建议域基础配置数量不超过三个。
Restricted user groups		如果指定，将仅允许这些组中的用户登录。 只需指定组的公用名 (CN)。 如果未指定任何组，则指定域基范围内的 所有用户 都可以登录到 GitHub Enterprise Server 实例。 可以配置多个受限用户组。 但是，每个组都会增加 GitHub Enterprise Server 为每个用户执行的组成员身份 LDAP 查询的数量。 为了防止身份验证超时和同步性能问题，我们建议组配置数量不超过三个。
User ID		标识尝试身份验证的 LDAP 用户的 LDAP 属性。 建立映射后，用户可以更改其 GitHub Enterprise Server 用户名。 对于大多数Active Directory安装，此字段应为 sAMAccountName，但对于其他 LDAP 解决方案（如 OpenLDAP），此字段可能uid。 默认值为 uid。
Profile name		将显示在用户的 GitHub Enterprise Server 个人资料页面上的名称。 除非启用 LDAP 同步，否则用户可以更改他们的个人资料姓名。
Emails		用户帐户 GitHub Enterprise Server 的电子邮件地址。
SSH keys		附加到用户帐户的公共 GitHub Enterprise Server SSH 密钥。 密钥必须采用 OpenSSH 格式。
GPG keys		与用户的 GitHub Enterprise Server 账户关联的 GPG 密钥。
Disable LDAP authentication for Git operations		如果选择，将禁止用户使用 LDAP 密码对 Git 操作进行身份验证。
Enable LDAP certificate verification		如果选择，将启用 LDAP 证书验证。
Synchronization		如果选中此选项，将启用 LDAP 同步。

为 Git 操作禁用密码身份验证

若要强制使用 personal access tokens 或 SSH 密钥进行 Git 访问，这有助于防止服务器被 LDAP 身份验证请求重载，可以为 Git 操作禁用密码身份验证。

我们建议使用此设置，因为响应慢的 LDAP 服务器是性能问题和故障的常见来源，尤其是在遇到轮询导致的大量请求时。

若要禁用 Git 操作的密码身份验证，请在 LDAP 设置中选择“禁用 Git 操作的用户名和密码身份验证”。

选择此选项时，如果用户通过命令行尝试为 Git 操作使用密码，他们将收到一条错误消息，内容为 Password authentication is not allowed for Git operations. You must use a personal access token.

启用 LDAP 证书验证

可以通过启用 LDAP 证书验证来验证用于 TLS 的 LDAP 服务器证书。

若要启用 LDAP 证书验证，请在 LDAP 设置中选择“启用 LDAP 证书验证”。

选择此选项时，将对证书进行验证，以确保：

• 如果证书至少包含一个使用者可选名称 (SAN)，则其中的一个 SAN 将匹配 LDAP 主机名。 否则，常用名 (CN) 将匹配 LDAP 主机名。
• 证书未过期。
• 证书由受信任的证书颁发机构 (CA) 签名。

启用 LDAP 同步

可以通过将用户和团队成员身份与已建立的 LDAP 组同步 GitHub Enterprise Server ，为 LDAP 服务器中的用户建立基于角色的访问控制。 有关详细信息，请参阅“创建组织团队”。

LDAP 同步不会在你的 GitHub Enterprise Server 实例上创建用户账户。 有关详细信息，请参阅查看和创建 LDAP 用户。

若要启用 LDAP 同步，请在 LDAP 设置中选择“同步”。

若要为所有用户和所有团队选择同步间隔，请单击下拉菜单。 然后选择每 1 小时、每 4 小时或每 24 小时。

若要从 LDAP 自动同步某些属性，请在“同步用户电子邮件、SSH 和 GPG 密钥”下，单击“同步电子邮件”、“同步 SSH 密钥”和/或 “同步 GPG 密钥”。

启用 LDAP 同步后，某个同步作业将以指定的时间间隔运行，在每个用户帐户上执行以下操作：

• 如果您已允许对您的身份提供程序覆盖范围以外的用户进行内置身份验证，并且该用户使用内置身份验证，请前进到下一个用户。
• 如果用户没有 LDAP 映射，请尝试将用户映射到目录中的 LDAP 条目。 如果用户无法映射到 LDAP 条目，请挂起该用户并转到下一个用户。
• 如果存在 LDAP 映射但目录中相应的 LDAP 条目缺失，请挂起该用户并前进到下一个用户。
• 如果相应的 LDAP 条目已被标记为禁用并且该用户尚未被挂起，请挂起该用户并前进到下一个用户。
• 如果相应的 LDAP 条目未标记为禁用，用户已被挂起，并在管理中心启用了“重新激活挂起的用户”，请取消挂起该用户。
• 如果在实例中配置了一个或多个受限用户组，并且相应的 LDAP 条目不在其中，请挂起该用户。
• 如果在实例上配置了一个或多个受限用户组，相应的 LDAP 条目位于其中一个组中，并在管理中心启用了“重新激活挂起的用户”，请取消挂起该用户。
• 如果相应的 LDAP 条目包括 name 属性，请更新用户的个人资料姓名。
• 如果相应的 LDAP 条目位于管理员组中，请将该用户升级为站点管理员。
• 如果相应的 LDAP 条目未包含在管理员组中，请将该用户降级为普通帐户，除非该帐户被暂停。 暂停的管理员不会被降级，并保留在“站点管理员”和“企业所有者”页面上。
• 如果为电子邮件定义了一个 LDAP 用户字段，请将该用户的电子邮件设置与 LDAP 条目同步。 将第一个 LDAP mail 条目设为主电子邮件。
• 如果为 SSH 公钥定义了一个 LDAP 用户字段，请将该用户的 SSH 公钥与 LDAP 条目同步。
• 如果为 GPG 密钥定义了一个 LDAP 用户字段，请将该用户的 GPG 密钥与 LDAP 条目同步。

某个同步作业也将以指定的时间间隔运行，在已经映射到 LDAP 组的每个团队上执行以下操作：

• 如果已移除团队的相应 LDAP 组，请移除团队中的所有成员。

• 如果已从 LDAP 组中移除 LDAP 成员条目，请从团队中移除相应的用户。 如果用户不再是组织中任何团队的成员，也不是组织的所有者，请从组织中删除该用户。 如果因此用户失去对任何仓库的访问权限，请删除该用户在这些仓库中的所有私人派生库。

  注意

  如果用户是组织的所有者，LDAP 同步将不会从组织中删除该用户。 另一个组织所有者将需要手动删除用户。

• 如果已向 LDAP 组中添加 LDAP 成员条目，请将相应的用户添加到团队中。 如果用户因此重新获得了任何仓库的访问权限，请恢复过去 90 天内因为用户失去访问权限而被删除的仓库中的任何私有分叉。

作为优化配置的一部分，LDAP 同步不会传输你的嵌套团队结构。 要创建子团队与父团队的关系，必须手动重新创建嵌套团队结构并将其与相应的 LDAP 组同步。 有关详细信息，请参阅“创建组织团队”

支持的 LDAP 组对象类

GitHub Enterprise Server 支持这些 LDAP 组对象类。 可以嵌套组。

• group
• groupOfNames
• groupOfUniqueNames
• posixGroup

查看和创建 LDAP 用户

使用 LDAP 时，首次使用 LDAP 凭据成功登录时实例会创建用户帐户。 或者，可手动预配用户帐户。

您可以查看具有您的实例访问权限的 LDAP 用户的完整列表和配置新用户。

1. 在 http(s)://HOSTNAME/login 上登录 你的 GitHub Enterprise Server 实例。

2. 在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击“”。

3. 如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。

4. 在左边栏中，单击“LDAP 用户”。

5. 若要搜索用户，请输入完整或部分用户名，然后单击“搜索”。 现有用户将显示在搜索结果中。 如果用户不存在，请单击“创建”以预配新用户帐户。

更新 LDAP 帐户

除非 启用了 LDAP 同步，否则不会自动同步 GitHub Enterprise Server对 LDAP 帐户的更改。

• 若要使用新的 LDAP 管理员组，必须在 GitHub Enterprise Server 上手动提升或降低用户权限，以反映 LDAP 中的变更。
• 若要将 LDAP 帐户加入或移出 LDAP 管理员组，请在 GitHub Enterprise Server 上提升或降级这些帐户。
• 若要删除 LDAP 帐户，请暂停GitHub Enterprise Server这些帐户。

手动同步 LDAP 帐户

1. 在 http(s)://HOSTNAME/login 上登录 你的 GitHub Enterprise Server 实例。

2. 在 GitHub Enterprise Server 上的管理帐户中，在任一页面的右上角，单击“”。

3. 如果你尚未在“站点管理员”页上，请在左上角单击“站点管理员”。

4. 在“搜索用户、组织、团队、存储库、Gist 和应用程序”下的文本字段中键入用户的名称。

5. 在文本字段右侧，单击“搜索”。

   • 如果未找到完全匹配的帐户名，请在“搜索结果 - 帐户”下的“模糊匹配”部分中，单击要管理的用户的名称。
     

6. 在站点管理员页中查看用户详细信息，确认已标识正确的用户。

7. 在页面的右上角，单击“ Admin”****。

8. 在“LDAP”下，单击“立即同步”，使用 LDAP 服务器中的数据手动更新帐户。

也可以使用 API 触发手动同步。

撤销对 你的 GitHub Enterprise Server 实例 的访问权限

如果启用 LDAP 同步，删除用户的 LDAP 凭据将在下一次同步操作后挂起他们的帐户。

如果未启用 LDAP 同步，则必须在删除 LDAP 凭据后手动暂停该GitHub Enterprise Server账户。 有关详细信息，请参阅“挂起和取消挂起用户”。

关于 LDAP 的记录

LDAP 的日志事件出现在 你的 GitHub Enterprise Server 实例 上的 systemd journal 日志中。 你将在 github-unicorn 和 github-resqued 日志中找到与 LDAP 操作相关的事件。 有关详细信息，请参阅“关于系统日志”。

GitHub Enterprise Server 上的 LDAP 限制

GitHub Enterprise Server LDAP 身份验证超时设置为 10 秒。 这意味着，对于正在登录到 GitHub Enterprise Server 的 LDAP 用户，用户身份验证和组成员身份查询（在管理控制台中配置了管理员和受限用户组时）所需的所有 LDAP 查询都必须在 10 秒内成功完成。 GitHub Enterprise Server 目前不支持延长此 10 秒 LDAP 身份验证超时，因为这可能会对设备上的其他服务产生负面影响，并导致性能不佳或意外中断。 建议限制与 LDAP 服务器之间的网络延迟 GitHub Enterprise Server ，以帮助防止身份验证超时。

GitHub Enterprise Server 不支持具有特殊字符的用户 LDAP DN。 如果 LDAP 用户在其 LDAP DN 中有特殊字符， GitHub Enterprise Server 则可能无法准确确定正在通过 LDAP 同步进行身份验证或正在同步的用户的组成员身份。

从 LDAP 迁移到 SAML 和 SCIM

如果您的组织需要超越 LDAP 提供的自动化用户预配和生命周期管理功能，可以通过 SCIM 预配迁移到基于 SAML 的单一登录。 通过此迁移，可以从身份提供者集中进行用户预配和取消预配，以及属性同步。

有关详细信息，请参阅“使用 SCIM 从 LDAP 迁移到 SAML”。