使用 REST API 通过 SCIM 预配用户和组

使用 GitHub 的跨域身份管理系统 (SCIM) 的 REST API 从标识提供者管理用户帐户的生命周期。

谁可以使用此功能？

Enterprise Managed Users 可用于 GitHub Enterprise Cloud 上的新企业帐户。 请参阅“关于 Enterprise Managed Users”。

本文内容

Note

GitHub 建议在与 IdP 和 GitHub 上的生产数据隔离的环境中测试预配。

关于 Enterprise Managed Users 的 IAM

如果在 GitHub 上为 Enterprise Managed Users 创建了企业，则必须配置外部身份管理系统，以便预配和维护用户帐户。 身份管理系统必须提供以下功能：

  • 实施以下两种单一登录 (SSO) 标准之一的单一登录身份验证：
    • 安全断言标记语言 (SAML) 2.0
    • 如果使用 Microsoft Entra ID（以前称为 Azure AD），则为唯一支持的 OpenID Connect (OIDC) 标准
  • 跨域身份管理系统 (SCIM) 的用户生命周期管理

为企业配置身份验证和预配时，既可使用合作伙伴 IdP，也可使用身份管理系统的另一种组合。

使用合作伙伴标识提供者

每个合作伙伴 IdP 都提供一个“铺路路径”应用程序，用以实现 SSO 和用户生命周期管理。 为了简化配置，GitHub 建议使用合作伙伴 IdP 的应用程序进行身份验证和预配。 有关详细信息和合作伙伴 IdP 列表，请参阅“关于 Enterprise Managed Users”。

有关使用合作伙伴 IdP 配置 SCIM 预配的详细信息，请参阅“为企业托管用户配置 SCIM 预配”。

使用其他身份管理系统

如果由于迁移开销、许可成本或组织惰性等原因，无法使用合作伙伴 IdP 进行身份验证和预配，则可使用其他身份管理系统或系统组合。 系统必须使用 SAML 提供身份验证，使用 SCIM 提供用户生命周期管理，并且必须遵循 GitHub 的集成准则。

GitHub 尚未测试与所有身份管理系统的集成。 虽然可以实现与 Enterprise Managed Users 的集成，但 GitHub 的支持团队可能无法帮助你解决与这些系统相关的问题。 如果需要有关非合作伙伴 IdP 的身份管理系统的帮助，或者你仅将合作伙伴 IdP 用于 SAML 身份验证，则必须查询系统的文档，咨询支持团队或利用其他资源。

先决条件

使用 GitHub 的 REST API 进行 SCIM 预配的最佳做法

将身份管理系统配置为在 GitHub Enterprise Cloud 上预配用户或用户组时，GitHub 强烈建议你遵守以下准则。

确保身份管理系统是唯一的写入操作源

为了确保环境具有单一事实来源，应仅以编程方式写入 REST API，以便从身份管理系统进行 SCIM 预配。 GitHub 强烈建议只让一个系统向 API 发送 POST、PUT、PATCH 或 DELETE 请求。

但是，你可以通过脚本中的 GET 请求或企业所有者的临时请求，安全地从 GitHub 的 API 检索信息。

Warning

如果使用合作伙伴 IdP 进行 SCIM 预配，则 IdP 上的应用程序必须是向 API 发出写入请求的唯一系统。 如果使用 POST、PUT、PATCH 或 DELETE 方法发出临时请求，后续的同步尝试将会失败，并且不会为企业正常运行预配。

将有效请求发送到 REST API 终结点

GitHub 的 REST API 终结点，用于通过 SCIM 预配用户，需要格式标准的请求。 请牢记以下准则：

  • 与 API 预期不匹配的请求将返回 400 Bad Request 错误。
  • 用于通过 SCIM 预配用户的 REST API 终结点需要 User-Agent 标头。 GitHub Enterprise Cloud 将拒绝无此标头的请求。
  • 如果你的企业在 GHE.com 上，请确保你将 API 请求发送到你的企业在 api.SUBDOMAIN.ghe.com 的终结点。

在预配组之前预配用户

SCIM 组可以有效地进行大规模用户访问管理。 例如，可以使用身份管理系统上的组来管理 GitHub Enterprise Cloud 上的团队和组织成员身份。

若要在身份管理系统中使用组来管理团队成员身份，必须按顺序完成以下步骤：

  1. 在 GitHub Enterprise Cloud 上预配用户帐户。
  2. 在 GitHub Enterprise Cloud 上预配组。
  3. 更新身份管理系统中的组成员身份。
  4. 在 GitHub Enterprise Cloud 上创建团队，映射到身份管理系统上的组。

验证 GitHub 上的组的访问权限

如果集成使用身份管理系统上的组来管理访问权限，则可验证用户是否获得你期望的访问权限。 可以使用 REST API，将系统的组成员身份与 GitHub 对这些组的理解进行比较。 有关详细信息，请参阅 REST API 文档中的“外部组的 REST API 终结点”和“团队的 REST API 终结点”。

了解 GitHub 的速率限制

为了确保平台的可用性和可靠性，GitHub 实施了速率限制。

如果不考虑速率限制，首次使用 Enterprise Managed Users 的大型企业可能会超过限制。 为避免超过 GitHub Enterprise Cloud 的速率限制，每小时为 IdP 上的 SCIM 集成分配的用户不要超过 1,000 个。 如果使用组将用户分配到 IdP 应用程序，则每小时向每个组添加的用户不要超过 1,000 个。 如果超出这些阈值，预配用户的尝试可能会失败并出现“速率限制”错误。 可以查看 IdP 日志，确认尝试的 SCIM 预配或推送操作是否由于速率限制错误而失败。 对失败的预配尝试的响应将取决于 IdP。

有关详细信息，请参阅“REST API 的速率限制”。

配置审核日志流式处理

企业审核日志显示有关企业中活动的详细信息。 可以使用审核日志来支持 SCIM 的配置。 有关详细信息，请参阅“关于企业的审核日志”。

由于此日志中的事件量，GitHub 会将数据保留 180 天月。 为了确保不会丢失审核日志数据，并在审核日志中查看更精细的活动，GitHub 建议配置审核日志流式处理。 流式处理审核日志时，可以选择流式处理 API 请求的事件，包括对 REST API 终结点的 SCIM 预配请求。 有关详细信息，请参阅“流式处理企业审核日志”。

限制 SCIM 令牌的范围

为增强安全状况，我们建议仅将 personal access token (classic) 与 scim:enterprise 范围结合使用，以限制令牌对进行 SCIM 调用所需 REST API 终结点的访问。

如果当前使用 admin:enterprise 范围的令牌，则应注意此令牌会授予对企业上所有操作的访问权限。 可以将令牌用仅包含 scim:enterprise 范围且不会中断的新令牌交换。

使用 REST API 预配用户

若要预配、列出或管理用户，请向以下 REST API 终结点发出请求。 你可在 REST API 文档中阅读有关关联的 API 终结点的信息，并查看代码示例，还可查看与每个请求关联的审核日志事件。

在身份管理系统上具有身份的人员能够登录到企业之前，必须创建相应的用户。 你的企业不需要可用的许可证来预配新的用户帐户。

  • 有关用户的支持属性的概述，请参阅 REST API 文档中的“SCIM”。
  • 可在 GitHub Enterprise Cloud 的 Web 用户界面中查看预配的用户。 有关详细信息，请参阅“查看企业中的人员”。
操作方法端点和详细信息审核日志中的事件
列出企业的所有预配用户，包括通过将 active 设置为 false 执行软取消设置的所有用户。GET/scim/v2/enterprises/{enterprise}/Users空值
创建一个用户。 API 的响应包括用于唯一标识用户的 id 字段。POST/scim/v2/enterprises/{enterprise}/Users
  • external_identity.provision
  • user.create
  • 如果请求添加 enterprise_owner 角色，business.add_admin
  • 如果请求添加 billing_manager 角色，business.add_billing_manager
  • 如果请求成功，external_identity.scim_api_success
  • 如果请求失败，external_identity.scim_api_failure
使用你发送用于创建用户的 POST 请求中的 id 字段，检索企业中的现有用户。GET/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}空值
使用你发送用于创建用户的 POST 请求中的 id 字段，更新现有用户的全部属性。 将 active 更新为 false 以软取消设置用户，或更新为 true 以重新激活用户。 有关详细信息，请参阅“使用 REST API 对用户进行软取消设置”和“使用 REST API 重新激活用户”。PUT/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • external_identity.update，除非软取消设置或重新预配
  • 如果请求添加 enterprise_owner 角色，business.add_admin
  • 如果请求添加 billing_manager，business.add_billing_manager
  • 如果请求删除 enterprise_owner 角色，business.remove_admin
  • 如果请求删除 billing_manager 角色，business.remove_billing_manager
  • 如果请求成功，external_identity.scim_api_success
  • 如果请求失败，external_identity.scim_api_failure
使用你发送用于创建用户的 POST 请求中的 id 字段，更新现有用户的单个属性。 将 active 更新为 false 以软取消设置用户，或更新为 true 以重新激活用户。 有关详细信息，请参阅“使用 REST API 对用户进行软取消设置”和“使用 REST API 重新激活用户”。PATCH/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • external_identity.update，除非软取消设置或重新预配
  • 如果请求添加 enterprise_owner 角色，business.add_admin
  • 如果请求添加 billing_manager，business.add_billing_manager
  • 如果请求删除 enterprise_owner 角色，business.remove_admin
  • 如果请求删除 billing_manager 角色，business.remove_billing_manager
  • 如果请求成功，external_identity.scim_api_success
  • 如果请求失败，external_identity.scim_api_failure
若要完全删除现有用户，可以硬取消设置用户。 硬取消设置后，再无法重新激活用户，必须将用户预配为新用户。 有关详细信息，请参阅“使用 REST API 硬取消预配用户”。DELETE/scim/v2/enterprises/{enterprise}/Users/{scim_user_id}
  • external_identity.deprovision
  • user.remove_email
  • 如果请求成功，external_identity.scim_api_success
  • 如果请求失败，external_identity.scim_api_failure

使用 REST API 软取消设置用户

若要防止用户登录以访问你的企业，可以通过发送 PUT 或 PATCH 请求，将用户的 active 字段更新为 false 或 /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} 来软取消设置用户。 当你软取消设置用户时，GitHub Enterprise Cloud 将模糊处理用户记录的 login 和 email 字段，用户将被挂起。

当你软取消设置用户时，external_identity.update 事件不会显示在审核日志中。 以下事件显示在审核日志中：

  • user.suspend
  • user.remove_email
  • user.rename
  • external_identity.deprovision
  • 如果请求成功，external_identity.scim_api_success
  • 如果请求失败，则说明 external_identity.scim_api_failure

你可以查看企业的全部挂起用户。 有关详细信息，请参阅“查看企业中的人员”。

使用 REST API 重新激活用户

若要允许已被软取消设置的用户进行登录以访问你的企业，请通过将 PUT 或 PATCH 请求发送到 /scim/v2/enterprises/{enterprise}/Users/{scim_user_id}，将用户的 active 字段更新为 true，取消挂起该用户。

重新激活用户时，external_identity.update 事件不会显示在审核日志中。 以下事件显示在审核日志中：

  • user.unsuspend
  • user.remove_email
  • user.rename
  • external_identity.provision
  • 如果请求成功，external_identity.scim_api_success
  • 如果请求失败，则说明 external_identity.scim_api_failure

使用 REST API 硬取消设置用户

若要完全删除用户，可通过将 DELETE 请求发送到 /scim/v2/enterprises/{enterprise}/Users/{scim_user_id} 来硬取消设置用户。 你的企业将保留由该用户创建的任何资源和注释。

硬取消设置用户时，会发生以下事件：

  • 用户记录的 login 和 email 字段进行模糊处理。
  • 用户的显示名称设置为空字符串。
  • GitHub Enterprise Cloud 删除用户的所有 SCIM 属性、电子邮件、SSH 密钥、personal access tokens 和 GPG 密钥。
  • GitHub Enterprise Cloud 上的用户帐户挂起，登录帐户的身份验证将失败。

若要重新预配用户，必须使用 POST 方法来创建新用户。 新用户可以重复使用已被取消设置的用户的 login。 如果已被硬取消设置用户的电子邮件地址与新用户相匹配，GitHub Enterprise Cloud 会将与该电子邮件地址关联的现有 Git 提交归属于新用户。 原始用户创建的现有资源和注释不会与新用户相关联。

使用 REST API 预配组

若要控制对企业的存储库的访问，可以使用身份管理系统上的组，来控制企业中用户的组织和团队成员身份。 你可在 REST API 文档中阅读有关关联的 API 终结点的信息，并查看代码示例，还可查看与每个请求关联的审核日志事件。

虽然企业不需要可用的许可证来预配新用户帐户，但如果预配的组会导致组织中添加用户，则必须拥有这些用户的可用许可证。如果企业仅使用 包含 GitHub Enterprise 的 Visual Studio 订阅，则必须将关联的用户分配给订阅者。 有关详细信息，请参阅“关于包含 GitHub Enterprise 的 Visual Studio 订阅”。

操作方法端点和详细信息审核日志中的相关事件
列出为企业定义的所有组。GET/scim/v2/enterprises/{enterprise}/Groups空值
若要为企业定义新的 IdP 组，请创建组。 API 的响应包括用于唯一标识组的 id 字段。POST/scim/v2/enterprises/{enterprise}/Groups
  • external_group.provision
  • external_group.update_display_name
  • 如果请求包含用户列表，external_group.add_member
  • 如果请求成功，external_group.scim_api_success
  • 如果请求失败，external_group.scim_api_failure
使用你发送用于创建组的 POST 请求中的 id 字段，检索企业的现有组。GET/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}空值
更新现有组的所有属性。PUT/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.update
  • 如果请求更新组名称，external_group.update_display_name
  • 如果请求将用户添加到组，external_group.add_member
  • 如果请求从组中删除用户，external_group.remove_member
  • 如果请求成功，external_group.scim_api_success
  • 如果请求失败，external_group.scim_api_failure
  • 审核日志中可能会显示其他事件，具体取决于用户是否已经是包含链接到 IdP 组的团队的组织的成员。 有关详细信息，请参阅“IdP 组更改的其他审核日志事件”。
更新现有组的单个属性。PATCH/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.update
  • 如果请求更新组名称，external_group.update_display_name
  • 如果请求将用户添加到组，external_group.add_member
  • 如果请求从组中删除用户，external_group.remove_member
  • 如果请求成功，external_group.scim_api_success
  • 如果请求失败，external_group.scim_api_failure
  • 审核日志中可能会显示其他事件，具体取决于用户是否已经是包含链接到 IdP 组的团队的组织的成员。 有关详细信息，请参阅“IdP 组更改的其他审核日志事件”。
完全删除现有组。DELETE/scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}
  • external_group.delete
  • 如果请求删除了用户在组织中与团队关联的群组，而用户没有其他团队成员资格，org.remove_member
  • 如果请求删除了用户在组织中与团队关联的群组，而用户拥有其他团队成员资格，team.remove_member
  • 如果请求成功，external_group.scim_api_success
  • 如果请求失败，external_group.scim_api_failure

对 IdP 组的更改的其他审核日志事件

如果使用 PUT 或 PATCH 请求，将现有群组的成员更新为 /scim/v2/enterprises/{enterprise}/Groups/{scim_group_id}，GitHub Enterprise Cloud 可能会将用户添加到组织，或者根据用户的当前组织成员身份从组织中删除用户。 如果用户已是组织中至少一个团队的成员，则用户是该组织的成员。 如果用户不是组织中任何团队的成员，则用户也可能尚未成为该组织的成员。

如果请求更新了链接到组织中某个团队的组，而且用户尚未成为该团队的成员，则除了 external_group.update 之外，审核日志还会显示以下事件：

  • org.add_member
  • 如果请求将用户添加到链接到组织中的某个团队的组，而且用户尚未成为该团队的成员，org.add_member
  • 如果请求将用户添加到链接到组织中的某个团队的组，team.add_member

如果请求更新了链接到组织中某个团队的组，而且用户已经成为该团队的成员，则除了 external_group.update 之外，审核日志还会显示以下事件：

  • 如果请求将用户从链接到组织中的某个团队的组中删除，而且该团队不是用户在组织中成为成员的最后一个团队，team.remove_member
  • 如果请求将用户从链接到组织中的最后一个团队的组中删除，而且用户已经是该团队的成员，org.remove_member

迁移到新的 SCIM 提供程序

为企业配置 SCIM 预配之后，可能需要迁移到新的 SCIM 提供程序。 有关详细信息，请参阅“将企业迁移到新的标识提供者或租户”。

排除 SCIM 预配错误

  • 如果你对 REST API 的请求受到速率限制，可以在“了解 GitHub 的速率限制”中了解详细信息。

  • 如果为 API 请求启用审核日志流式处理和流式处理事件，可以通过筛选来自 EnterpriseUsersScim 或 EnterpriseGroupsScim 控制器的事件，来查看对 SCIM 预配的 REST API 终结点的任何请求。

  • 如果 SCIM 请求失败，而且无法确定原因，请检查身份管理系统的状态，以确保服务可用。此外，请检查 GitHub 的状态页。 有关详细信息，请参阅“关于 GitHub 支持”。

  • 如果预配用户的请求失败，出现 400 错误，并且你的标识管理系统日志中的错误消息指示帐户所有权或用户名格式存在问题，请查看“外部身份验证的用户名注意事项”。

  • 身份验证成功后，GitHub Enterprise Cloud 会将经过身份验证的用户链接到 SCIM 预配的身份。 身份验证和预配的唯一标识符必须匹配。 有关详细信息，请参阅“SCIM 的 REST API 端点”。你也可以在 GitHub 上查看此映射。 请参阅“查看和管理用户对企业的 SAML 访问”。

  • 如果使用身份管理系统上的群组来管理访问权限，则可使用 GitHub Enterprise Cloud 的 REST API 或 Web 用户界面来排除问题。

有关额外的故障排除建议，请参阅“排除企业的标识和访问管理故障”。