通过 SCIM 预配人员

预配的作用

• 入职人员。 在提供者中将人员分配给应用，screenRIG 就会为其创建账户，并使其成为你的组织的成员。他们通过单点登录登录，没有密码。群组授予项目之前，他们没有任何项目。
• 调动人员。 绑定到项目的群组会让其成员获得该项目。加入或离开群组会添加或移除访问。
• 离职人员。 停用人员或取消其分配，会结束其会话和访问。人员批准的智能体和 OAuth 授权会继续有效，直到该人员被停用（通过用户预配或由 screenRIG 员工停用）：要求单点登录以及在你的提供者处禁用该人员都不会终止它们。

开始之前

• 已设置单点登录，且组织有已验证域名。预配只创建位于你的已验证域名的地址。
• 你是该组织的管理员。

开启

1. 在组织设置中，打开用户预配（SCIM）并选择开启预配。复制基础 URL，即 https://api.screenrig.ai/scim/v2。它位于 API 的源上，而不是控制台的源。
2. 在预配令牌下，选择创建令牌，输入令牌名称（例如 Entra）并确认。请立即复制令牌：srscim_ 后跟 43 个字符，仅显示一次。screenRIG 只保存哈希。

开启预配和创建令牌需要你的通行密钥或密码。单点登录会话也可作为 10 分钟内的近期登录，前提是你的提供者说明该人员的认证时间；否则控制台会要求该人员在提供者处重新登录。

一个组织最多持有五个令牌。要轮换令牌，请创建新令牌，将其粘贴到你的提供者，然后撤销旧令牌；预配持续运行。列表显示每个令牌的最近使用时间。关闭预配会使每个请求返回 403，且不会改变任何人的访问。

Microsoft Entra ID

1. 打开你的企业应用（承载单点登录的那个），选择 Provisioning，并将 Provisioning Mode 设为 Automatic。
2. 在 Admin Credentials 下，将基础 URL 输入为 Tenant URL，将令牌输入为 Secret Token。选择 Test Connection，然后选择 Save。
3. 打开 Mappings、Provision Microsoft Entra ID Users。将 userPrincipalName 映射到 userName（当你的用户主体名称不是人员登录所用的地址时，改用 mail），将 mail 映射到 emails[type eq "work"].value，并让 active 保持默认值 Switch([IsSoftDeleted], , "False", "True", "True", "False")。保留 Entra 提出的其他映射。screenRIG 使用工作电子邮件，没有则使用主电子邮件，再没有则使用 userName；该地址必须位于已验证域名，并且是你的单点登录发送的地址。
4. 保持 Provision Microsoft Entra ID Groups 为启用，以便按群组授予访问。
5. 在 Settings 中，将 Scope 设为 Sync only assigned users and groups，然后在 Users and groups 下分配人员和群组。
6. 将 Provisioning Status 设为 On 并保存。Entra 先运行首个周期，之后约每 40 分钟同步一次。Provision on demand 会立即同步一个人员或群组。

Okta

1. 打开你的 screenRIG 应用。在 General 上，编辑 App Settings，并将 Provisioning 设为 SCIM。
2. 打开 Provisioning、Integration、Edit。将基础 URL 输入为 SCIM connector base URL，将 userName 输入为 Unique identifier field for users，勾选 Push New Users、Push Profile Updates 和 Push Groups，并将 Authentication Mode 设为 HTTP Header。在自定义 SCIM 应用中，将令牌粘贴到 HTTP Header 字段。如果 Okta 要求填写 API Token（Okta 的 SCIM 测试应用），请输入 Bearer、一个空格和令牌。两种方式都可行。选择 Test Connector Configuration，然后选择 Save。
3. 打开 To App、Edit，并启用 Create Users、Update User Attributes 和 Deactivate Users。保持 Sync Password 关闭：screenRIG 会忽略密码。
4. 在 Sign On 上，将 Application username format 设为 Email。
5. 在 Assignments 上分配人员和群组，并在 Push Groups 上推送你绑定的群组。

Okta 通过 active: false 停用人员，从不删除。

群组与项目

已预配的群组列在组织设置的用户预配（SCIM）下的已预配的群组中，附有成员数量和所绑定的项目。项目中可批准的人员绑定群组之前，群组不提供任何访问：

1. 在项目中，打开访问权限，然后打开群组。任何成员都可以查看绑定；项目所有者、可批准的成员以及身为成员的组织管理员可以绑定群组。
2. 在绑定群组下，选择一个群组和一个角色：成员（普通成员资格）或批准人（同时可以批准审核）。选择绑定群组。移除绑定会解除绑定。

绑定还可以把它授予的内容限定在屏幕文件夹和屏幕，与可以限定成员的屏幕范围相同：在绑定群组下选择整个项目或限定屏幕（批准人绑定只能指定文件夹）。一个人在项目中的屏幕是其各个绑定范围的并集，任何没有范围的绑定都会授予整个项目；只有当其批准人绑定覆盖了所有这些屏幕时，此人才能在这些屏幕上批准，因此某个文件夹的批准人加上整个项目的成员，会让此人成为整个项目的普通成员。预配绝不会降低手动授予的访问权限，并且只要此人创建的服务客户端仍然有效，就不会限制此人：每次这样的拒绝都会显示在用户预配的最近活动中，撤销这些客户端后，范围会在下一次同步时生效。绑定的范围是固定的；要更改，请移除该绑定并重新绑定该群组。

• 没有范围时，属于多个已绑定群组的人员获得其中最高的角色，审批人高于成员。
• 加入或离开群组会添加或移除成员资格。解除群组绑定，或在你的提供者中删除群组，会撤回它所授予的内容。
• 预配只移除它添加的内容。手动授予的成员资格保留；被群组提升为审批人的成员，离开该群组后恢复为原有角色。
• 一个组织跨其所有项目最多容纳 200 名成员，每人只计一次。被组织拒绝的人员会在预配事件中记为失败，其他内容不变。
• 群组只授予项目角色，绝不授予组织管理员。管理员能看到绑定和项目名称，看不到项目内容。

谁可以被预配

• 已验证域名下没有账户的地址会创建一个账户，不带密码。
• 没有密码或通行密钥、由你的组织管理，或所在组织要求单点登录的人员，会被接管并通过单点登录登录。
• 已有自己的登录方式且是你的组织某个项目成员的人员，仅为访问而关联，除非你的组织要求单点登录。预配管理他们对你的项目的访问，绝不管理其姓名、电子邮件或登录方式。
• 其他任何人都会被拒绝，并返回指明原因的错误：拥有自己登录方式但不是你的项目成员的账户、由其他组织管理的人员，以及 screenRIG 员工。请先邀请此类人员加入你的某个项目，预配随后会为访问而关联他们。

停用与 DELETE

active: false（通过 PUT 或 PATCH 发送）和 DELETE 都会结束人员的访问。active: true 会取消停用，如各表所述。

由你的预配以外的任何方停用的人员（例如 screenRIG 员工）保持停用状态：active: true 会失败并返回 400 mutability。人员拥有的项目绝不会被转移：已关联的人员保留对该项目的访问，受管理人员的项目则与其账户的其余内容一起保持原状，直至重新启用。如果其他人必须继续管理该项目，请在停用所有者之前转移其所有权。组织的最后一名管理员不能作为受管理人员被停用；请求会失败并返回 400 mutability，因此请先添加另一名管理员。

参考

基础 URL https://api.screenrig.ai/scim/v2。令牌放在 Authorization: Bearer srscim_TOKEN 中，也接受不带前缀的令牌。请求和响应为 application/scim+json；也接受 application/json。

过滤器由一到四个 attribute eq value 项组成，以 and 连接。值是带引号的字符串，对 active 也可以是 true 或 false。用户可按 userName（不区分大小写）、externalId（精确匹配）、id、emails 或 emails.value、displayName 和 active 过滤。群组可按 displayName、externalId、id 以及 members 或 members.value 过滤。其他任何内容返回 400 invalidFilter。

PATCH 按 Entra 和 Okta 发送操作的方式读取操作，带或不带 ?aadOptscim062020 均可。操作名称不区分大小写，布尔值可以是 true、false、"True" 或 "False"。操作可以省略 path，也可以使用带点的键，例如 {"name.givenName": "Ada"}。路径包括 emails[type eq "work"].value、members（添加、替换，以及带值数组的移除）和 members[value eq "<id>"]（移除）。screenRIG 不使用的属性会被接受并忽略。

限制。 一个组织的所有令牌合计每分钟最多发送 600 个请求，不按地址计算，因为 Entra 和 Okta 共用源地址。超出限制时返回 429，并附带 Retry-After。每个地址每 10 分钟最多允许 30 次认证失败。

错误使用带有 scimType 的 SCIM 信封，例如 invalidFilter、uniqueness 或 mutability：

{ "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "409", "scimType": "uniqueness", "detail": "…" }

组织设置中的用户预配列出最近 500 个请求，保留 30 天，包括失败请求及其原因。有内容没有到达时，先查看这里。

故障排查

相关

• 单点登录：连接 Entra ID、Okta、Google Workspace 或其他提供者，并强制使用。
• 身份验证：智能体如何登录，以及访问如何获得批准。
• API 参考：/scim/v2 和预配路由。