OneUptime SCIM v2.0 集成实战：基于 SCIM 协议实现用户与订阅者的自动化生命周期管理

OneUptime SCIM v2.0 集成实战基于 SCIM 协议实现用户与订阅者的自动化生命周期管理【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 是开源的监控与可观测性平台其内置的 SCIMSystem for Cross-domain Identity Managementv2.0 服务端实现可以让 Microsoft Entra ID原 Azure AD、Okta 等企业身份提供商IdP自动完成用户的创建、更新与移除将成员进出项目的流程与企业的身份治理体系完全对齐。本文以 SCIM 官方文档 为骨架结合 Identity FeatureSet 下的真实源码实现完整讲解项目 SCIM 与状态页 SCIM 的配置方法、全部 REST 端点、Entra ID / Okta 分步配置以及底层的认证、去重与团队归属机制帮助你在企业中一次性打通从 IdP 分配到项目权限的全链路。SCIM 集成能带来什么SCIM v2.0 是一套标准化的用户与组管理 REST API 协议OneUptime 作为 SCIM 服务端向 IdP 暴露用户User与组Group两类资源。启用后集成提供四项核心能力用户自动开通Provisioning用户在 IdP 中被分配到 OneUptime 应用时自动在 OneUptime 创建对应账号并加入指定团队用户自动回收Deprovisioning用户在 IdP 中被移除时自动从 OneUptime 项目团队中移除收回访问权限用户属性同步userName、displayName、name.givenName、name.familyName、emails、active等属性随 IdP 侧变更持续同步集中化访问治理无需在 OneUptime 后台手工增删成员所有成员变更都从现有身份管理体系发起审计可追溯。从数据模型看SCIM 配置的核心字段定义在 ProjectSCIM 模型 中包括bearerToken认证令牌、autoProvisionUsers自动开通默认true、autoDeprovisionUsers自动回收默认true、enablePushGroups组推送默认false以及teams默认团队多对多关联这些开关正是下面所有配置动作的落点。项目 SCIM管理团队成员项目 SCIM 面向团队成员这一资源让 IdP 直接管理谁属于哪个 OneUptime 项目。项目 SCIM 配置步骤进入你的 OneUptime 项目导航到项目设置Ajustes del proyecto 安全Seguridad SCIM配置 SCIM 选项开启自动开通用户Aprovisionar usuarios automáticamente用户在 IdP 中被分配后自动加入项目开启自动回收用户Desaprovisionar usuarios automáticamente用户在 IdP 中被移除后自动移出项目选择默认团队Equipos predeterminados新用户会被自动加入这些团队复制SCIM 基础 URLURL base de SCIM与Bearer 令牌Token de portador供 IdP 侧配置使用配置身份提供商使用 SCIM 基础 URLhttps://oneuptime.com/scim/v2/{scimId}采用 Bearer Token 认证映射用户属性邮箱为必填项。需要说明的是官方 SaaS 地址以https://oneuptime.com开头而自托管部署时则指向你自己的实例域名{scimId}是 SCIM 配置的唯一 ID同时充当 URL 中的资源标识与认证查询键认证中间件正是用它连同 Bearer Token 一起在数据库中查找对应配置见 SCIMAuthorization 中间件。项目 SCIM 端点清单项目 SCIM 的全部路由定义在 SCIM.ts端点如下端点方法说明/scim/v2/{scimId}/ServiceProviderConfigGET服务提供商能力声明/scim/v2/{scimId}/SchemasGET可用资源 Schema/scim/v2/{scimId}/ResourceTypesGET可用资源类型/scim/v2/{scimId}/UsersGET列出用户/scim/v2/{scimId}/Users/{userId}GET获取单个用户/scim/v2/{scimId}/UsersPOST创建用户/scim/v2/{scimId}/Users/{userId}PUT / PATCH更新用户/scim/v2/{scimId}/Users/{userId}DELETE删除用户/scim/v2/{scimId}/GroupsGET列出组/scim/v2/{scimId}/Groups/{groupId}GET获取单个组/scim/v2/{scimId}/GroupsPOST创建组/scim/v2/{scimId}/Groups/{groupId}PUT / PATCH更新组/scim/v2/{scimId}/Groups/{groupId}DELETE删除组除上述端点外源码还实现了Bulk 批量操作端点POST /scim/v2/{scimId}/BulkSCIM.ts用于一次请求内批量创建/更新/删除用户与组其failOnErrors参数控制错误容忍阈值。在自托管场景下这些端点前缀对应实际的 API 网关路径项目 SCIM 与状态页 SCIM 的差异仅体现在 URL 前缀/scim/v2与/status-page-scim/v2上。项目 SCIM 用户生命周期IdP 侧分配用户用户在 IdP 中被分配到 OneUptime 应用SCIM 开通IdP 调用 OneUptime SCIM API 创建用户加入团队用户被自动加入已配置的默认团队若未开启组推送授予访问权用户获得项目访问权限IdP 侧解除分配用户在 IdP 中被移除SCIM 回收IdP 调用 OneUptime SCIM API 移除用户撤销访问权用户失去项目访问权限。这一生命周期在源码中对应handleUserTeamOperations函数SCIM.ts开通时逐个检查并创建TeamMember记录hasAcceptedInvitation true即无需再次接受邀请回收时按teamId批量删除成员记录。值得注意的是源码中删除用户并不会物理删除 OneUptime 的 User 账号而是将其从 SCIM 配置关联的团队中移除这与文档 FAQ 中的说明完全一致。状态页 SCIM管理私有状态页订阅者状态页 SCIM 面向私有状态页Private Status Page的订阅者资源让 IdP 管理谁能够访问私密状态页。状态页 SCIM 配置步骤进入你的状态页导航到状态页Página de estado 安全Seguridad SCIM配置 SCIM 选项开启自动开通订阅者订阅者在 IdP 中被分配后自动成为状态页订阅者开启自动回收订阅者订阅者在 IdP 中被移除后自动失去订阅资格复制SCIM 基础 URL与Bearer 令牌配置身份提供商使用 SCIM 基础 URLhttps://oneuptime.com/status-page-scim/v2/{scimId}采用 Bearer Token 认证映射用户属性邮箱为必填项。状态页 SCIM 端点清单状态页 SCIM 的路由定义在 StatusPageSCIM.ts与项目 SCIM 相比不支持组Groups资源端点方法说明/status-page-scim/v2/{scimId}/ServiceProviderConfigGET服务提供商能力声明/status-page-scim/v2/{scimId}/SchemasGET可用资源 Schema/status-page-scim/v2/{scimId}/ResourceTypesGET可用资源类型/status-page-scim/v2/{scimId}/UsersGET列出订阅者/status-page-scim/v2/{scimId}/Users/{userId}GET获取单个订阅者/status-page-scim/v2/{scimId}/UsersPOST创建订阅者/status-page-scim/v2/{scimId}/Users/{userId}PUT / PATCH更新订阅者/status-page-scim/v2/{scimId}/Users/{userId}DELETE删除订阅者状态页 SCIM 用户生命周期IdP 侧分配用户用户在 IdP 中被分配到 OneUptime 状态页应用SCIM 开通IdP 调用 SCIM API 创建订阅者授予访问权用户可访问私有状态页IdP 侧解除分配用户在 IdP 中被移除SCIM 回收IdP 调用 SCIM API 删除订阅者撤销访问权用户失去状态页访问权限。身份提供商配置Microsoft Entra ID原 Azure ADMicrosoft Entra ID 的自动开通能力依赖Premium P1 或 P2 许可。OneUptime 侧需Scale 及以上计划对应 ProjectSCIM 模型的计费访问控制创建/读取/更新/删除均要求PlanType.Scale同时需要 Entra ID 与 OneUptime 两侧的管理员权限。第 1 步获取 OneUptime SCIM 配置登录 OneUptime 控制台进入项目设置 安全 SCIM点击创建 SCIM 配置Crear configuración SCIM输入描述性名称例如 Microsoft Entra ID 开通配置以下选项自动开通用户开启后自动创建用户自动回收用户开启后自动删除用户默认团队选择新用户要加入的团队启用组推送Habilitar grupos push如需通过 Entra ID 组管理团队成员资格则开启保存配置复制SCIM 基础 URL与Bearer 令牌后续用于 Entra ID。第 2 步在 Microsoft Entra ID 创建企业应用登录 Microsoft Entra 管理中心进入标识 应用程序 企业应用程序点击 新建应用程序点击 创建你自己的应用程序输入名称例如 OneUptime选择集成库中找不到的任何其他应用程序非库应用点击创建。第 3 步配置 SCIM 开通在 OneUptime 企业应用中进入开通点击开始将开通模式设为自动在管理员凭据中租户 URL填入 OneUptime 的 SCIM 基础 URL例如https://oneuptime.com/api/identity/scim/v2/{your-scim-id}机密令牌填入 OneUptime 的 Bearer 令牌点击测试连接验证配置点击保存。第 4 步配置属性映射在开通区域点击映射点击预配 Azure Active Directory 用户配置以下属性映射Azure AD 属性OneUptime SCIM 属性是否必填userPrincipalNameuserName是mailemails[type eq work].value推荐displayNamedisplayName推荐givenNamename.givenName可选surnamename.familyName可选Switch([IsSoftDeleted], , False, True, True, False)active推荐删除不必要的映射以简化开通点击保存。其中active属性的Switch表达式会把 Entra ID 的软删除状态映射为 SCIM 的active布尔值。在 OneUptime 源码中active: false的用户更新会触发从配置团队中移除成员的操作active: true则触发加入团队的操作SCIM.ts且只有当autoDeprovisionUsers开启时才执行回收动作。第 5 步配置组开通可选若在 OneUptime 开启了组推送回到映射点击预配 Azure Active Directory 组将已启用设为是开启组开通配置以下属性映射Azure AD 属性OneUptime SCIM 属性displayNamedisplayNamemembersmembers点击保存。第 6 步分配用户与组在企业应用中进入用户和组点击 添加用户/组选择要开通到 OneUptime 的用户和/或组点击分配。第 7 步启动开通进入开通 概述点击启动开通首次开通周期开始首次同步最长可能需要 40 分钟在开通日志中监控错误。Entra ID 常见问题排查连接测试失败确认 SCIM 基础 URL 包含/api/identity前缀且 Bearer 令牌正确用户未开通检查用户是否已分配给应用、属性映射是否正确开通错误查看 Entra ID 开通日志中的具体错误信息同步延迟首次开通最长 40 分钟后续每 40 分钟执行一次周期同步。身份提供商配置OktaOkta 需要具备开通能力生命周期管理功能OneUptime 侧同样要求 Scale 及以上计划并需要双侧管理员权限。第 1 步获取 OneUptime SCIM 配置登录 OneUptime 控制台进入项目设置 安全 SCIM点击创建 SCIM 配置输入描述性名称例如 Okta 开通配置选项与 Entra ID 相同自动开通、自动回收、默认团队、启用组推送保存配置复制SCIM 基础 URL与Bearer 令牌。第 2 步创建或配置 Okta 应用已有 SSO 应用登录 Okta 管理控制台进入应用程序 应用程序找到并选择已有的 OneUptime 应用。新建应用进入应用程序 应用程序点击创建应用集成选择SAML 2.0并点击下一步输入应用名称 OneUptime完成 SAML 配置参见 SSO 文档点击完成。第 3 步启用 SCIM 开通在 OneUptime 应用的常规选项卡在应用设置区域点击编辑在开通中选择SCIM点击保存会出现新的开通选项卡。第 4 步配置 SCIM 连接进入开通选项卡点击左侧边栏的集成点击配置 API 集成勾选启用 API 集成配置以下内容SCIM 连接器基本 URL填入 OneUptime 的 SCIM 基础 URL例如https://oneuptime.com/api/identity/scim/v2/{your-scim-id}用户唯一标识字段填入userName支持的预配操作按需勾选导入新用户和配置文件更新推送新用户推送配置文件更新推送组如使用基于组的开通身份验证模式选择HTTP 标头Encabezado HTTP授权填入Bearer {your-bearer-token}替换为真实令牌点击测试 API 凭据验证连接点击保存。第 5 步为应用配置开通在开通选项卡点击左侧边栏的到应用A la aplicación点击编辑启用以下选项创建用户开通新用户更新用户属性同步属性变更停用用户用户被解除分配时回收点击保存。第 6 步配置属性映射滚动到属性映射核对或配置以下映射Okta 属性OneUptime SCIM 属性方向userNameuserNameOkta → 应用user.emailemails[primary eq true].valueOkta → 应用user.firstNamename.givenNameOkta → 应用user.lastNamename.familyNameOkta → 应用user.displayNamedisplayNameOkta → 应用删除不必要的映射如有改动点击保存。第 7 步配置组推送可选若在 OneUptime 开启了组推送进入推送组Grupos de inserción选项卡点击 推送组选择按名称搜索组或按规则搜索组搜索并选择要推送的组点击保存。第 8 步分配用户进入分配选项卡点击分配 分配给人员或分配给组选择要开通的用户或组逐一点击分配点击完成。第 9 步验证开通在 Okta 管理控制台进入报告 系统日志筛选与 OneUptime 应用相关的事件确认开通事件成功在 OneUptime 中核对用户已被创建。Okta 常见问题排查API 凭据测试失败检查 SCIM 基础 URL 与 Bearer 令牌是否正确用户未开通确认用户已分配给应用且开通已启用用户重复确保userName唯一并正确映射到邮箱组推送失败检查组是否存在且成员关系正确错误 401 未授权在 OneUptime 重新生成 Bearer 令牌并更新到 Okta。其他身份提供商与通用配置OneUptime 的 SCIM 实现遵循 SCIM v2.0 规范理论上兼容任意符合规范的 IdP。通用配置要点SCIM 基础 URL项目用https://oneuptime.com/api/identity/scim/v2/{scim-id}状态页用https://oneuptime.com/api/identity/status-page-scim/v2/{scim-id}认证HTTP Bearer Token必填用户属性userName必须为合法邮箱地址支持的操作针对用户与组的 GET、POST、PUT、PATCH、DELETE。受支持的 SCIM 端点端点方法说明/ServiceProviderConfigGETSCIM 服务器能力声明/SchemasGET可用资源 Schema/ResourceTypesGET可用资源类型/UsersGET、POST列出与创建用户/Users/{id}GET、PUT、PATCH、DELETE管理单个用户/GroupsGET、POST列出与创建组/团队仅项目 SCIM/Groups/{id}GET、PUT、PATCH、DELETE管理单个组仅项目 SCIMServiceProviderConfig的生成逻辑SCIMUtils.ts向 IdP 声明了以下能力支持patchPATCH 操作、支持bulk最多 1000 个操作、最大负载 1MB、支持filter最多返回 200 条、支持sort、不支持changePassword与etag认证方案为httpbearer。这些声明决定了 IdP 侧可用的高级能力如 Okta 的批量同步、Entra ID 的按条件过滤。SCIM 用户 Schema{ schemas: [urn:ietf:params:scim:schemas:core:2.0:User], userName: userexample.com, name: { givenName: John, familyName: Doe, formatted: John Doe }, displayName: John Doe, emails: [ { value: userexample.com, type: work, primary: true } ], active: true }该 Schema 由 formatUserForSCIM 生成userName恒等于用户邮箱name子对象由完整姓名拆分givenName取首词、familyName取其余部分、formatted为完整名emails统一标记为type: work且primary: true。SCIM 组 Schema{ schemas: [urn:ietf:params:scim:schemas:core:2.0:Group], displayName: Engineering Team, members: [ { value: user-id-here, display: userexample.com } ] }项目 SCIM 中SCIM 组Group直接映射为 OneUptime 团队Team。formatTeamForSCIMSCIM.ts会把团队名映射为displayName、团队成员映射为members数组value为用户 ID、display为邮箱、$ref为用户的 SCIM 资源定位。列表接口出于性能考虑默认不返回成员明细。源码级原理剖析认证与鉴权Bearer Token scimId 双因子校验所有 SCIM 请求首先经过 SCIMAuthorization 中间件。该中间件从 URL 中提取projectScimId或statusPageScimId从Authorization头解析Bearer令牌然后分别在ProjectSCIM与StatusPageSCIM配置表中按{_id, bearerToken}联合查询。只有 scimId 与令牌同时匹配请求才会被放行并将解析出的scimConfig、projectId、statusPageId挂载到请求对象上供后续路由使用两者都不匹配时返回 401 未授权。这意味着令牌泄露时可立即在 OneUptime 侧重新生成令牌实现失效对应 Okta 排查指南中的401 未授权处理。用户去重以邮箱为唯一键当 SCIM 尝试创建已存在的用户时按邮箱匹配OneUptime 不会创建重复账号而是直接把该用户加入配置的默认团队。源码中创建用户的流程SCIM.ts先按email查询User存在则复用不存在才调用UserService.createByEmail生成随机密码、标记邮箱已验证随后在未开启组推送且配置了默认团队时执行加入团队操作。这也解释了 FAQ 中SCIM 与既有用户如何共存的答案。组推送Push Groups与默认团队的分工默认团队所有经 SCIM 开通的用户统一加入相同的预定义团队粒度粗、配置简单组推送团队归属由 IdP 侧组决定不同用户按 IdP 组差异进入不同团队粒度细。源码中当enablePushGroups为真时创建/更新用户路径会跳过默认团队操作改由 Groups 端点的成员管理驱动反之则由handleUserTeamOperations统一处理。另外还有一个细节源码定义了名为Unassigned的特殊团队SCIM.ts描述为通过 SCIM 开通但未分配任何组的用户被放入此团队该团队无任何权限。当用户通过组推送进入真实团队时会自动从Unassigned团队移出——这是组推送模式下防止无组用户获得默认权限的安全兜底机制。查询过滤与分页列表接口支持 SCIM 过滤表达式userName eq ...用户与displayName eq ...组SCIM.ts、SCIM.ts分页遵循 SCIM 规范startIndex从 1 开始count默认 100、上限 200parseSCIMQueryParams用户列表会按用户 ID 去重防止同一用户因多团队成员关系被重复返回SCIM.ts。一个值得注意的行为当GET /Users?filteruserName eq xxx匹配不到用户且autoProvisionUsers开启时服务端会立即按该邮箱创建用户并加入默认团队SCIM.ts。这是为了兼容 Entra ID 等 IdP 先查询后创建的开通模式而若userName过滤值不是合法邮箱格式例如 Entra ID 的 GUID则返回空列表由 IdP 后续以真实邮箱发起创建SCIM.ts。PATCH 语义支持用户与组资源均支持PUT全量替换与PATCH增量修改。extractUserUpdateFromSCIMSCIMUtils.ts实现了 SCIM PATCH 的add/replace/remove三种操作语义覆盖active、userName、emails含emails[type eq work].value这类子属性路径的增量更新组资源的 PATCH 则支持对members的增删替换以及对displayName的重命名SCIM.ts。特别地PATCH 中移除active属性不会被解释为停用用户避免误回收。审计日志与排障每次 SCIM 操作都会写入结构化的审计日志SCIMLogger.ts记录operationType、status、HTTP 方法与状态码、请求/响应体、受影响的用户邮箱与组名、执行步骤序列以及附加上下文。日志写入前会执行敏感数据脱敏bearerToken、password、authorization、token、secret等键名递归打码既满足审计需求又避免令牌泄露。当 IdP 侧开通报错时这些日志OneUptime 后台的 SCIM 日志页与 IdP 侧的开通日志可以互为印证、定位问题环节。常见问题解答用户被回收后会怎样当用户被回收无论是通过 DELETE 请求还是设置active: false该用户会从 SCIM 设置中配置的团队中被移除。用户账号本身仍保留在 OneUptime但失去对该项目的访问权限。这一行为与源码实现一致——回收仅删除TeamMember关系不删除User实体。能否在不启用 SSO 的情况下使用 SCIM可以。SCIM 与 SSO 是相互独立的功能可以用 SCIM 做用户开通同时允许用户使用 OneUptime 密码或其他认证方式登录。如何管理 OneUptime 中已存在的用户SCIM 尝试创建已存在的用户时按邮箱匹配OneUptime 会直接将其加入配置的默认团队而不是创建重复账号。默认团队与组推送有什么区别默认团队所有经 SCIM 开通的用户加入相同的预定义团队组推送团队归属由 IdP 管理不同用户可依据其在 IdP 中的组成员关系进入不同团队。开通同步的频率如何取决于身份提供商Microsoft Entra ID首次同步最长 40 分钟后续每 40 分钟一次Okta大多数操作近乎实时另有周期性全量同步。结语从配置界面到 REST 端点、从 Entra ID/Okta 的分步接入到源码级的去重、回收与组推送机制OneUptime 的 SCIM 实现覆盖了企业身份治理的完整闭环。无论你是想用默认团队快速开通成员还是借助组推送实现精细化的按组授权都可以依据 SCIM 文档、项目 SCIM 实现 与 状态页 SCIM 实现 在自托管环境中复现并验证全部行为。落地时只需记住三条主线邮箱是用户唯一键、Bearer 令牌是唯一凭据、团队归属由默认团队 / 组推送两种模式决定。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考