OneUptime SCIM 2.0 身份供给集成指南：项目与状态页的用户自动供给、取消供给及 Entra ID / Okta 配置

OneUptime SCIM 2.0 身份供给集成指南：项目与状态页的用户自动供给、取消供给及 Entra ID / Okta 配置

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

OneUptime 是一款开源的监控与可观测性平台，本文围绕其内置的 SCIM（System 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 实现：

从源码层面看，这两套实现分别对应两个独立的数据模型：ProjectSCIM 与 StatusPageSCIM，并各自拥有独立的审计日志模型ProjectSCIMLog与StatusPageSCIMLog。

二、项目 SCIM（Project SCIM）配置指南

项目 SCIM 使 IdP 能够管理 OneUptime 项目内的团队成员。以下为完整配置流程。

2.1 在 OneUptime 中创建 SCIM 配置

1. 进入项目设置：登录 OneUptime 控制台，进入目标项目，导航至Project Settings>Security>SCIM；
2. 创建 SCIM 配置：点击Create SCIM Configuration，填写一个友好的配置名称（例如 "Microsoft Entra ID Provisioning" 或 "Okta Provisioning"）；
3. 配置关键选项：
   • Auto Provision Users：启用后，当用户在 IdP 中被分配时自动创建到 OneUptime；
   • Auto Deprovision Users：启用后，当用户在 IdP 中被取消分配时自动移除访问；
   • Default Teams：选择新供给用户默认加入的团队；
   • Enable Push Groups（可选）：启用后，改由 IdP 通过组推送（Push Groups）来管理团队归属，而不是统一放入默认团队；
4. 保存并复制凭据：保存配置后，复制SCIM Base URL与Bearer Token，这两个值将用于后续 IdP 侧的配置。

源码佐证：在 ProjectSCIM.ts 中可以看到autoProvisionUsers与autoDeprovisionUsers字段的数据库默认值均为true，而enablePushGroups默认值为false；teams字段通过ProjectScimTeam多对多关联表与 Team 关联。name字段以projectId为唯一键约束（@UniqueColumnBy("projectId")），即每个项目下 SCIM 配置名称不可重复。

2.2 在 IdP 侧配置 SCIM

在 IdP（如 Entra ID、Okta）中新建 SCIM 应用时，使用以下信息：

• SCIM Base URL：https://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）：

源码佐证：这些路由定义在 App/FeatureSet/Identity/API/SCIM.ts 中，例如router.get("/scim/v2/:projectScimId/ServiceProviderConfig", SCIMMiddleware.isAuthorizedSCIMRequest, ...)。此外该文件还实现了标准端点之外的POST /scim/v2/:projectScimId/Bulk批量操作端点，用于一次性处理多笔用户/组操作（批量上限为 1000 条操作）。

2.4 项目 SCIM 用户生命周期

一次完整的 SCIM 供给 / 取消供给周期如下：

1. IdP 中分配用户：管理员在 IdP 中将用户分配给 OneUptime 应用；
2. 触发 SCIM 供给：IdP 调用 OneUptime 的 SCIM API 创建用户；
3. 加入默认团队：用户自动被加入 OneUptime 中预先配置的默认团队（若未启用 Push Groups）；
4. 授予访问权限：用户即可访问 OneUptime 项目；
5. IdP 中取消分配：管理员在 IdP 中取消对用户的分配；
6. 触发 SCIM 取消供给：IdP 调用 SCIM API 移除该用户；
7. 访问失效：用户失去对项目的访问权限。

源码佐证：在 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 错误。

三、状态页 SCIM（Status Page SCIM）配置指南

状态页 SCIM 面向私有状态页（Private Status Page）的订阅者管理，使 IdP 可以自动管理谁能订阅（查看）你的私有状态页。

3.1 配置步骤

1. 进入状态页设置：打开你的 OneUptime 状态页，导航至Status Page>Security>SCIM；
2. 配置 SCIM 设置：
   • Auto Provision Users：启用后，当订阅者在 IdP 中被分配时自动创建为状态页用户；
   • Auto Deprovision Users：启用后，当订阅者在 IdP 中被取消分配时自动移除；
   • 复制SCIM Base URL与Bearer Token；
3. 配置 IdP：
   • SCIM Base URL 使用：https://oneuptime.com/status-page-scim/v2/{scimId}；
   • 使用 Bearer Token 认证；
   • 映射用户属性（email 必填）。

3.2 状态页 SCIM 端点清单

与项目 SCIM 不同，状态页 SCIM不提供 Groups 相关端点——订阅者不属于团队体系，因此无需组管理。

3.3 状态页 SCIM 用户生命周期

1. IdP 中分配订阅者；
2. 触发 SCIM 供给：IdP 调用 SCIM API 创建订阅者；
3. 授予访问权限：订阅者可以访问私有状态页；
4. IdP 中取消分配；
5. 触发 SCIM 取消供给：IdP 调用 SCIM API 移除订阅者；
6. 访问失效：订阅者失去对私有状态页的访问。

源码佐证：StatusPageSCIM.ts 模型同样包含autoProvisionUsers（默认true）与autoDeprovisionUsers（默认true）字段，并通过statusPageId关联到具体的 StatusPage 资源。其 CRUD 端点为/status-page-scim，权限基于Permission.CreateStatusPageSSO等状态页 SSO 相关权限。

四、身份提供方配置详解

4.1 Microsoft Entra ID（原 Azure AD）

Entra ID 提供企业级身份管理与完善的 SCIM 供给能力。OneUptime 账户需为Scale 及以上套餐，Entra ID 侧需要Premium P1 或 P2 许可证（自动供给必需），并且需要对两侧拥有管理员访问权限。

Step 1：从 OneUptime 获取 SCIM 配置

1. 登录 OneUptime 仪表盘，进入Project Settings>Security>SCIM；
2. 点击Create SCIM Configuration，输入友好名称（如 "Microsoft Entra ID Provisioning"）；
3. 配置Auto Provision Users、Auto Deprovision Users、Default Teams，如需通过 Entra ID 组管理团队归属则开启Enable Push Groups；
4. 保存后复制SCIM Base URL与Bearer Token。

Step 2：在 Entra ID 中创建企业应用

1. 登录 Microsoft Entra 管理中心；
2. 进入Identity>Applications>Enterprise applications；
3. 点击+ New application，然后选择+ Create your own application；
4. 输入名称（如 "OneUptime"），选择Integrate any other application you don't find in the gallery (Non-gallery)；
5. 点击Create。

Step 3：配置 SCIM 供给

1. 进入刚创建的企业应用，打开Provisioning并点击Get started；
2. 将Provisioning Mode设置为Automatic；
3. 在Admin Credentials中填写：
   • Tenant URL：OneUptime 提供的 SCIM Base URL，例如https://oneuptime.com/api/identity/scim/v2/{your-scim-id}；
   • Secret Token：OneUptime 提供的 Bearer Token；
4. 点击Test Connection验证配置，然后Save。

Step 4：配置属性映射（Mappings）

1. 在 Provisioning 中点击Mappings，选择Provision Azure Active Directory Users；
2. 按下表配置属性映射：

3. 移除不需要的映射以简化供给；完成后Save。

说明：active属性决定用户是否处于启用状态，Entra ID 使用表达式Switch([IsSoftDeleted], ...)将"软删除"状态映射为active的布尔值。OneUptime 侧会对该字段做严格的语义解析（详见后文"SCIM 属性解析原理"）。

Step 5（可选）：配置组供给

若在 OneUptime 中启用了Push Groups：

1. 回到Mappings，点击Provision Azure Active Directory Groups；
2. 将Enabled设为Yes；
3. 配置映射：displayName→displayName，members→members；
4. Save。

Step 6：分配用户与组

1. 进入企业应用的Users and groups；
2. 点击+ Add user/group，选择要供给到 OneUptime 的用户和/或组；
3. 点击Assign。

Step 7：启动供给

1. 进入Provisioning>Overview；
2. 点击Start provisioning；
3. 首次供给周期随即开始——首次同步最长可能需要 40 分钟；
4. 通过Provisioning logs监控任何错误。

Entra ID 故障排查速查表

4.2 Okta

Okta 提供灵活的身份管理与良好的 SCIM 支持。前置条件：Okta 租户具备供给能力（Lifecycle Management），OneUptime 账户为 Scale 及以上套餐，且拥有两侧管理员权限。

Step 1：从 OneUptime 获取 SCIM 配置

操作同 4.1 的 Step 1：进入Project Settings>Security>SCIM，创建 SCIM Configuration，配置 Auto Provision / Auto Deprovision / Default Teams / Enable Push Groups，保存后复制SCIM Base URL与Bearer Token。

Step 2：创建或复用 Okta 应用

• 已有 SSO 应用：登录 Okta 管理控制台，进入Applications>Applications，找到并选中现有的 OneUptime 应用；
• 新建应用：进入Applications>Applications，点击Create App Integration，选择SAML 2.0，应用命名为 "OneUptime"，完成 SAML 配置（参见 SSO 文档），点击Finish。

Step 3：启用 SCIM 供给

1. 在应用General标签页的App Settings中点击Edit；
2. 在Provisioning下勾选SCIM；
3. 保存后，应用会新增Provisioning标签页。

Step 4：配置 SCIM 连接（Integration）

1. 进入Provisioning标签页，左侧导航选择Integration，点击Configure API Integration；
2. 勾选Enable API integration；
3. 填写以下配置：
   • SCIM connector base URL：OneUptime 提供的 SCIM Base URL，例如https://oneuptime.com/api/identity/scim/v2/{your-scim-id}；
   • Unique identifier field for users：userName；
   • Supported provisioning actions：按需勾选Import New Users and Profile Updates、Push New Users、Push Profile Updates，若使用组供给则勾选Push Groups；
   • Authentication Mode：选择HTTP Header；
   • Authorization：填写Bearer {your-bearer-token}（替换为实际 Token）；
4. 点击Test API Credentials验证连接，然后Save。

Step 5：配置"供给到应用"（To App）

1. 在Provisioning左侧导航点击To App，再点击Edit；
2. 启用以下选项：
   • Create Users：供给新用户；
   • Update User Attributes：同步属性变更；
   • Deactivate Users：取消分配时停用用户；
3. Save。

Step 6：配置属性映射（Attribute Mappings）

进入Attribute Mappings，确认或配置以下映射：

删除不必要的映射，如有修改则Save。

Step 7（可选）：配置 Push Groups

若启用了Push Groups：

1. 进入Push Groups标签页，点击+ Push Groups；
2. 选择Find groups by name或Find groups by rule；
3. 搜索并选择要推送的组，Save。

Step 8：分配用户

1. 进入Assignments标签页；
2. 点击Assign>Assign to People或Assign to Groups；
3. 选择用户或组并逐一Assign，最后Done。

Step 9：验证供给

1. 在 Okta 管理控制台进入Reports>System Log；
2. 按 OneUptime 应用过滤事件，确认供给事件均为成功状态；
3. 登录 OneUptime 确认用户已被创建。

Okta 故障排查速查表

4.3 其他身份提供方

OneUptime 的 SCIM 实现遵循 SCIM 2.0 规范，应与任何支持 SCIM 的 IdP 兼容。通用配置要点：

1. SCIM Base URL：
   • 项目：https://oneuptime.com/api/identity/scim/v2/{scim-id}；
   • 状态页：https://oneuptime.com/api/identity/status-page-scim/v2/{scim-id}；
2. 认证方式：HTTP Bearer Token；
3. 必填用户属性：userName（必须是有效邮箱地址）；
4. 支持的操作：对 Users 与 Groups 的 GET、POST、PUT、PATCH、DELETE。

4.4 受支持的 SCIM 端点总览

五、SCIM 数据格式与属性解析原理

5.1 用户 schema

OneUptime 遵循 SCIM 2.0 核心用户 schema（urn:ietf:params:scim:schemas:core:2.0:User），典型请求/响应体如下：

{ "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"], "userName": "user@example.com", "name": { "givenName": "John", "familyName": "Doe", "formatted": "John Doe" }, "displayName": "John Doe", "emails": [ { "value": "user@example.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": "user@example.com" } ] }

源码佐证：项目 SCIM 中的组即 OneUptime 的团队（Team）。在 SCIM.ts 的formatTeamForSCIM函数中，SCIM 组的id直接使用团队 ID，displayName使用团队名称，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，反之则得到false；Remove操作清除待处理的active更新而不会误触发取消供给；
• 邮箱提取优先级：userName优先于emails[0].value；支持emails[type eq "work"].value这类带过滤条件的路径写法（正是 Entra ID 与 Okta 默认使用的映射路径）；
• 不修改入站请求对象：所有解析过程均不改变原始请求体。

这套容错解析逻辑保证了两大主流 IdP（Entra ID、Okta）在映射细节存在差异时，仍能稳定完成用户创建、属性更新与停用/启用。

六、SCIM 鉴权与安全实现

所有 SCIM 端点都要求 Bearer Token 认证。OneUptime 通过专门的中间件实现，见 Common/Server/Middleware/SCIMAuthorization.ts：

1. 从 URL 路径参数中提取projectScimId或statusPageScimId；
2. 从Authorization: Bearer {token}请求头中提取 Token；
3. 先在ProjectSCIM表中按_id + bearerToken匹配（即 SCIM 配置 ID 与 Token 必须同时匹配）；若命中，则在请求上下文中注入type: "project-scim"及该配置（含autoProvisionUsers、autoDeprovisionUsers、enablePushGroups、teams）；
4. 未命中则再在StatusPageSCIM表中按同样方式匹配，注入type: "status-page-scim"；
5. 两者均未命中则抛出NotAuthorizedException（"Invalid bearer token or SCIM configuration not found"）。

其中SCIM 配置 ID（scimId）与 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 按组成员关系差异化分配团队。

供给同步多久发生一次？

取决于 IdP：

• Microsoft 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