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

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

在本文中

注意

在当前版本的 GitHub Enterprise Server 中，SCIM 支持处于公共预览版阶段。 SCIM 支持已在版本 3.17 及更高版本中正式发布。

关于在 GitHub Enterprise Server 上进行的 SCIM 配置管理

要使用 SCIM 预配和维护用户帐户，身份管理系统必须提供以下功能：

  • 实现安全断言标记语言 (SAML) 2.0 的单一登录身份验证
  • 跨域身份管理系统 (SCIM) 的用户生命周期管理

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

  •         [使用合作伙伴身份提供者](#using-a-partner-identity-provider)

  •         [使用其他身份管理系统](#using-other-identity-management-systems)

使用合作伙伴身份提供商

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

有关使用合作伙伴 IdP 配置 SCIM 预配的详细信息，请参阅“配置 SCIM 预配 （用于管理用户）”。

使用其他身份管理系统

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

GitHub 没有明确支持混合合作伙伴 IdP 来进行身份验证和预配，而且未测试所有身份管理系统。 GitHub 的支持团队可能无法协助你解决与混合或未测试的系统相关的问题。 如果需要帮助，必须咨询系统的文档、支持团队或其他资源。

重要

用于 SSO 和 SCIM 的 Okta 与 Entra ID 的组合显式不受支持********。 如果配置这种组合，GitHub的 SCIM API 将在预配尝试时向标识提供者返回错误。

先决条件

要使用 REST API 实现 SCIM，必须满足在 GitHub Enterprise Server 上使用 SCIM 的一般先决条件。 请参阅“配置 SCIM 预配 （用于管理用户）”中的“先决条件”部分。

此外，还应满足以下先决条件：

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

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

  •         [确保身份管理系统是唯一的写入操作源](#ensure-your-identity-management-system-is-the-only-source-of-write-operations)

  •         [将有效请求发送到 REST API 终结点](#send-valid-requests-to-rest-api-endpoints)

  •         [在配置组之前先配置用户](#provision-users-before-you-provision-groups)

  •         [验证 GitHub 上的组的访问权限](#validate-access-for-groups-on-github)

  •         [了解 GitHub 的速率限制](#understand-rate-limits-on-github)

  •         [配置审核日志流式处理](#configure-audit-log-streaming)

  •         [限制 SCIM 令牌的范围](#limit-the-scope-of-the-scim-token)

  •         [了解取消预配的影响](#understand-the-effects-of-deprovisioning)

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

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

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

警告

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

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

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

  • 与 API 预期不匹配的请求将返回 400 Bad Request 错误。
  • 用于通过 SCIM 预配用户的 REST API 接口端点需要 User-Agent 标头。 GitHub 将拒绝无此标头的请求。

在配置组之前先配置用户

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

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

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

验证 GitHub 上组的访问权限

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

了解 GitHub 的速率限制

如果站点管理员对实例启用了速率限制，则首次预配用户时可能会遇到错误。 可以查看 IdP 日志，确认尝试的 SCIM 预配或推送操作是否由于速率限制错误而失败。 对失败的预配尝试的响应将取决于 IdP。

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

配置审核日志流式处理

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

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

限制 SCIM 令牌的范围

为获得更好的安全态势，我们建议使用仅具有 scim:enterprise 范围的 personal access token (classic)，限制令牌对进行 SCIM 调用所需的 REST API 终结点的访问。

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

了解取消预配的影响

要移除用户对 GitHub 的访问权限，可以将“软取消预配”或“硬取消预配”请求发送到 SCIM 提供程序。 硬取消预配是一种不可逆的操作，会永久暂停用户的 GitHub 帐户。

在实现 API 集成之前，请确保你了解取消预配的类型及其影响。 要了解各种取消预配类型、它们所产生的影响以及生成的审核日志事件，请参阅“使用 SCIM 取消预配和恢复用户”。

使用 REST API 预配用户

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

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

  • 有关用户的支持属性的概述，请参阅 REST API 文档中的“SCIM”。
  • 可在 GitHub 的用户界面中查看预配的用户。 有关详细信息，请参阅“查看企业中的人员”。
操作方法端点和详细信息审核日志中的事件
列出企业的所有预配用户，包括通过将 active 设置为 false 进行软取消预配的所有用户。GET/scim/v2/Users空值
创建一个用户。 API 的响应包括用于唯一标识用户的 id 字段。POST/scim/v2/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
使用你发送用于创建用户的 id 请求中的 POST 字段，检索企业中的现有用户。GET/scim/v2/Users/{scim_user_id}空值
使用你发送用于创建用户的 id 请求中的 POST 字段，更新现有用户的全部属性。 将 active 更新为 false 以软卸载用户，或将 active 更新为 以重新激活用户。 有关详细信息，请参阅“使用 REST API 软取消预配用户”和“使用 REST API 重新激活用户”。PUT/scim/v2/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
使用你发送用于创建用户的 id 请求中的 POST 字段，更新现有用户的单个属性。 将 active 更新为 false 以软卸载用户，或将 active 更新为 以重新激活用户。 有关详细信息，请参阅“使用 REST API 软取消预配用户”和“使用 REST API 重新激活用户”。PATCH/scim/v2/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/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/Users/{scim_user_id} 来软取消设置用户。 当你软取消预配用户时，GitHub 会混淆用户记录的 login 和 email 字段，用户将被暂停。

使用 REST API 重新激活用户

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

通过 REST API 硬删除用户配置

重要

硬取消预配是一种不可逆的操作，会永久暂停用户的 GitHub 帐户。 请参阅了解取消预配的影响。

你可以通过向 DELETE 发送 /scim/v2/Users/{scim_user_id} 请求来硬取消预配用户。 你的企业将保留由该用户创建的任何资源和注释。

使用 REST API 预配组

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

虽然企业不需要可用的许可证来预配新用户帐户，但如果预配的组会导致组织中添加用户，则必须拥有这些用户的可用许可证。

操作方法端点和详细信息审核日志中的相关事件
列出为企业定义的所有组。GET/scim/v2/Groups空值
若要为企业定义新的 IdP 组，请创建组。 API 的响应包括用于唯一标识组的 id 字段。POST/scim/v2/Groups
  • external_group.provision
  • external_group.update_display_name
  • 如果请求包含用户列表，external_group.add_member
  • 如果请求成功，external_group.scim_api_success
  • 如果请求失败，external_group.scim_api_failure
使用你发送用于创建组的 id 请求中的 POST 字段，检索企业的现有组。GET/scim/v2/Groups/{scim_group_id}空值
更新现有组的所有属性。PUT/scim/v2/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/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/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/Groups/{scim_group_id}，GitHub 可能会将用户添加到组织，或者根据用户的当前组织成员身份从组织中删除用户。 如果用户已是组织中至少一个团队的成员，则用户是该组织的成员。 如果用户不是组织中任何团队的成员，则用户也可能尚未成为该组织的成员。

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

  • org.add_member
  • 如果请求将用户添加到与某个组织中的团队相关联的组，而用户尚未是该团队或该组织的成员，org.add_member
  • 如果请求将用户添加到与某个组织中的团队相关联的组，team.add_member

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

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

解决 SCIM 预配问题

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

  • GitHub 接收的所有 SCIM 请求（成功的 HTTP GET 请求除外）都将生成审核日志事件。 这些日志将包含有关请求结果、有效负载信息和任何错误的有用信息。 这些日志可用于确定 GitHub 是否收到 SCIM 请求，以及排查 API 故障。

    • 若要确定用户是否已预配，可以使用以下审核日志查询：action:external_identity.provision user:USERNAME
    • 如果使用上述查询未找到用户，可以搜索你预期收到请求的具体日期的 action:external_identity.scim_api_failure 事件。

  • 如果 SCIM 请求失败，而且无法确定原因，请检查身份管理系统的状态，以确保服务可用。

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

  • 身份验证成功后，GitHub 会将经过身份验证的用户链接到由 SCIM 预配的身份。 身份验证和预配的唯一标识符必须匹配。 有关详细信息，请参阅“SCIM 的 REST API 端点”。

  • 如果使用身份管理系统上的组来管理访问权限，则可以使用 GitHub 的 REST API 或 Web 用户界面来进行故障排除。

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