使用 PingFederate 配置身份验证和预配

将 PingFederate 设置为标识提供者 (IdP) 用于 GitHub.com 或 GHE.com 上的 Enterprise Managed Users。

谁可以使用此功能？

Enterprise owners with admin access to the IdP

本文内容

当使用 Enterprise Managed Users 时，SAML SSO 可控制并保护对企业资源（如仓库、议题和拉取请求）的访问。 对 IdP 进行更改时，SCIM 会自动创建用户帐户并管理对企业的访问权限。 还可将 GitHub 上的团队与 IdP 上的组同步。 有关详细信息，请参阅“About Enterprise Managed Users”。

概述

本指南将帮助你在 PingFederate 上为 GitHub 设置 SAML 身份验证和 SCIM 预配。

在开始之前，请注意以下事项：

  • 本指南基于 PingFederate 版本 12.1。 其他版本的说明可能有所不同。
  • 本指南提供配置工作设置的最少步骤。 由于标识目录可能以不同的方式连接到 PingFederate，因此需要根据后备数据存储中提供的内容为 SAML 和 SCIM 选取正确的数据属性。

先决条件

如果要为新企业配置 SCIM 预配，请确保完成初始配置过程中的所有先前步骤。 请参阅“Enterprise Managed Users 入门”。

此外：

  • 必须在 PingFederate 上安装“GitHub EMU 连接器”。 若要下载并安装连接器，请参阅 PingIdentity 文档中的安装预配程序。
  • 若要使用 SCIM 预配用户，必须使用 LDAP 服务器作为后备数据存储。
  • 可能需要配置 PingFederate 中的防火墙以允许到 GitHub 上的 SCIM 终结点的出站连接：
    • 对于 GitHub.com：https://api.github.com/scim/v2/enterprises/ENTERPRISE
    • 对于 GHE.com：https://api.SUBDOMAIN.ghe.com/scim/v2/enterprises/SUBDOMAIN
  • PingFederate 的“预配模式”必须设置为允许 SCIM 预配的值。 请参阅 PingIdentity 配置出站预配设置指南中的“准备阶段”部分。
  • 在此过程中，需要将 X509 证书上传到 PingFederate。 在继续操作之前，可能需要创建和存储证书。 还需要证书的质询密码。 请参阅本文后面的“创建 X509 证书的示例”部分。
  • 在此过程中，需要将 SAML 元数据文件上传到 PingFederate。 如果你正在设置一个在 GHE.com 上使用 数据驻留 的企业，那么在开始之前创建这个文件会最容易****。 请参阅“为 GHE.com 创建 SAML 元数据文件”。

1. 配置 SAML

在本部分中，将在 PingFederate 中创建 SAML 连接器，设置 LDAP IdP 适配器实例，并从 IdP 适配器管理 SAML 输出。

  1. 创建 SAML 适配器
  2. 设置 LDAP IdP 适配器实例
  3. 管理 IdP 适配器的 SAML 输出

在开始本部分之前，请确保你已按照“Enterprise Managed Users 入门”中前面的步骤进行操作。****

创建 SAML 适配器

  1. 打开 PingFederate 管理控制台。

  2. 在标头中单击“应用程序”，然后单击左边栏中的“SP 连接”。

  3. 单击“使用此连接的模板”****，然后从“连接模板”下拉列表中选择“GitHub EMU 连接器”。

    注意

    如果未看到此选项，则尚未安装 GitHub EMU 连接器。 如果需要帮助，请联系 Ping 代表。

  4. 为了填充 PingFederate 配置中的一些字段，需要上传一个包含你的企业的 SAML 元数据的 XML 文件。若要查找文件，请执行以下操作：

    • 如果你在 GitHub.com 上设置企业，你将在 PingFederate 上“GitHub EMU Connector”的附加 ZIP 文件中找到此文件****。
    • 如果你在 GHE.com 上设置企业，你将需要手动创建该文件****。 请参阅“为 GHE.com 创建 SAML 元数据文件”。

  5. 在 PingFederate 的“SP Connection”页面上，将上一步中的文件作为元数据文件上传。

  6. 转到“连接类型”选项卡。

  7. 选择“浏览器 SSO 配置文件”，然后取消选择“出站预配”（稍后将启用此功能）。

  8. 单击 “下一步” 。

  9. 在“连接选项”选项卡上，确保仅选择“浏览器 SSO”****。

  10. 单击 “下一步” 。

  11. 在“常规信息”选项卡上，输入以下详细信息。

    • “Partner’s Entity ID”：你的 GitHub 主机 URL（https://github.com 或 https://SUBDOMAIN.ghe.com）
    • “连接名称”：PingFederate 中 SP 连接的描述性名称
    • “Base URL”：你的 GitHub 主机 URL（https://github.com 或 https://SUBDOMAIN.ghe.com）
    • “事务日志记录”：标准
    • 所有其他字段均可留空。

  12. 单击 “下一步” 。

  13. 单击“配置浏览器 SSO”****。

  14. 单击“配置断言创建”****。

  15. 在“身份验证源映射”选项卡上，单击“映射新适配器实例”****。

  16. 在“适配器实例”选项卡上，单击“管理适配器实例”****。

  17. 单击“创建新实例”****。

设置 LDAP IdP 适配器实例

  1. 在 PingFederate 上“创建适配器实例”页的“类型”选项卡上，输入以下详细信息。

    • “实例名称”：用于标识实例的名称，例如 pfghadapter
    • “实例 ID”：实例的 ID，例如 pfghadapter
    • “类型”：HTML 表单 IDP 适配器
    • “父实例”：无

  2. 单击 “下一步” 。

  3. 在页面底部的“IDP 适配器”选项卡上，单击“管理密码凭据验证程序”****。

  4. 单击“创建新实例”****。

  5. 在“类型”选项卡上，输入以下详细信息。

    • “实例名称”：用于标识实例的名称，例如 pfghdocscv
    • “实例 ID”：实例的 ID，例如 pfghdocscv
    • “类型”：LDAP 用户名密码凭据验证程序
    • “父实例”：无

  6. 单击 “下一步” 。

  7. 在“实例配置”选项卡上，单击“管理数据存储”****。

  8. 单击“添加新数据存储”****。

  9. 在“数据存储类型”选项卡上，输入以下详细信息。

    • “实例名称”：任何唯一值，例如 pfghdocsds
    • “类型”：目录 (LDAP)
    • “日志中的掩码值”：取消选择

  10. 单击 “下一步” 。

  11. 在“LDAP 配置”选项卡上，配置 LDAP 服务器详细信息。

  12. 单击 “测试连接”。 应会看到“连接测试成功”。

  13. 单击页面底部的“高级”****。

  14. 单击“LDAP 二进制属性”选项卡，然后添加 guidAttribute 和 objectGUID 作为属性。

  15. 单击“Done”（完成） 。 应返回到“LDAP 配置”选项卡。

  16. 单击“下一步”，然后单击“保存”。

  17. 在“管理数据存储”选项卡上，单击“完成”****。

  18. 在“实例配置”选项卡上，输入以下详细信息。

    • “LDAP 数据存储”：上面创建的数据存储的名称
    • “搜索库”：希望开始 LDAP 搜索的目录中的位置
    • “搜索筛选器”：确保用户登录时输入的用户名与 LDAP 服务器中的字段匹配（例如：sAMAccountName=${username}）
    • “搜索范围”：子树
    • “区分大小写匹配”：已选择

  19. 单击“下一步”，再次单击“下一步”，然后单击“保存”****。

管理 IdP 适配器的 SAML 输出

  1. 在“管理密码凭据验证程序”页上，单击“完成”****。

  2. 在“IDP 适配器”选项卡上，输入以下详细信息。

    • “密码凭据验证程序实例”：上面创建的验证程序实例的名称（例如 pfghdocscv）。 单击“更新”**** 以完成选择。
    • 所有其他字段都可以保留为默认值，或者根据你的要求进行修改。

  3. 单击“下一步”，然后再次单击“下一步”。

  4. 在“适配器属性”选项卡上，输入以下详细信息。

    • “唯一用户密钥属性”：username

    • 在 username 属性旁边，选择“假名”。

    注意

    此步骤非常重要， 在 SCIM 预配过程中，适配器属性用于在 GitHub 上唯一标识用户。

  5. 单击“下一步”，然后再次单击“下一步”。

  6. 查看摘要页上的设置，然后单击“保存”****。

  7. 在“IdP 适配器”选项卡上，应会看到刚刚创建的适配器。 单击“Done”（完成） 。

  8. 在“适配器实例”选项卡上的“适配器实例”下拉列表中，选择刚刚创建的适配器。

  9. 单击 “下一步” 。

  10. 在“映射方法”选项卡上，选择“仅使用 SAML 断言 中的适配器协定值”****（其他选项可能有效，但尚未确认）。

  11. 单击 “下一步” 。

  12. 在“属性协定履行”选项卡上，将 SAML_SUBJECT 映射到“适配器”作为源，而 username 作为值。

    注意

    此步骤非常重要， 规范化 SAML_SUBJECT 需要匹配 SCIM 预配的用户的规范化用户名。

  13. 单击“下一步”，再次单击“下一步”，然后单击“完成”****。

  14. 应返回到“身份验证源映射”选项卡，且“适配器实例名称”部分应包含刚刚创建的适配器实例。

  15. 单击 “下一步” 。

  16. 在“Protocol Settings”选项卡上，单击“Configure Protocol Settings”****。

  17. 对于“Assertion Consumer Service URL”，添加具有以下详细信息的行：

    • 已选择“Default”
    • “Index”：0
    • “Binding”：POST
    • “Endpoint URL”：/enterprises/ENTERPRISE/saml/consume，其中 ENTERPRISE 是你的企业名称或子域

  18. 单击 “下一步” 。

  19. 在“Allowable SAML Bindings”选项卡上，确保仅选中“POST”和“REDIRECT”。

  20. 单击 “下一步” 。

  21. 在“Signature Policy”页上，确保仅选中“SIGN RESPONSE AS REQUIRED”。

  22. 单击 “下一步” 。

  23. 在“Encryption Policy”选项卡上，确保已选择“NONE”。

  24. 单击 “下一步” 。

  25. 单击“ 保存”。

  26. 单击“下一步”**** 和“完成”****，直到到达“凭据”选项卡。

  27. 在“凭据”选项卡上，单击“配置凭据”，然后单击“管理证书”。

  28. 在“Certificate Management”页上，单击“Import”，然后上传 X509 证书（如需帮助，请参阅“创建 X509 证书的示例”部分）。****

  29. 对于“密码”，请使用证书的质询密码。

  30. 单击“下一步”，然后单击“保存”。

  31. 在“证书管理”选项卡上，应会看到刚刚导入的证书。 单击“Done”（完成） 。

  32. 在“数字签名设置”选项卡上：

    • 为“签名证书”选择刚创建的证书。
    • 可以将辅助证书留空，并取消选中“在签名中包含证书”复选框。
    • 签名算法应为“RSA SHA256”。

  33. 依次单击“下一步”、“完成”、“下一步”****。

  34. 在“摘要”选项卡上，启用“SSO 应用程序终结点”的切换。

  35. 单击“ 保存”。 应返回到 SP 连接列表，在此应会看到新创建的 SP 连接。

收集 SAML 配置的信息

需要 PingFederate 中的一些详细信息才能在 GitHub 上配置 SAML。

  1. 在“SP 连接”页上新连接的行中，单击“选择操作”，然后单击“导出元数据”。
  2. 在“元数据签名”选项卡上新连接的行中，选择上面创建的签名证书。 要下载该证书，请单击“下一步”，然后单击“导出”。
  3. 在 PingFederate 上，依次单击标头中的“系统”、“服务器” 和“协议设置”****。 检查 SAML 2.0 ENTITY ID 是否已定义。 请记下此项，因为 GitHub 的 SAML 设置中的“颁发者”字段需要该内容。
  4. 打开下载的元数据文件，并准备好执行后续步骤。

配置 GitHub

  1. 以你的企业的设置用户身份登录 GitHub

  2. 在企业设置中启用 SAML。 请参阅“为企业托管用户配置 SAML 单一登录”。

  3. 输入上一部分中 SAML 元数据文件中的以下值。

    • 对于“单一登录 URL”，请使用 <md: SingleSignOnService> 字段的 location 值。 此项应为以 /idp/SSO.saml2 结尾的 URL。
    • 对于“颁发者”，请使用 <md: EntityDescriptor> 字段的 entityId 值 (URL)。

  4. 对于“验证证书”，上传之前创建的 X509 证书文件。

  5. 单击“保存设置”。

2. 配置 SCIM

在本部分中，将在 PingFederate 上配置 SCIM 设置和属性映射。

  1. 配置 SCIM 设置
  2. 将 LDAP 字段映射到 SCIM
  3. 完成配置和测试

在开始本部分之前，请确保你已按照“Enterprise Managed Users 入门”中前面的步骤进行操作。****

配置 SCIM 设置

  1. 返回到 PingFederate 上的“SP 连接”页，然后选择之前创建的 SP 连接。

  2. 单击“连接类型”选项卡。

  3. 选择“出站预配”****。

  4. 确保已选择“浏览器 SSO 配置文件”****。

  5. 单击“下一步”，直到到达“出站预配”选项卡，然后单击“配置预配”。

  6. 在“目标”选项卡上，输入以下详细信息。

    • “Base URL”：https://api.github.com/scim/v2/enterprises/{enterprise}/ 或 https://api.SUBDOMAIN.ghe.com/scim/v2/enterprises/SUBDOMAIN
    • “Access Token”：为设置用户创建的 personal access token (classic)

  7. 单击 “下一步” 。

  8. 在“管理频道”选项卡上，单击“创建”****，然后输入唯一的频道名称，例如 pfghscim。

  9. 单击 “下一步” 。

  10. 在“源”选项卡上，选择之前创建的数据存储。

  11. 单击 “下一步” 。

  12. 在“源设置”选项卡上，可以保留所有默认设置。 其他设置可能正常工作，但尚未确认。

  13. 单击 “下一步” 。

  14. 在“源位置”选项卡上，配置希望预配用户来自 LDAP 服务器中的位置。 此项因设置和需求而异。 配置后，单击“下一步”****。

将 LDAP 字段映射到 SCIM

在“属性映射”选项卡上，需要将字段从 LDAP 服务器映射到 SCIM 字段。 请参阅以下列表，了解 GitHub 支持的 SCIM 字段以及每个字段的预期值。

  • Username：这将被规范化，并用作预配用户的 GitHub 用户名****。 请参阅“外部身份验证的用户名注意事项”。 此项必须与在 PingFederate 中使用 SAML_SUBJECT 属性配置的 SAML 断言发送的主题规范化匹配。
  • 电子邮件****：包含用户电子邮件地址的字段。
  • 显示名称****：用户可读的名称。
  • 格式化名称****：用户的全名，包括所有中间名、称谓和后缀，经过格式化以便显示。
  • 名字****：用户的名字。
  • 姓氏****：用户的姓氏。
  • 外部 ID****：此标识符由 IdP 提供程序生成。
  • Roles：此字段应包含一个字符串，表示用户对 GitHub 的预期角色****。 有效的角色是 enterprise_owner、user、billing_manager 和 guest_collaborator。

完成配置设置后，请单击“下一步”****。

完成配置和测试

  1. 在“激活和摘要”选项卡上的“频道状态”中，选择“活动”****。
  2. 在“管理频道”选项卡上，单击“完成”****。
  3. 在“出站预配”选项卡上，单击“保存”****。 SCIM 现已配置并启用。
  4. 等待几分钟让预配运行，然后打开一个新的专用浏览器窗口并导航到 GitHub。
  5. 单击“使用 SAML 登录”****。 应重定向到 PingFederate 登录页。
  6. 你应该能够使用已预配给 GitHub 的 LDAP 服务器中用户的凭据登录。

PingFederate 预配可独立处理用户和组。 必须直接分配用户才能进行预配。 不会预配处于已分配组但未直接分配的用户。

创建 X509 证书的示例

可通过多种方式创建 X509 证书。 下面是一个可能满足要求的示例。

  1. 在终端窗口中，通过运行 openssl version 检查是否已安装 OpenSSL。 如果未安装，请安装它。

  2. 使用以下命令生成私钥。

    Shell
    openssl req -nodes -sha256 -newkey rsa:2048 -keyout MyPrivateKey.key -out MyCertificateRequest.csr

    输入所需的信息，并记下**** 你创建的质询密码。

  3. 要确保密钥已创建，请运行以下命令。 命令输出中应列出一个名为 MyPrivateKey.key 的文件。

    Shell
    ls | grep MyPrivateKey.key

  4. 使用以下命令生成证书。

    Shell
    openssl x509 -req -days 365 -sha256 -in MyCertificateRequest.csr -signkey MyPrivateKey.key -out pfgh256.crt

  5. 要确保证书已创建，请运行以下命令。 命令输出中应列出一个名为 pfgh256.crt 的文件。

    Shell
    ls | grep pfgh256.crt

  6. 使用以下命令导出 PKCS #12 文件。 这是应上传到 PingFederate**** 的文件。

    Shell
    openssl pkcs12 -export -in pfgh256.crt -inkey MyPrivateKey.key -out pfgh256.p12

  7. 要确保文件已导出，请运行以下命令。 命令输出中应列出一个名为 pfgh256.p12 的文件。

    Shell
    ls | grep pfgh256.p12

为 GHE.com

创建 SAML 元数据文件

由于某些值与 PingFederate 为 GitHub.com 提供的元数据文件不同，因此需要手动为企业的 SAML 元数据创建 XML 文件。

  1. 将以下 XML 复制到文本编辑器中。

    XML
    <?xml version="1.0"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  entityID="https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN" cacheDuration="PT1440M">
  <md:SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"
    AuthnRequestsSigned="false" WantAssertionsSigned="false">
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified</md:NameIDFormat>
    <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
      Location="https://SUBDOMAIN.ghe.com/enterprises/SUBDOMAIN/saml/consume" isDefault="true"
      index="0"/>
  </md:SPSSODescriptor>
</md:EntityDescriptor>

  2. 将 SUBDOMAIN 的所有实例替换为企业的子域 GHE.com。 例如：octocorp。

  3. 将该文件另存为 XML 文件。

  4. 返回到“创建 SAML 适配器”中的说明。