OneUptime SCIM 集成基于 SCIM v2.0 的项目与状态页用户自动配发实战【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文以 OneUptime 的 SCIMSystem for Cross-domain Identity Management文档为主体系统讲解如何利用 SCIM v2.0 协议实现用户自动配发provision与自动反配发deprovision。读完你将掌握如何在项目与私有状态页两个通道下启用 SCIM、全部 REST 端点的语义、与 Microsoft Entra ID 和 Okta 的对接步骤以及从源码层面理解 Bearer Token 鉴权、Team 与 Group 的映射关系、默认团队与推送群组Push Groups两种配发模式的差异。SCIM 协议与核心价值OneUptime 实现了 SCIM v2.0 协议用于在身份提供商Identity Provider简称 IdP与 OneUptime 之间自动化管理用户生命周期。对于企业场景SCIM 的价值在于把人员入职/离职、项目成员变更、私有状态页订阅者增删这类高频、易出错的手动操作收敛为 IdP 驱动的声明式同步。具体而言SCIM 集成带来四类收益自动用户配发自动 provision当用户在 IdP 中被分配时自动在 OneUptime 中创建对应账号。自动用户反配发自动 deprovision当用户在 IdP 中解除分配时自动移除其在 OneUptime 中对应项目的访问。用户属性同步在 IdP 与 OneUptime 之间同步用户信息如姓名、邮箱。集中化访问管理直接复用企业现有的身份管理系统来管控 OneUptime 访问无需在每个项目里手工维护成员。这里需要强调一个关键设计OneUptime 将 SCIM 能力拆分为**项目级Project SCIM和状态页级Status Page SCIM**两条独立通道二者各自持有独立的配置实体、独立的scimId与独立的 Bearer Token从而在端点命名空间上互不干扰详见下文架构总览。架构总览双通道设计与鉴权中间件从源码结构看OneUptime 的 SCIM 实现位于 Identity 特性集 下由三部分组成项目级端点SCIM.ts注册在/scim/v2/{projectScimId}/...命名空间下状态页级端点StatusPageSCIM.ts注册在/status-page-scim/v2/{statusPageScimId}/...命名空间下共享鉴权中间件SCIMAuthorization.ts被两类端点共同挂载。所有端点都以中间件SCIMMiddleware.isAuthorizedSCIMRequest作为第一道守卫见 SCIM.ts 中ServiceProviderConfig端点的定义。该中间件的执行链路是从路由参数中提取scimId兼容projectScimId与statusPageScimId两种键名从Authorization: Bearer token请求头中截取令牌见 SCIMAuthorization.ts先按_id bearerToken联合查询项目 SCIM 配置命中则把projectId、scimConfig、类型project-scim写入请求上下文bearerTokenData并放行若未命中再查询状态页 SCIM 配置命中则写入statusPageId与类型status-page-scim两者都未命中则抛出未授权异常见 SCIMAuthorization.ts。这种先项目、后状态页的探测顺序意味着同一套鉴权逻辑可以同时服务两类通道端点处理函数只需从req.bearerTokenData中读取已解析好的projectId与scimConfig即可。这一设计也解释了为什么两条通道必须各自使用不同的 base URL 前缀/scim与/status-page-scim——它们对应不同的配置表与不同的资源语义。项目级 SCIM配置与启用进入设置并创建配置在项目内启用 SCIM 的标准路径进入项目设置打开目标 OneUptime 项目 →项目设置安全SCIM。配置 SCIM 参数勾选自动配发用户Auto Provision Users当用户在 IdP 中被分配时自动创建。勾选自动反配发用户Auto Deprovision Users当用户在 IdP 中解除分配时自动移除。选择新用户将被加入的默认团队Default Teams。复制SCIM Base URL与Bearer Token供 IdP 配置使用。配置 IdP使用 SCIM Base URLhttps://oneuptime.com/scim/v2/{scimId}按 Bearer Token 方式鉴权并映射用户属性邮箱为必填项。SCIM 配置参数详解源码级默认值项目级 SCIM 配置由数据模型 ProjectSCIM.ts 定义其关键字段的默认值与访问控制对理解行为边界至关重要字段类型默认值说明bearerToken长文本必填SCIM 鉴权令牌需妥善保管中间件按_id bearerToken联合校验teams多对多Team无新用户的默认团队集合通过关联表ProjectScimTeam维护autoProvisionUsers布尔true是否自动创建用户见 ProjectSCIM.tsautoDeprovisionUsers布尔true是否自动反配发用户见 ProjectSCIM.tsenablePushGroups布尔false启用推送群组模式替代默认团队见 ProjectSCIM.ts从源码结构看autoProvisionUsers与autoDeprovisionUsers默认均为true因此新建配置即具备完整的配发/反配发能力除非显式关闭而enablePushGroups默认false意味着默认走默认团队模式详见 FAQ 对比。此外该模型通过装饰器声明了能力边界TableEditionAccessControl({ requiresEnterprise: true })表明 SCIM 为企业版能力且TableBillingAccessControl({ create: PlanType.Scale, ... })表明其创建/读取/更新/删除均要求Scale 套餐或更高见 ProjectSCIM.ts。这与文档Scale 套餐或更高的前置要求一致。项目级 SCIM 端点以下为文档明确列出的项目级端点均以/scim/v2/{scimId}为前缀。其中ServiceProviderConfig、Schemas、ResourceTypes是 IdP 在首次对接时用于发现服务能力的元端点其余为资源 CRUD 端点能力方法与路径Service Provider ConfigGET /scim/v2/{scimId}/ServiceProviderConfigSchemasGET /scim/v2/{scimId}/SchemasResource TypesGET /scim/v2/{scimId}/ResourceTypes列出用户GET /scim/v2/{scimId}/Users获取用户GET /scim/v2/{scimId}/Users/{userId}创建用户POST /scim/v2/{scimId}/Users更新用户PUT /scim/v2/{scimId}/Users/{userId}或PATCH /scim/v2/{scimId}/Users/{userId}删除用户DELETE /scim/v2/{scimId}/Users/{userId}列出组GET /scim/v2/{scimId}/Groups获取组GET /scim/v2/{scimId}/Groups/{groupId}创建组POST /scim/v2/{scimId}/Groups更新组PUT /scim/v2/{scimId}/Groups/{groupId}或PATCH /scim/v2/{scimId}/Groups/{groupId}删除组DELETE /scim/v2/{scimId}/Groups/{groupId}除上述元端点外源码还实现了POST /scim/v2/{scimId}/Bulk批量端点见 SCIM.ts允许在一次请求中提交至多 1000 条操作并支持failOnErrors阈值——当累计错误数达到该阈值时中止后续处理这对 IdP 的批量导入场景很有价值。用户资源创建、更新与反配发语义创建用户时POST /Users源码的执行逻辑是见 SCIM.ts从userName或emails[0].value提取邮箱缺失则返回 400若autoProvisionUsers关闭则直接报错自动配发已禁用先按邮箱查询若用户已存在则直接复用不重复建号否则通过UserService.createByEmail创建——注意该路径下账号被标记为isEmailVerified: true且generateRandomPassword: true即 SCIM 创建的账号没有可登录的明文密码其登录应走 SSO 或后续重置若配置了默认团队且未启用推送群组则调用handleUserTeamOperations(add, ...)把用户加入各团队。更新/反配发PUT/PATCH见 SCIM.ts对active字段做了专门处理active false且非推送群组模式 → 把用户从已配置团队中移除不删除账号active true且非推送群组模式 → 把用户重新加入已配置团队同时按需更新email与name。这里的移除由handleUserTeamOperations(remove, ...)完成它只删除TeamMember记录用户在配置团队内的成员关系而不动 User 主账号见 SCIM.ts。这正是 FAQ 中反配发保留账号、仅失去项目访问结论的底层依据。组资源Team 映射与 Unassigned 兜底团队在 OneUptime 中SCIM 的Group 直接映射为项目的 Team由formatTeamForSCIM负责把 Team 序列化为 SCIM Group 表示含members数组每个成员携带value/display/$ref见 SCIM.ts。组操作的几个细节值得注意创建组若同名 Team 已存在则复用返回 200否则新建返回 201若请求携带members则逐个把已存在用户加入该 TeamPUT替换先清空该 Team 全部成员再按请求重建PATCH对members支持replace/add/remove三种操作对displayName支持replace重命名 Team删除组先删除该 Team 的全部成员再删除 Team 本身且若isTeamDeleteable为 false 则拒绝该组不可删除。此外源码引入了一个Unassigned未分配兜底团队当用户在默认团队模式下通过 SCIM 配发、但尚未归属任何真实群组时会被放入自动创建、且无任何权限的 Unassigned 团队见 SCIM.ts一旦该用户被加入某个真实 Group系统会调用removeUserFromUnassignedTeam将其移出兜底团队。这套机制保证了配发即有归属但默认无权限的安全默认。批量操作与错误模型Bulk端点对每条操作单独执行并收集结果method/bulkId/status/location/response单条失败不会中断整个批量除非触发failOnErrors阈值。错误会按异常类型映射为 SCIM 标准错误BadRequestException→ HTTP 400 invalidValueNotFoundException→ HTTP 404 noTarget见 SCIM.ts。每次批量操作还会通过 SCIMLogger.ts 落库审计日志记录执行步骤、成功/失败计数与failOnErrors等上下文便于事后排障。状态页 SCIM私有状态页订阅者管理状态页 SCIM 面向私有状态页Private Status Page的订阅者管理。启用步骤进入状态页设置打开目标 OneUptime 状态页 →状态页设置安全SCIM。配置 SCIM 参数勾选自动配发用户与自动反配发用户复制SCIM Base URL与Bearer Token。配置 IdP使用 SCIM Base URLhttps://oneuptime.com/status-page-scim/v2/{scimId}。从源码看状态页通道由 StatusPageSCIM.ts 实现端点前缀为/status-page-scim/v2/{statusPageScimId}/ServiceProviderConfig、Schemas、ResourceTypes、Bulk等见 StatusPageSCIM.ts其元端点同样复用了 SCIMUtils.ts 中的generateServiceProviderConfig/generateSchemasResponse/generateResourceTypesResponse生成逻辑只是把域参数改为status-page。与项目级最大的差异在于资源语义项目级管理的是项目团队里的用户而状态页级通过StatusPagePrivateUserService管理的是私有状态页的订阅者。二者共用同一套鉴权中间件与 SCIM 工具函数但落库到不同的服务与数据表——这也解释了为什么它们的 base URL 前缀必须不同以避免同一scimId命名空间下的语义混淆。身份提供商对接实战Microsoft Entra ID原 Azure AD前置条件具备 Premium P1 或 P2 许可的 Entra ID 租户自动配发所需具备Scale 套餐或更高的 OneUptime 账号与源码中TableBillingAccessControl的 Scale 门槛一致对 Entra ID 与 OneUptime 均有管理员权限。第 1 步从 OneUptime 获取 SCIM 配置登录 OneUptime 控制台进入项目设置安全SCIM点击创建 SCIM 配置复制SCIM Base URL与Bearer Token。第 2 步在 Entra ID 中创建企业应用登录 Entra 管理中心进入身份应用企业应用点击 新建应用 创建自有应用输入名称如 OneUptime选择集成你未能在目录中找到的任意其他应用点击创建。第 3 步配置 SCIM 配发在该 OneUptime 企业应用中进入配发Provisioning将配发模式设为自动Automatically在管理员凭据中租户 URL填入 OneUptime 的 SCIM Base URL机密令牌Secret Token填入 OneUptime 的 Bearer Token点击测试连接点击保存。Okta前置条件具备配发能力的 Okta 租户具备Scale 套餐或更高的 OneUptime 账号对 Okta 与 OneUptime 均有管理员权限。第 4 步配置 SCIM 连接进入配发Provisioning标签页在左侧边栏点击集成Integrations点击配置 API 集成Configure API Integration启用启用 API 集成配置SCIM Connector 基础 URL填入 OneUptime 的 SCIM Base URL用户唯一标识字段填userName与源码中从userName提取邮箱的解析逻辑对应鉴权模式选择HTTP 头Header授权Authorization填Bearer {your-bearer-token}点击测试 API 凭据点击保存。鉴权机制Bearer Token 中间件两条通道共享 SCIMAuthorization.ts 中间件其要点已在前文架构总览展开这里补充两点工程细节令牌与 scimId 联合校验中间件不是仅比对令牌而是以_id scimId AND bearerToken token作为数据库查询条件。这意味着即便令牌正确若scimId不匹配也会落到未找到配置而返回未授权——令牌与命名空间被绑定校验避免跨配置越权。失败路径的遥测中间件用CaptureSpan()装饰器包裹并在catch中显式调用SpanUtil.recordExceptionOnCurrentSpan(err)。源码注释解释了原因Express 4 不会捕获异步中间件的 rejection若不在自身 span 上记录该异常在链路追踪里将不可见见 SCIMAuthorization.ts。常见问题与行为语义以下问题直接继承自文档并用源码行为加以印证。问当用户被反配发deprovision时会发生什么无论是DELETE请求还是把active置为false该用户都只会被从 SCIM 配置中指定的团队里移除其 OneUptime 账号本身被保留但失去对应项目访问。这与源码中handleUserTeamOperations(remove, ...)仅删除TeamMember记录、不触碰 User 主账号的行为一致。问能否不使用 SSO 单独使用 SCIM可以。SCIM 与 SSO 是两个独立能力你可以只用 SCIM 做用户配发同时仍允许用户以 OneUptime 密码或其他认证方式登录。需要注意的源码事实是SCIM 自动创建的账号会带generateRandomPassword: true即没有可登录的明文密码因此若不走 SSO实际登录体验取决于是否额外设置了密码。问对于已存在于 OneUptime 中的用户该如何处理当 SCIM 试图创建按邮箱匹配一个已存在的用户时OneUptime 不会重复建号而是直接把该用户加入所配置的默认团队。这正是创建用户路径中先按邮箱查询、命中则复用的逻辑见 SCIM.ts。问默认团队Default Teams与推送群组Push Groups有何区别默认团队所有通过 SCIM 配发的用户都会被加入同一组预定义的团队。对应ProjectSCIM.teams字段由handleUserTeamOperations统一处理。推送群组Push Groups团队成员关系改由你的 IdP 驱动因此不同用户可依据其在 IdP 中的群组归属分别落到 OneUptime 的不同 Team。对应enablePushGroups字段默认false。从源码看一旦启用推送群组默认团队路径的加/移出团队分支会被跳过改由 Group 端点POST/PUT/PATCH /Groups及members操作来维护成员关系。延伸阅读本文引用的核心源码与文档均位于仓库内便于继续深入项目级 SCIM 端点实现App/FeatureSet/Identity/API/SCIM.ts状态页级 SCIM 端点实现App/FeatureSet/Identity/API/StatusPageSCIM.tsSCIM 鉴权中间件Common/Server/Middleware/SCIMAuthorization.ts项目 SCIM 数据模型Common/Models/DatabaseModels/ProjectSCIM.tsSCIM 响应/解析工具App/FeatureSet/Identity/Utils/SCIMUtils.tsSCIM 审计日志App/FeatureSet/Identity/Utils/SCIMLogger.ts文档源德语App/FeatureSet/Docs/Content/de/identity/scim.md文档源英语App/FeatureSet/Docs/Content/en/identity/scim.md适用前提与限制说明SCIM 为 OneUptime 企业版能力且数据访问要求 Scale 套餐或更高端点默认值如autoProvisionUsers/autoDeprovisionUsers默认开启、enablePushGroups默认关闭以当前仓库 ProjectSCIM.ts 中定义的列默认值为准。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考