OneUptime SCIM 2.0 身份供给集成指南项目与状态页的用户自动供给、取消供给及 Entra ID / Okta 配置【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 是一款开源的监控与可观测性平台本文围绕其内置的 SCIMSystem for Cross-domain Identity Management跨域身份管理系统2.0 协议实现讲解如何借助身份提供方IdP如 Microsoft Entra ID、Okta实现用户在 OneUptime 项目与私有状态页中的自动供给Provisioning与取消供给Deprovisioning。读完本文你将掌握 OneUptime 中 SCIM 配置的完整操作流程、两类 SCIM 端点与用户生命周期模型并能够独立完成 Entra ID 与 Okta 的端到端集成及常见故障排查。一、OneUptime 中的 SCIM 是什么SCIM 是一种基于 HTTP 的标准协议用于在身份域之间自动交换用户与组身份信息。OneUptime 实现了SCIM 2.0规范RFC 7643 / RFC 7644允许组织身份提供方IdP——例如 Azure AD现 Microsoft Entra ID、Okta 以及其他企业身份系统——自动管理用户对 OneUptime 项目与状态页的访问。在 OneUptime 中启用 SCIM 后可以获得以下能力自动供给用户Auto Provision Users当用户在 IdP 中被分配给 OneUptime 应用时系统自动在 OneUptime 中创建对应用户自动取消供给用户Auto Deprovision Users当用户在 IdP 中被取消分配时自动将其从 OneUptime 中移除访问用户属性同步Attribute Sync保持 IdP 与 OneUptime 之间的用户信息一致集中式访问管理直接通过已有的企业身份管理系统管理对 OneUptime 的访问无需逐一手动操作。OneUptime 提供了两套相互独立的 SCIM 实现类型管理对象入口路径项目 SCIMProject SCIM项目内的团队成员Project SettingsSecuritySCIM状态页 SCIMStatus Page SCIM私有状态页的订阅者Status PageSecuritySCIM从源码层面看这两套实现分别对应两个独立的数据模型ProjectSCIM 与 StatusPageSCIM并各自拥有独立的审计日志模型ProjectSCIMLog与StatusPageSCIMLog。二、项目 SCIMProject SCIM配置指南项目 SCIM 使 IdP 能够管理 OneUptime 项目内的团队成员。以下为完整配置流程。2.1 在 OneUptime 中创建 SCIM 配置进入项目设置登录 OneUptime 控制台进入目标项目导航至Project SettingsSecuritySCIM创建 SCIM 配置点击Create SCIM Configuration填写一个友好的配置名称例如 Microsoft Entra ID Provisioning 或 Okta Provisioning配置关键选项Auto Provision Users启用后当用户在 IdP 中被分配时自动创建到 OneUptimeAuto Deprovision Users启用后当用户在 IdP 中被取消分配时自动移除访问Default Teams选择新供给用户默认加入的团队Enable Push Groups可选启用后改由 IdP 通过组推送Push Groups来管理团队归属而不是统一放入默认团队保存并复制凭据保存配置后复制SCIM Base URL与Bearer Token这两个值将用于后续 IdP 侧的配置。源码佐证在 ProjectSCIM.ts 中可以看到autoProvisionUsers与autoDeprovisionUsers字段的数据库默认值均为true而enablePushGroups默认值为falseteams字段通过ProjectScimTeam多对多关联表与 Team 关联。name字段以projectId为唯一键约束UniqueColumnBy(projectId)即每个项目下 SCIM 配置名称不可重复。2.2 在 IdP 侧配置 SCIM在 IdP如 Entra ID、Okta中新建 SCIM 应用时使用以下信息SCIM Base URLhttps://oneuptime.com/scim/v2/{scimId}自托管部署请替换为你的 OneUptime 域名认证方式HTTP Bearer Token即携带Authorization: Bearer {token}请求头用户映射将 IdP 用户属性映射到 SCIM 属性其中email 为必填项对应 SCIM 的userName。2.3 项目 SCIM 端点清单OneUptime 项目 SCIM 实现遵循 SCIM 2.0 规范暴露以下标准端点均需在请求头中携带 Bearer Token端点方法说明/scim/v2/{scimId}/ServiceProviderConfigGET返回服务提供方能力配置/scim/v2/{scimId}/SchemasGET返回可用资源 schema/scim/v2/{scimId}/ResourceTypesGET返回可用资源类型/scim/v2/{scimId}/UsersGET / POST列出 / 创建用户/scim/v2/{scimId}/Users/{userId}GET / PUT / PATCH / DELETE读取 / 更新 / 删除单个用户/scim/v2/{scimId}/GroupsGET / POST列出 / 创建团队组/scim/v2/{scimId}/Groups/{groupId}GET / PUT / PATCH / DELETE读取 / 更新 / 删除单个团队组源码佐证这些路由定义在 App/FeatureSet/Identity/API/SCIM.ts 中例如router.get(/scim/v2/:projectScimId/ServiceProviderConfig, SCIMMiddleware.isAuthorizedSCIMRequest, ...)。此外该文件还实现了标准端点之外的POST /scim/v2/:projectScimId/Bulk批量操作端点用于一次性处理多笔用户/组操作批量上限为 1000 条操作。2.4 项目 SCIM 用户生命周期一次完整的 SCIM 供给 / 取消供给周期如下IdP 中分配用户管理员在 IdP 中将用户分配给 OneUptime 应用触发 SCIM 供给IdP 调用 OneUptime 的 SCIM API 创建用户加入默认团队用户自动被加入 OneUptime 中预先配置的默认团队若未启用 Push Groups授予访问权限用户即可访问 OneUptime 项目IdP 中取消分配管理员在 IdP 中取消对用户的分配触发 SCIM 取消供给IdP 调用 SCIM API 移除该用户访问失效用户失去对项目的访问权限。源码佐证在 SCIM.ts 中handleUserTeamOperations函数实现了 add/remove 两种团队操作添加成员时通过TeamMemberService.create写入TeamMember记录并设置hasAcceptedInvitation true、invitationAcceptedAt为当前时间移除时则通过TeamMemberService.deleteBy按projectId userId teamId ∈ teamsIds批量删除。值得注意的是当用户创建时若autoProvisionUsers关闭API 会直接抛出 Auto-provisioning is disabled for this project 的 400 错误。三、状态页 SCIMStatus Page SCIM配置指南状态页 SCIM 面向私有状态页Private Status Page的订阅者管理使 IdP 可以自动管理谁能订阅查看你的私有状态页。3.1 配置步骤进入状态页设置打开你的 OneUptime 状态页导航至Status PageSecuritySCIM配置 SCIM 设置Auto Provision Users启用后当订阅者在 IdP 中被分配时自动创建为状态页用户Auto Deprovision Users启用后当订阅者在 IdP 中被取消分配时自动移除复制SCIM Base URL与Bearer Token配置 IdPSCIM Base URL 使用https://oneuptime.com/status-page-scim/v2/{scimId}使用 Bearer Token 认证映射用户属性email 必填。3.2 状态页 SCIM 端点清单端点方法说明/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 / POST列出 / 创建订阅者/status-page-scim/v2/{scimId}/Users/{userId}GET / PUT / PATCH / DELETE管理单个订阅者与项目 SCIM 不同状态页 SCIM不提供 Groups 相关端点——订阅者不属于团队体系因此无需组管理。3.3 状态页 SCIM 用户生命周期IdP 中分配订阅者触发 SCIM 供给IdP 调用 SCIM API 创建订阅者授予访问权限订阅者可以访问私有状态页IdP 中取消分配触发 SCIM 取消供给IdP 调用 SCIM API 移除订阅者访问失效订阅者失去对私有状态页的访问。源码佐证StatusPageSCIM.ts 模型同样包含autoProvisionUsers默认true与autoDeprovisionUsers默认true字段并通过statusPageId关联到具体的 StatusPage 资源。其 CRUD 端点为/status-page-scim权限基于Permission.CreateStatusPageSSO等状态页 SSO 相关权限。四、身份提供方配置详解4.1 Microsoft Entra ID原 Azure ADEntra ID 提供企业级身份管理与完善的 SCIM 供给能力。OneUptime 账户需为Scale 及以上套餐Entra ID 侧需要Premium P1 或 P2 许可证自动供给必需并且需要对两侧拥有管理员访问权限。Step 1从 OneUptime 获取 SCIM 配置登录 OneUptime 仪表盘进入Project SettingsSecuritySCIM点击Create SCIM Configuration输入友好名称如 Microsoft Entra ID Provisioning配置Auto Provision Users、Auto Deprovision Users、Default Teams如需通过 Entra ID 组管理团队归属则开启Enable Push Groups保存后复制SCIM Base URL与Bearer Token。Step 2在 Entra ID 中创建企业应用登录 Microsoft Entra 管理中心进入IdentityApplicationsEnterprise applications点击 New application然后选择 Create your own application输入名称如 OneUptime选择Integrate any other application you dont find in the gallery (Non-gallery)点击Create。Step 3配置 SCIM 供给进入刚创建的企业应用打开Provisioning并点击Get started将Provisioning Mode设置为Automatic在Admin Credentials中填写Tenant URLOneUptime 提供的 SCIM Base URL例如https://oneuptime.com/api/identity/scim/v2/{your-scim-id}Secret TokenOneUptime 提供的 Bearer Token点击Test Connection验证配置然后Save。Step 4配置属性映射Mappings在 Provisioning 中点击Mappings选择Provision Azure Active Directory Users按下表配置属性映射Azure AD 属性OneUptime SCIM 属性是否必填userPrincipalNameuserName是mailemails[type eq work].value推荐displayNamedisplayName推荐givenNamename.givenName可选surnamename.familyName可选Switch([IsSoftDeleted], , False, True, True, False)active推荐移除不需要的映射以简化供给完成后Save。说明active属性决定用户是否处于启用状态Entra ID 使用表达式Switch([IsSoftDeleted], ...)将软删除状态映射为active的布尔值。OneUptime 侧会对该字段做严格的语义解析详见后文SCIM 属性解析原理。Step 5可选配置组供给若在 OneUptime 中启用了Push Groups回到Mappings点击Provision Azure Active Directory Groups将Enabled设为Yes配置映射displayName→displayNamemembers→membersSave。Step 6分配用户与组进入企业应用的Users and groups点击 Add user/group选择要供给到 OneUptime 的用户和/或组点击Assign。Step 7启动供给进入ProvisioningOverview点击Start provisioning首次供给周期随即开始——首次同步最长可能需要 40 分钟通过Provisioning logs监控任何错误。Entra ID 故障排查速查表问题处理方式连接测试失败确认 SCIM Base URL 包含/api/identity前缀且 Bearer Token 正确用户未供给确认用户已分配给应用且属性映射正确供给报错在 Entra ID 的 Provisioning logs 中查看具体错误信息同步延迟首次供给最多 40 分钟之后的增量同步每 40 分钟发生一次4.2 OktaOkta 提供灵活的身份管理与良好的 SCIM 支持。前置条件Okta 租户具备供给能力Lifecycle ManagementOneUptime 账户为 Scale 及以上套餐且拥有两侧管理员权限。Step 1从 OneUptime 获取 SCIM 配置操作同 4.1 的 Step 1进入Project SettingsSecuritySCIM创建 SCIM Configuration配置 Auto Provision / Auto Deprovision / Default Teams / Enable Push Groups保存后复制SCIM Base URL与Bearer Token。Step 2创建或复用 Okta 应用已有 SSO 应用登录 Okta 管理控制台进入ApplicationsApplications找到并选中现有的 OneUptime 应用新建应用进入ApplicationsApplications点击Create App Integration选择SAML 2.0应用命名为 OneUptime完成 SAML 配置参见 SSO 文档点击Finish。Step 3启用 SCIM 供给在应用General标签页的App Settings中点击Edit在Provisioning下勾选SCIM保存后应用会新增Provisioning标签页。Step 4配置 SCIM 连接Integration进入Provisioning标签页左侧导航选择Integration点击Configure API Integration勾选Enable API integration填写以下配置SCIM connector base URLOneUptime 提供的 SCIM Base URL例如https://oneuptime.com/api/identity/scim/v2/{your-scim-id}Unique identifier field for usersuserNameSupported provisioning actions按需勾选Import New Users and Profile Updates、Push New Users、Push Profile Updates若使用组供给则勾选Push GroupsAuthentication Mode选择HTTP HeaderAuthorization填写Bearer {your-bearer-token}替换为实际 Token点击Test API Credentials验证连接然后Save。Step 5配置供给到应用To App在Provisioning左侧导航点击To App再点击Edit启用以下选项Create Users供给新用户Update User Attributes同步属性变更Deactivate Users取消分配时停用用户Save。Step 6配置属性映射Attribute Mappings进入Attribute Mappings确认或配置以下映射Okta 属性OneUptime SCIM 属性方向userNameuserNameOkta → Appuser.emailemails[primary eq true].valueOkta → Appuser.firstNamename.givenNameOkta → Appuser.lastNamename.familyNameOkta → Appuser.displayNamedisplayNameOkta → App删除不必要的映射如有修改则Save。Step 7可选配置 Push Groups若启用了Push Groups进入Push Groups标签页点击 Push Groups选择Find groups by name或Find groups by rule搜索并选择要推送的组Save。Step 8分配用户进入Assignments标签页点击AssignAssign to People或Assign to Groups选择用户或组并逐一Assign最后Done。Step 9验证供给在 Okta 管理控制台进入ReportsSystem Log按 OneUptime 应用过滤事件确认供给事件均为成功状态登录 OneUptime 确认用户已被创建。Okta 故障排查速查表问题处理方式API 凭据测试失败确认 SCIM Base URL 与 Bearer Token 正确用户未供给确认用户已分配给应用且供给已启用出现重复用户确认userName属性唯一并正确映射为邮箱组推送失败确认组存在且成员关系正确401 Unauthorized 错误在 OneUptime 中重新生成 Bearer Token 并更新 Okta 中的配置4.3 其他身份提供方OneUptime 的 SCIM 实现遵循 SCIM 2.0 规范应与任何支持 SCIM 的 IdP 兼容。通用配置要点SCIM Base 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必须是有效邮箱地址支持的操作对 Users 与 Groups 的 GET、POST、PUT、PATCH、DELETE。4.4 受支持的 SCIM 端点总览端点方法说明/ServiceProviderConfigGETSCIM 服务端能力/SchemasGET可用资源 schema/ResourceTypesGET可用资源类型/UsersGET、POST列出与创建用户/Users/{id}GET、PUT、PATCH、DELETE管理单个用户/GroupsGET、POST列出与创建组/团队仅项目 SCIM/Groups/{id}GET、PUT、PATCH、DELETE管理单个组仅项目 SCIM五、SCIM 数据格式与属性解析原理5.1 用户 schemaOneUptime 遵循 SCIM 2.0 核心用户 schemaurn:ietf:params:scim:schemas:core:2.0:User典型请求/响应体如下{ 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 }源码佐证OneUptime 返回用户时正是按上述格式构造的——见 SCIMUtils.ts 中的formatUserForSCIM函数。它会将 OneUptime 内部用户对象转换为包含schemas、id、userName、displayName、name拆分为givenName/familyName/formatted、emails固定type: work、primary: true、active与meta含资源类型、创建/修改时间与location的标准 SCIM 用户资源。parseNameFromSCIM则按name.formatted→givenName familyName→displayName的优先级从入站请求中提取姓名。5.2 组 schema组遵循urn:ietf:params:scim:schemas:core:2.0:Group{ schemas: [urn:ietf:params:scim:schemas:core:2.0:Group], displayName: Engineering Team, members: [ { value: user-id-here, display: userexample.com } ] }源码佐证项目 SCIM 中的组即 OneUptime 的团队Team。在 SCIM.ts 的formatTeamForSCIM函数中SCIM 组的id直接使用团队 IDdisplayName使用团队名称members通过查询TeamMemberService得到每个成员携带value用户 ID、display用户邮箱以及$ref指向该用户在 SCIM 中的完整资源位置。5.3 PATCH 与active属性解析的健壮性OneUptime 对 SCIM PATCH 请求urn:ietf:params:scim:api:messages:2.0:PatchOp与active属性的解析非常严谨这在 App/Tests/Identity/SCIMUtils.test.ts 中有大量针对性测试大小写不敏感操作名add/replace/remove以及属性名Active、UserName、Emails[TYPE EQ WORK].Value均可被正确识别布尔归一化active的字符串值False/false/FALSE均归一化为false而true/True系列保留为true无效值null、0、disabled、[]、{}等不会被错误地解释为停用按请求顺序处理先停用后重新启用会得到active: true反之则得到falseRemove操作清除待处理的active更新而不会误触发取消供给邮箱提取优先级userName优先于emails[0].value支持emails[type eq work].value这类带过滤条件的路径写法正是 Entra ID 与 Okta 默认使用的映射路径不修改入站请求对象所有解析过程均不改变原始请求体。这套容错解析逻辑保证了两大主流 IdPEntra ID、Okta在映射细节存在差异时仍能稳定完成用户创建、属性更新与停用/启用。六、SCIM 鉴权与安全实现所有 SCIM 端点都要求 Bearer Token 认证。OneUptime 通过专门的中间件实现见 Common/Server/Middleware/SCIMAuthorization.ts从 URL 路径参数中提取projectScimId或statusPageScimId从Authorization: Bearer {token}请求头中提取 Token先在ProjectSCIM表中按_id bearerToken匹配即 SCIM 配置 ID 与 Token 必须同时匹配若命中则在请求上下文中注入type: project-scim及该配置含autoProvisionUsers、autoDeprovisionUsers、enablePushGroups、teams未命中则再在StatusPageSCIM表中按同样方式匹配注入type: status-page-scim两者均未命中则抛出NotAuthorizedExceptionInvalid bearer token or SCIM configuration not found。其中SCIM 配置 IDscimId与 Bearer Token 需同时匹配缺一不可Token 缺失直接返回 401。此外Token 生成创建 SCIM 配置时若未显式提供 Token服务端会自动生成安全的随机 Token见 ProjectSCIMService.ts 的onBeforeCreate钩子使用ObjectID.generate()。因此 Okta 排错表中重新生成 Bearer Token的建议本质上是通过重新创建或更新配置来更换凭据敏感数据脱敏SCIM 操作日志会通过 SCIMLogger.ts 写入日志中password、bearerToken、authorization、token、secret、apiKey等敏感键的值会被递归脱敏避免凭据泄露到审计日志错误码标准SCIM 错误响应遵循 RFC 7644 定义的错误类型invalidFilter、tooMany、uniqueness、mutability、invalidSyntax、invalidPath、noTarget、invalidValue、invalidVers、sensitive见 SCIMUtils.ts 中的SCIMErrorType枚举。七、组供给与默认团队的工作机制理解 Default Teams 与 Push Groups 的区别是正确设计 SCIM 策略的关键默认团队Default Teams所有通过 SCIM 供给的用户都会被加入预先指定的团队。适合全员统一权限的简单场景Push Groups组推送团队归属由 IdP 侧的组决定。不同用户依据其在 IdP 中的组成员关系进入不同团队适合需要精细授权的大组织。源码佐证源码中还存在一个特殊的Unassigned 团队机制。当项目启用了基于组的供给而某用户尚未被任何组覆盖时该用户会被放入一个名为Unassigned的自动创建团队描述为通过 SCIM 供给但没有组分配的用户被放入此团队该团队没有任何权限且该团队不可编辑、不可删除、权限不可修改。当用户之后被加入真实的组SCIM 组时会自动从Unassigned团队中移出。相关实现见 SCIM.ts 的getOrCreateUnassignedTeam、addUserToUnassignedTeam、removeUserFromUnassignedTeam函数。八、常见问题FAQ取消供给Deprovision后会发生什么当用户被取消供给时无论是收到 DELETE 请求还是收到active: false的更新该用户会被从 SCIM 配置中指定的团队中移除。用户的 OneUptime 账户本身仍然保留但失去对项目的访问权限。源码佐证在 SCIM.ts 的用户更新处理中当active false且未启用 Push Groups 时会调用handleUserTeamOperations(remove, ...)将用户从 SCIM 配置的团队中移除删除用户DELETE时若autoDeprovisionUsers关闭则直接拒绝操作。能否在不开 SSO 的情况下使用 SCIM可以。SCIM 与 SSO 是两个相互独立的能力。你可以仅使用 SCIM 做用户供给用户仍然通过 OneUptime 密码或其他认证方式登录。如何处理已存在于 OneUptime 中的用户当 SCIM 尝试创建一个已存在的用户时按邮箱匹配OneUptime 不会创建重复用户而是仅将该用户添加到配置的默认团队中。这保证了 SCIM 供给与既有用户体系的平滑融合。源码佐证用户创建路径中会先通过UserService.findOneBy({ email })查询只有不存在时才调用UserService.createByEmail此时会生成随机密码并标记邮箱已验证。默认团队与 Push Groups 的区别见第七节默认团队对所有 SCIM 用户一视同仁Push Groups 则让 IdP 按组成员关系差异化分配团队。供给同步多久发生一次取决于 IdPMicrosoft Entra ID首次同步最长 40 分钟之后每 40 分钟增量同步一次Okta大多数操作近乎实时另有周期性的全量同步。九、总结OneUptime 的 SCIM 2.0 实现覆盖了项目团队与私有状态页订阅者两类场景提供了标准化的 Users/Groups 端点、Bearer Token 鉴权、PATCH 容错解析、批量操作Bulk与完整的操作审计日志。结合本仓库源码可见其设计同时兼容了 Entra ID 与 Okta 在映射细节上的差异并内置了敏感数据脱敏、无效值防护等安全机制。按本文流程你可以在 30 分钟内完成从 OneUptime 侧创建 SCIM 配置到 IdP 侧分配用户、再到验证供给成功的完整闭环。进一步阅读可参考ProjectSCIM 模型、StatusPageSCIM 模型、SCIM 鉴权中间件、SCIM API 实现、SCIM 工具函数 与 SCIM 解析测试。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考