使用 SCIM 2.0，自动化用户与团队管理

了解如何在 ProtoPie Enterprise 中配置 SCIM 2.0（跨域身份管理系统），以便通过身份提供商 (IdP)（如 Okta 或 Microsoft Entra ID）自动管理用户账户和团队。

什么是 SCIM？

当您在 IdP（如 Okta 或 Microsoft Entra ID）中添加或停用用户，或者更改群组成员身份时，ProtoPie Cloud 中的对应账户和团队将自动更新。无需发送邀请电子邮件，也无需为离职员工手动停用账户。

先决条件

• 您必须使用的是企业版套餐（私有云或本地部署）。

• 在启用 SCIM 之前，必须先启用 SSO（SAML 或 OIDC），因为 SCIM 负责用户账户创建和生命周期管理，而不负责身份验证。

• 您需要一个 ProtoPie 企业版管理员账户以及您 IdP 管理控制台中的管理权限。

• 注意：Google Workspace 不支持自定义应用集成的 SCIM。

在 ProtoPie 中准备 SCIM

1) 启用 SCIM 和群组配置 (Group Provisioning)

1. 前往组织设置 (Organization Settings) → 身份验证 (Authentication) 并确认 SSO 已启用。

2. 在用户配置 (User Provisioning) 页面上，将 SCIM 2.0 开关切换为开启 (On)。如果 SSO 处于关闭状态，该请求将被拒绝并显示以下提示：“请先启用 SSO。”("Please enable SSO first.")

3. 要同步到团队级别，还要开启群组配置 (Group provisioning) 开关。如果保持禁用状态，来自 IdP 的群组推送将被拒绝，而用户同步将继续进行。

2) 生成令牌并复制 Base URL

1. 在 SCIM 2.0 部分，点击更新 (Update) 以生成令牌。

2. 点击复制 (Copy) 按钮复制显示的 Bearer Token，并将其保存在安全的位置（例如密码管理器中）。该令牌在此页面上仅显示一次，以后无法再次找回。

   

3. 复制 Base URL，其格式如下：https://<your-protopie-host>/api/scim/v2

注意：如果您省略末尾的 /api/scim/v2，IdP 连接测试将会失败。

☝️重要令牌规则：签发新令牌后，现有令牌将立即作废。每个组织仅允许存在一个有效令牌。如果您在已连接到 IdP 的情况下重新签发令牌，则 IdP 端的令牌也必须更新为新值，以便继续进行同步。

3) 检查连接状态

SCIM 页面顶部的状态徽章会显示以下四种状态之一：

与 Okta 集成

应用选择指南

• 标准方法：从 Okta 目录中添加一个新的 "SCIM 2.0 Test App (Header Auth)"。请勿使用 Basic Auth 变体。因为 ProtoPie SCIM 身份验证仅接受 Authorization: Bearer 令牌，使用 Basic Auth 应用的连接测试将因 401 错误而失败。

• 现有 SAML 2.0 或 SWA 应用：如果是通过 App Integration Wizard 创建的，请在 General App Settings → Edit Provisioning: SCIM 下启用 SCIM 将其链接到同一个应用（目录应用没有此设置；其 Provisioning 标签页从一开始就是可见的）。OIDC 应用没有 SCIM 选项。

• 配置规则：在 Okta 中手动创建的应用无法在单个应用中同时结合 OIDC 和 SCIM。

• 如果 SSO 是 OIDC：在 Okta 中使用两个单独的应用——一个用于登录的 OIDC 应用和一个用于配置 (Provisioning) 的 SCIM 2.0 Test App (Header Auth)。将相同的 Okta 用户组分配给这两个应用。

• 如果 SSO 是 SAML：使用 App Integration Wizard 创建一个 SAML 2.0 应用，然后在 General App Settings → Provisioning 下启用 SCIM，即可在一个应用中同时处理登录和配置。

分步 Okta 设置指南

1. 为 SAML 或 SWA 应用启用 SCIM（如适用）。在 General 标签页中，转到 App Settings → Edit → Provisioning，选择 SCIM，然后保存更改。如果您使用的是目录应用，则可跳过此步骤，因为配置功能已经可用。

   

2. 配置 API 集成。转到 Provisioning → Configure API Integration，选择 Enable API Integration，然后输入以下详细信息：

• Base URL：粘贴从 ProtoPie 复制的 Base URL（https://<host>/api/scim/v2）。

• API Token： 在 Bearer 前缀（prefix，包含空格）后面，粘贴从 ProtoPie 复制的 token（例如：Bearer abc123…）。在 Okta 中，必须保留这个前缀。 而在 Microsoft Entra ID 等其他 IdP（身份提供商）中，则无需前缀，直接输入 token 值即可。

• 对于 SAML 或 SWA 应用： Okta 会显示 Integration → Edit（集成 → 编辑）界面。像上面一样输入 SCIM connector base URL，并在 “Unique identifier field for users”（用户的唯一标识符字段）中选择 “userName”。在 “Supported provisioning actions”（支持的预配操作）中，勾选 “Push New Users”（推送新用户）、“Push Profile Updates”（推送配置文件更新）和 “Push Groups”（推送群组）。将 “Authentication Mode”（身份验证模式）设置为 “HTTP Header”，并在 “Authorization”（授权）字段中同时输入 Bearer 前缀和 token 值。

3. 测试并保存连接。点击 Test API Credentials，或者对于 SAML 或 SWA 应用，点击 Test Connector Configuration。测试成功后，点击 Save。Okta 会向 ProtoPie 发送一个 GET /Users 请求，ProtoPie 中的连接状态将更改为已连接 (Connected)。

• 启用用户生命周期操作。在 Provisioning → To App 下，启用 Create Users、Update User Attributes 和 Deactivate Users。对于 SAML 或 SWA 应用，To App 仅在您于 Supported provisioning actions 下启用 Push New Users 并保存配置后才会出现。启用 Push Groups 还会添加 Push Groups 标签页。这些选项在目录应用中默认可用。

  

  5. 检查属性映射。确认已配置以下映射：

     

  • userName ← user.email（ProtoPie 使用电子邮件地址作为用户名。）

  • givenName ← user.firstName

  • familyName ← user.lastName

  • 移除 ProtoPie 不使用的属性的映射，例如电话号码。

6. 分配用户或群组。在 Assignments 标签页中，分配应具有 ProtoPie 访问权限的用户或群组。一旦分配了用户，Okta 就会立即创建 ProtoPie 账户。如果您的组织使用单独的 SSO 和 SCIM 应用（如采用 OIDC 时），请将用户分配给这两个应用，以便身份验证和账户配置保持同步。为了便于管理，可以创建一个 Okta 群组，例如 ProtoPie Users，并将其分配给这两个应用。仅从 SSO 应用中移除用户并不会停用 ProtoPie 账户；还必须从 SCIM 应用中移除该用户。

   

7. 推送群组以同步团队。在 Push Groups 标签页中，添加您要同步的每个 Okta 群组。ProtoPie 将使用 Okta 群组名称创建相应的团队。

   

   ☝️Okta 会立即发送更改。分配或取消分配后几秒钟内，您就可以在 ProtoPie 成员 (People) 列表中验证它们。验证后，检查 ProtoPie 中的连接状态是否已更改为“已连接 (Connected)”。

   与 Microsoft Entra ID 集成

   开始之前选择正确的应用。配置 (Provisioning) 菜单仅适用于企业应用程序 (Enterprise applications) 下的非库应用 (Non-gallery apps)。如果您使用 SAML 进行 SSO，请在同一个非库应用中配置 SSO 和 SCIM 配置。如果您通过应用注册 (App registrations) 使用 OIDC，请为预配创建一个单独的非库企业应用。将相同的用户和群组分配给 OIDC 应用和预配应用，以便身份验证和账户预配保持同步。

   1. 转到 entra.microsoft.com → Entra ID → 企业应用程序 (Enterprise applications)，然后打开用于 ProtoPie 的非库应用。如果不存在，请选择 + 新建应用程序 (+ New application) → + 创建你自己的应用程序 (+ Create your own application)，输入名称，选择集成库中找不到的任何其他应用程序(非库) (Integrate any other application you don’t find in the gallery (Non-gallery))，然后点击创建 (Create)。创建应用后，确认左侧边栏的管理 (Manage) 下显示有配置 (Provisioning)。该菜单不会出现在应用注册下创建的 OIDC 应用中。

      

   2. 在左侧边栏中打开配置 (Provisioning) 并点击 + 新建配置 (+ New configuration)。默认情况下已选择自动预配。在较早的 Entra 界面中，选择开始使用 (Get started)，然后将配置模式 (Provisioning Mode) 设置为自动 (Automatic)。

   3. 输入 ProtoPie SCIM 凭据：

      

      • 租户 URL (Tenant URL)：粘贴从 ProtoPie 复制的 Base URL（https://<host>/api/scim/v2）。

      • 机密令牌 (Secret Token)：粘贴从 ProtoPie 复制的令牌。

   4. 点击测试连接 (Test Connection)。测试成功后，点击保存 (Save)。Entra 会向 ProtoPie 发送一个 GET /Users?filter=… 请求，ProtoPie 中的连接状态将更改为已连接 (Connected)。如果测试超时，请确认您的防火墙允许来自 Microsoft Entra 预配服务 IP 范围的流量。

   5. 打开映射 (Mappings) → 配置 Microsoft Entra ID 用户 (Provision Microsoft Entra ID Users) 并确认以下映射：

      

      • userName ← mail。使用 mail 代替默认的 userPrincipalName，因为 ProtoPie 将 userName 用作用户的登录电子邮件。

      • active ← 保留基于 IsSoftDeleted 的内置 Switch 表达式。当用户在 Entra 中被取消分配或停用时，它会向 ProtoPie 发送 active: false。

      • name.givenName ← givenName

      • name.familyName ← surname

      • externalId ← objectId

      • 移除 ProtoPie 不使用的属性映射，例如地址和电话号码。

   6. 将配置 Microsoft Entra ID 组 (Provision Microsoft Entra ID Groups) 设置为已启用 (Enabled)。Entra 使用每个组的 displayName 作为对应的 ProtoPie 团队名称。

      

   7. 在配置 (Provisioning) → 概述 (Overview)（原设置 (Settings)）下，将范围 (Scope) 设置为仅同步分配的用户和组 (Sync only assigned users and groups)。这可以防止 Entra 尝试配置目录中的每个用户和组。

      

   8. 打开用户和组 (Users and groups) 并分配应预配到 ProtoPie 的用户和群组。选择建议的范围后，仅同步已分配的对象。

      

   9. 将配置状态 (Provisioning status) 设置为开启 (On) 并点击保存 (Save)。在较旧的界面中，这相当于点击启动配置 (Start provisioning)。若要稍后暂停同步，请将状态设置为关闭 (Off)。

      

      ☝️Microsoft Entra 大约每 40 分钟运行一次增量同步周期，因此新分配的用户和群组可能不会立即出现在 ProtoPie 中。若要在不等待下一个周期的情况下进行测试，请选择一个用户，运行按需配置 (Provision on demand)，并在配置日志 (Provisioning logs) 中查看结果。

      

ProtoPie 中由 SCIM 管理的账户

管理用户账户

同步后，ProtoPie 会标记通过 SCIM 管理的账户，并限制可能与您的身份提供商冲突的更改。

• 识别由 SCIM 管理的用户。在成员 (People) 列表中，受管账户旁边会显示 SCIM 徽章。使用列表顶部的 SCIM 筛选器可显示所有用户、仅显示 SCIM 管理的用户或仅显示不受 SCIM 管理的用户。

  

  成员列表 — SCIM 标签

  

  SCIM 筛选器已开启

• 在您的 IdP 中管理账户详细信息。由 SCIM 管理的用户的姓名、电子邮件地址、活动状态和账户删除无法在 ProtoPie 中更改。请在您的身份提供商中进行这些更改，ProtoPie 将在下次同步期间应用它们。在用户的行菜单 (⋯) 中，更改电子邮件地址或停用账户的选项已被移除；仅保留重置 MFA (Reset MFA)。

  

  SCIM 账户行菜单 — 仅保留“重置 MFA”

• 用户无法编辑受管个人资料详细信息。在账户设置中，SCIM 管理的用户会看到其姓名和电子邮件字段处于禁用状态，并附有消息 账户由 IdP 管理 (Account managed by IdP)。要更新这些详细信息，他们必须联系管理员或遵循组织的身份管理流程。

  

  账户设置 — SCIM 管理的账户编辑已锁定（临时屏幕）

• 用户仅能通过 SSO 登录。SCIM 管理的账户没有 ProtoPie 密码，不受 ProtoPie 内置 MFA 的约束。成员 (People) 列表中的 MFA 列显示不适用 (Not applicable)。请告知现有用户，他们在启用 SCIM 之前使用的任何 ProtoPie 密码都将被移除。

  

  账户设置 — SCIM 管理账户的 MFA 部分。

• 角色和个人资料照片仍可在 ProtoPie 中编辑。管理员仍然可以更改用户的 ProtoPie 角色（管理员 (Admin) 或成员 (Member)），用户仍然可以更新其个人资料照片。

管理团队

启用群组配置后，您的身份提供商将在 ProtoPie 中管理团队创建和成员资格。

• 团队在同步第一个成员时创建。当添加第一个成员时，IdP 群组将变为 ProtoPie 团队。新团队成员最初以查看者 (Viewers) 身份加入；您可以在 ProtoPie 中提升他们的团队角色。

• 在您的 IdP 中管理团队成员资格。您无法在 ProtoPie 中添加、邀请或移除 IdP 管理的成员。SCIM 管理的团队和成员会显示 SCIM 徽章，并且邀请新成员 (Invite new member) 按钮处于禁用状态。要更改成员资格，请更新您 IdP 中的相应群组。

  

  
  

• 检查自动分配的团队所有者。创建团队时，ProtoPie 会将所有权分配给账户注册时间最早的组织管理员。如果应由其他人拥有该团队，请在同步后在 ProtoPie 中更改所有者。

• 团队名称必须唯一。如果您的组织已有多个同名团队，则匹配的 IdP 群组同步将失败并出现 409 唯一性错误。请在 ProtoPie 中重命名现有团队，使每个团队都拥有唯一的名称，然后从 IdP 重试群组同步。

• 删除 IdP 群组不会删除 ProtoPie 内容。关联的团队及其文件将保留在 ProtoPie 中，但与 IdP 群组的连接将被移除。

日常 SCIM 管理

将您的 IdP 作为管理 SCIM 用户和团队成员资格的主要位置。

• 新员工：在您的 IdP 中将用户分配给 ProtoPie 配置应用。ProtoPie 将自动创建账户，用户通过 SSO 登录。

• 离职员工：在您的 IdP 中移除用户的分配或停用该账户。ProtoPie 会停用该账户但保留其数据。如果必须永久删除账户，ProtoPie 管理员必须单独处理。

• 电子邮件地址更改：SCIM 集成后在 IdP 中进行的电子邮件更改不会自动应用到 ProtoPie。如果必须更改电子邮件地址，请联系 ProtoPie 支持团队。

• 团队成员资格更改：在您的 IdP 对应群组中添加或移除用户。不要在 ProtoPie 中管理受 SCIM 控制的成员资格。

SCIM 故障排除

• 连接测试失败并提示 401 Unauthorized：令牌无效、已过期或复制错误。重新签发令牌会使先前的令牌立即失效。如果 ProtoPie 显示需要重新连接 (Reconnection required)，请在 IdP 中更新令牌并再次测试连接。

• 连接测试失败并提示 403 Forbidden：ProtoPie 中的 SCIM 2.0 开关处于关闭状态。将其打开，然后重试连接测试。

• 连接测试失败并提示 404 Not Found：确认 Base URL 包含 /api/scim/v2，且您的组织使用的是符合条件的企业版套餐。

• 群组成员未出现在 ProtoPie 团队中：该用户可能未分配给配置应用。请先分配该用户，然后在 IdP 中重试或保存该群组。

• 预配失败并出现 409 唯一性错误：ProtoPie 中已存在具有相同电子邮件地址的账户或同名团队。检查 IdP 日志以查找具体的冲突，解决重复项，然后重试同步。

  • Okta：在 Apps → Push Groups 下打开受影响的群组，或者在 Reports → System Log 下打开该事件，并查看 Debug Data 中的响应正文。

  • Microsoft Entra：在 配置日志 (Provisioning logs) 下打开失败的条目，然后查看故障排除与建议 (Troubleshooting & Recommendations)。

  • 解决冲突后，Okta 将重试群组推送。Microsoft Entra 将在其下一个同步周期中应用更改，或者您可以运行按需配置 (Provision on demand)。

• Microsoft Entra 将预配置于隔离区：由于临时服务器或配置错误导致的反复失败，Entra 可能会暂停预配。在配置日志 (Provisioning logs) 中查看最新错误，解决原因，然后点击重新启动配置 (Restart provisioning)。

暂停或断开 SCIM

根据您是想要暂停同步还是永久删除 SCIM 连接，来选择匹配的选项。

• 暂时暂停同步：关闭 SCIM 2.0 开关。您的映射和令牌将保持配置状态，但 ProtoPie 将拒绝预配请求，直到您重新开启 SCIM。在同步暂停期间，对 SCIM 管理的用户和团队的编辑限制仍然有效。

• 彻底断开 SCIM：点击断开 SCIM (Disconnect SCIM)，然后点击断开连接 (Disconnect) 进行确认。ProtoPie 将移除针对用户和团队的所有 SCIM 链接，删除活动令牌，并关闭 SCIM。现有的账户、团队和文件将作为标准的非受管内容保留在 ProtoPie 中。此操作无法撤销。该过程完成后，ProtoPie 将显示已断开连接的用户、团队和令牌数量。

• 断开单个用户或团队的连接：在成员 (People) 或团队 (Teams) 下找到该条目，然后点击解除与 IdP 的关联 (Unlink from IdP)。由于取消关联的用户可能没有 ProtoPie 密码，请在他们尝试不通过 SSO 登录之前，指导他们完成密码重置流程。

• 重新连接用户或团队：在您的 IdP 中将用户或群组重新分配给配置应用，然后运行完全同步。