Label Studio Enterprise SCIM2 配置实战Okta 与 Microsoft Entra ID 的自动化用户与群组管理【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio导读本文围绕 Label Studio Enterprise 的 SCIMSystem for Cross-domain Identity Management集成展开讲解如何借助 SCIM 2.0 标准让身份提供商IdP如 Okta、Microsoft Entra ID自动化地向 Label Studio Enterprise 同步用户、群组与角色映射实现用户开通Provisioning与停用Deprovisioning的全流程托管。读完本文你将掌握 SCIM 集成的前置条件、Okta 与 Entra ID 两套完整的对接配置步骤、群组到角色/工作区/项目的三级映射方法以及 SCIM REST API 端点的用法。SCIM 是什么为什么 Label Studio Enterprise 需要它System for Cross-domain Identity ManagementSCIM是一种广泛使用的开放标准协议用于在组织内部的各个服务与应用之间统一管理访问。其核心价值在于把“谁可以访问什么资源”的身份管理逻辑集中到身份提供商IdP一侧应用侧只需实现标准端点即可自动完成用户身份信息的同步。对 Label Studio Enterprise 而言SCIM 让管理员可以通过 SCIM 提供方统一完成以下工作批量添加用户自动创建 Label Studio 账号移除用户将其用户角色置为 Deactivated从而撤销访问将用户分配到群组将用户从群组中移出将群组映射为组织级或项目级角色。其中关键的一点是群组的定义由 IdP 维护Label Studio Enterprise 只负责维护“群组 → 角色”的映射关系。因此群组与角色的职责边界清晰便于在大型组织中以群组为单位统一放权或收权。Requirements 与 PrerequisitesSCIM 集成的硬性前提协议标准Label Studio Enterprise 采用SCIM Version 2.0标准遵循 SCIM RFC 7644。前置条件在开始配置前必须满足以下两个前提SSO 已配置完成SCIM 交互依赖于既有的 SSO 集成例如 Okta 的 SCIM 集成就是建立在 SAML SSO 之上的Okta 或其他类似的 SSO 提供方的 SCIM 集成都基于 SSO 应用。如果尚未配置 SSO请先按照 Set up SSO 完成配置。准备 Legacy Token需要提供一个与组织Owner 角色绑定的 Legacy tokenSCIM 提供方将用它在请求头中完成身份认证。关于 Legacy token 需要特别注意它是相对“老式”的令牌安全性不如 Personal Access Token因为必须手动撤销在 HTTP API 调用中Legacy token 通常通过Authorization: Token token头传递。而在 SCIM 集成场景下Okta / Entra ID 使用的是Authorization: Bearer token请求头——Label Studio 中Token与Bearer指向相同的令牌但 SCIM 配置中必须使用Bearer前缀而非Token前缀。从源码层面看SCIM 的令牌认证与普通 API 认证有明确的协同处理逻辑在 label_studio/core/middleware.py 中InactivitySessionTimeoutMiddleWare会识别request.is_scim标记并跳过会话超时强制登出逻辑因为 SCIM 请求是通过Authorization头隐式完成用户身份绑定的源码注释明确写着 “scim assign request.user implicitly”并不依赖浏览器会话。这意味着 SCIM 的系统调用不会被组织级的会话超时策略误杀。设置 Okta SCIM 集成分步指南第 1 步将 Label Studio Enterprise 添加为应用在 Okta 中导航到Applications Applications点击Create App Integration。选择SAML 2.0输入应用名称例如Label Studio Enterprise。在Configure SAML中按照 Set up SSO guide 的步骤完成 SAML 配置。确认 Label Studio Enterprise 出现在活跃应用列表中。⚠️重要提醒配置视频演示中使用了userName作为“用户唯一标识字段”但实际配置必须使用email作为唯一标识。否则对 SCIM 集成之前已创建的用户SCIM 将无法正确匹配身份。第 2 步启用 SCIM Provisioning进入Applications Applications选择Label Studio Enterprise。在General标签页勾选Enable SCIM provisioning。进入Provisioning标签页在左侧菜单中选择Integration点击右上角Edit。然后填写以下字段字段值 / 说明SCIM connector base URLhttps://LABEL_STUDIO_BASE_URL/scim/v2/其中LABEL_STUDIO_BASE_URL是 Label Studio Enterprise 实例的 Base URLUnique identifier field for users使用email。Label Studio Enterprise 以此字段作为用户标识Supported provisioning actions勾选以下项Import New Users and Profile Updates、Push New Users、Push Profile Updates、Push GroupsHTTP Header →Authorization: Bearer token填入与 Label Studio Owner 账号绑定的 Legacy token。Label Studio 中Token与Bearer是同一令牌但请求头必须用Bearer而非Token第 3 步配置 SCIM 设置与应用触发动作在应用页面进入Provisioning标签页左侧选择To App点击右上角Edit。启用以下三个项目Create Users创建用户Update User Attributes更新用户属性Deactivate Users停用用户第 4 步将应用分配给单个用户用户页与应用页都可以执行分配操作在应用页面进入Assignments标签页。点击Assign选择Assign to People。勾选要加入 Label Studio Enterprise 的人员。点击Done。点击Done后Okta 会向 Label Studio Enterprise 发送相应的用户创建请求用户随即被自动开通。第 5 步取消用户的分配在应用页面进入Assignments标签页。在左侧选择People。点击目标用户右侧的删除叉号。确认取消分配。第 6 步将应用分配给群组推荐做法通过群组管理访问是最便捷的方式将 Label Studio 分配给群组然后在 Okta 中管理群组成员所有变更都会自动传播到应用侧即 Label Studio Enterprise。在 Label Studio 中配置群组映射在 Label Studio 中点击左上角菜单选择Organization。在右上角选择SCIM。更新角色与工作区映射。注意群组名称必须与 SCIM 提供方发送的群组名完全一致。三种映射类型说明Organization Roles to Groups Mapping组织角色 ↔ 群组将群组映射为组织级角色。组织级角色是用户的默认角色会自动应用到工作区与项目中。角色说明详见 Roles in Label Studio Enterprise。可以将多个群组映射到同一角色。注意Not Activated未激活或 Deactivated已停用用户不计入账号的 seat席位配额。Workspaces to Groups Mapping工作区 ↔ 群组将群组添加为工作区成员。Manager、Reviewer、Annotator 角色的用户只有被加入某工作区成为成员后才能看到该工作区。可以选择已有工作区或新建一个多个群组可映射到同一工作区。Projects to Groups Mapping项目 ↔ 群组将群组映射为项目级角色。项目级角色可以是Annotator、Reviewer或Inherit。一个群组可以在多个项目中映射为不同角色多个群组也可以映射到相同角色和相同项目。若选择Inherit群组将继承“组织角色 ↔ 群组映射”中设置的角色如果群组继承的是 Not Activated 角色用户虽然被映射到项目但在群组同步即用户首次完成身份认证之前并不会真正被分配进项目。将群组分配给应用在 Okta 中打开应用页面进入Assignments标签页。选择Assign → Assign to Groups选择目标群组。将属性Active设为true。保存群组分配后更新会进入队列并发送到 Label Studio。如需立即生效也可以选择将变更即时推送Push到 Label Studio。将群组同步到应用在 Okta 中打开应用页面进入Push Groups标签页。点击Push Groups选择Find groups by name。找到要同步到 Label Studio 的群组。选择Create Group新建群组或选择Link Group关联到已在SCIM Settings页面中指定了同名的既有工作区。取消群组的分配取消群组分配的步骤与取消用户分配类似详见上文“取消用户的分配”在应用页面进入Assignments标签页。在左侧选择Group。点击目标群组右侧的删除叉号。确认取消分配。设置 Microsoft Entra IDAzure ADSCIM 集成Label Studio Enterprise 支持与 Microsoft Entra ID原 Azure AD进行 SCIM 预配。整体流程与 Okta 类似但必须配置特定的属性映射。支持的 SCIM 用户属性白名单Label Studio Enterprise 只支持有限的 SCIM 用户属性集合。在 Entra ID 中配置属性映射时只能包含下表列出的属性SCIM 属性描述是否必需emails[type eq work].value用户邮箱主标识符是userName用户名在 Label Studio 中映射为邮箱是active用户是否处于活跃状态是name.givenName用户名字否name.familyName用户姓氏否⚠️不支持的属性会导致预配失败如果映射了 Label Studio 不支持的属性SCIM 预配期间会返回HTTP 501 (Not Implemented)错误。必须移除 Entra ID 默认携带的以下多余属性映射displayNamepreferredLanguagename.formattedexternalId配置 Entra ID 预配步骤在 Microsoft Entra admin center 左侧选择Enterprise apps。选择你的企业应用。在左侧选择Provisioning。将Tenant URL设置为https://LABEL_STUDIO_BASE_URL/scim/v2/。将Secret Token设置为与 Label Studio Owner 账号绑定的 Legacy token。必须是Legacy token而不是 Personal Access Token且必须与 Owner 角色的用户关联。在Mappings下打开Provision Microsoft Entra ID Users。移除除上述受支持属性之外的所有属性映射仅保留emails[type eq work].value→userPrincipalNameuserName→userPrincipalNameactive→Switch([IsSoftDeleted], , False, True, True, False)name.givenName→givenNamename.familyName→surname在Mappings下打开Provision Microsoft Entra ID Groups如需基于群组进行角色分配请确保其已启用。对于群组预配请按上文“在 Label Studio 中配置群组映射”一节配置 SCIM 群组设置。SCIM 在 Label Studio Enterprise 中的工作流与角色模型SCIM 工作流一览SCIM 支持的用户生命周期操作包括添加用户、移除用户角色置为 Deactivated、将用户分配到群组、从群组移除用户、将群组映射为用户角色。群组定义在 IdP 侧群组到角色的映射定义在 Label Studio 侧——这也是整套架构中职责最清晰的分界。组织级角色与项目级角色通过群组映射可以为用户分配两类角色组织级角色可以是Annotator、Reviewer、Manager、Administrator。每个群组在组织级只能映射为一个角色还可以将群组映射到Deactivated角色这会立即撤销该群组用户的 Label Studio 访问权限。项目级角色可以是Annotator、Reviewer、Inherit继承组织级角色。与组织级不同一个群组可以在多个项目中被分配多个角色例如 Group A 在项目 1 中是 Annotator在项目 2 中可以是 Reviewer。从源码可以印证这套角色模型在 label_studio/core/settings/base.py 中可分配的组织角色枚举AssignableOrganizationRoleEnum包含 Owner、Administrator、Manager、Reviewer、Annotator、Deactivated、Not Activated而RoleSourceEnum明确将角色来源划分为 manual、saml、scim、ldap、api、billing 六类——也就是说通过 SCIM 分配的角色会在系统内被标记为scim来源便于审计与后续的增量同步管理。工作区映射的默认权限模型将群组分配到工作区时群组成员会以“工作区成员”身份加入默认可以访问该工作区下的所有项目。项目内的具体权限取决于其组织级角色如果需要更细粒度控制可以通过 SCIM 的“项目级角色”映射覆盖默认行为。SCIM REST API 端点速查Label Studio 的 SCIM API 基于 django-scim2 库实现可通过标准端点对Users与Groups两类资源进行控制。Users 端点操作端点说明搜索用户GET /scim/v2/Users?filteruserName useremail.comstartIndex1count100用户存在返回200不存在返回404获取用户GET /scim/v2/Users/useremail.com按邮箱获取用户详情创建用户POST /scim/v2/Users/请求体需包含邮箱、密码等用户信息Groups 端点操作端点说明修改群组成员PUT /scim/v2/Groups/group-name更新群组成员列表创建群组POST /scim/v2/Groups/group-name创建群组获取群组GET /scim/v2/Groups/group-name获取群组详情修改群组成员的请求体示例SCIM 2.0 Group 标准 schema{ BODY: { schemas: [urn:ietf:params:scim:schemas:core:2.0:Group], id: group-name, displayName: group-name, members: [ { value: useremail.com, display: useremail.com } ] } }SCIM Settings API群组到角色、群组到工作区的映射除了可以在应用内Organization SCIM页面配置外也可以通过 API 管理获取 SCIM 设置GET /api/scim/settings更新 SCIM 设置POST /api/scim/settings这些 API 与页面操作等价适合在自动化运维或脚本化配置场景下使用。常见注意事项与最佳实践唯一标识必须用email无论是 Okta 还是 Entra ID 集成用户唯一标识字段都应使用邮箱而不是userName否则 SCIM 集成之前已存在的用户无法被正确匹配。请求头必须用 BearerLabel Studio 中Token与Bearer指向同一令牌但 SCIM 提供方Okta / Entra ID必须使用Authorization: Bearer token头使用Token前缀会导致认证失败。Legacy Token 必须绑定 OwnerSCIM 预配令牌必须是 Legacy token而非 Personal Access Token且需与 Owner 角色的用户关联。属性映射白名单Entra ID 集成中只能保留文档列出的 5 个受支持属性多余映射会触发 HTTP 501 错误。群组名一致性Label Studio 侧的群组映射名称必须与 IdP 发送的群组名完全一致否则映射不会生效。席位与状态Not Activated 与 Deactivated 用户不计入 seat 配额可用于在配额紧张时管理用户存量。会话策略豁免从 label_studio/core/middleware.py 的实现可以看出SCIM 系统请求被显式排除在会话超时强制登出逻辑之外这保证了 IdP 触发的后台同步任务不会因会话过期而中断。延伸阅读How SCIM works with Label Studio Enterprise —— SCIM 工作流、API 端点与角色模型的完整说明Set up SSO —— SCIM 集成前必须完成的 SSO 配置Roles in Label Studio Enterprise —— 组织级与项目级角色的权限矩阵Manage users —— 用户与群组管理总览Access tokens —— Legacy Token 的生成与使用说明【免费下载链接】label-studioLabel Studio is a multi-type data labeling and annotation tool with standardized output format项目地址: https://gitcode.com/GitHub_Trending/la/label-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考