18.4 · SCIM 预配（SCIM Provisioning）

SCIM 预配（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/18.4-scim-provisioning

翻译时间：2026-06-09T16:12:26.277Z

翻译模型：deepseek-chat

原文字符数：7610

项目：Open WebUI (open-webui)

---

SCIM 预配置

Open WebUI 提供了 SCIM 2.0（跨域身份管理系统） 协议的实验性实现。此功能允许外部身份提供商（IdP）在 Open WebUI 环境中自动预配置、更新和取消预配置用户与组 backend/open_webui/routers/scim.py:1-6。

实现概述

SCIM 实现构建为一个专用的 FastAPI 路由器，将 SCIM 标准操作映射到内部的 Users 和 Groups 模型。它支持用户和组资源的标准 CRUD 操作 backend/open_webui/routers/scim.py:37-47。

关键组件

来源： backend/open_webui/routers/scim.py:1-232, backend/open_webui/models/groups.py:33-81, backend/open_webui/migrations/versions/b2c3d4e5f6a7_add_scim_column_to_user_table.py:22-22

数据流与架构

SCIM 流程充当外部 IdP 请求与内部数据库状态之间的桥梁。

SCIM 预配置请求流程

此图展示了来自身份提供商的外部请求如何通过 SCIM 路由器处理并持久化到 User 和 Group 数据库实体中。

sequenceDiagram
    participant IdP as "身份提供商 (Okta/Entra ID)"
    participant Router as "scim.py (APIRouter)"
    participant Auth as "get_scim_auth()"
    participant UModel as "Users (模型)"
    participant GModel as "Groups (模型)"
    participant DB as "SQLAlchemy (AsyncSession)"

    IdP->>Router: "POST /scim/v2/Users (JSON)"
    Router->>Auth: "验证 SCIM Bearer Token"
    Auth-->>Router: "已授权"
    Router->>UModel: "insert_new_user(user_data)"
    UModel->>DB: "INSERT INTO user (scim)"
    DB-->>UModel: "成功"
    UModel-->>Router: "UserModel"
    Router-->>IdP: "201 Created (SCIMUser JSON)"

来源： backend/open_webui/routers/scim.py:235-256, backend/open_webui/routers/scim.py:38-68, backend/open_webui/models/users.py:246-280

资源映射

该实现将标准 SCIM 属性映射到内部 Open WebUI 数据库字段。

用户映射

用户资源存储在 user 表中。为了支持 SCIM 特定的元数据而不破坏核心用户模式，使用了 scim JSON 列 backend/open_webui/migrations/versions/b2c3d4e5f6a7_add_scim_column_to_user_table.py:22-22。

组映射

组直接映射到 Group 和 GroupMember 表 backend/open_webui/models/groups.py:33-81。

来源： backend/open_webui/routers/scim.py:128-209, backend/open_webui/models/groups.py:33-81, backend/open_webui/migrations/versions/b2c3d4e5f6a7_add_scim_column_to_user_table.py:22-22

身份验证与安全

SCIM 端点的身份验证由 get_scim_auth 处理 backend/open_webui/routers/scim.py:235-240。它与标准用户身份验证不同：

1. Bearer Token： 它期望通过环境变量配置的静态 SCIM 专用 API 令牌 backend/open_webui/routers/scim.py:241-256。
2. 提供商验证： 如果设置了 SCIM_AUTH_PROVIDER，系统会验证预配置源是否与预期的身份提供商匹配 backend/open_webui/env.py:30-30, backend/open_webui/routers/scim.py:29-30。

SCIM 内部实体关联

下图将 SCIM 路由器逻辑映射到内部数据库实体和管理类。

classDiagram
    class SCIMRouter {
        <<APIRouter>>
        +get_users()
        +create_user()
        +patch_user()
        +get_groups()
        +update_group()
    }

    class Users {
        <<TableClass>>
        +insert_new_user()
        +update_user_by_id()
        +get_user_by_email()
    }

    class Groups {
        <<TableClass>>
        +insert_new_group()
        +add_users_to_group()
        +remove_user_from_group()
    }

    class Group {
        <<Base>>
        id: "Text"
        name: "Text"
        permissions: "JSON"
    }

    class User {
        <<Base>>
        id: "Text"
        email: "Text"
        scim: "JSON"
    }

    SCIMRouter --> Users : "调用以获取用户资源"
    SCIMRouter --> Groups : "调用以获取组资源"
    Users --> User : "持久化到"
    Groups --> Group : "持久化到"

来源： backend/open_webui/routers/scim.py:37-232, backend/open_webui/models/users.py:246-280, backend/open_webui/models/groups.py:33-50, backend/open_webui/models/groups.py:130-168

实验性限制

当前的 SCIM 实现被标记为实验性 backend/open_webui/routers/scim.py:1-6。主要注意事项包括：

• 补丁支持： PATCH 操作通过 SCIMPatchRequest 实现，但可能不支持复杂的 SCIM 过滤器或多值属性移除 backend/open_webui/routers/scim.py:220-233。
• 模式合规性： 虽然使用了标准模式如 urn:ietf:params:scim:schemas:core:2.0:User，但并非所有可选的 SCIM 扩展都受支持 backend/open_webui/routers/scim.py:41-44。
• 错误处理： 使用 scim_error 辅助函数返回错误，以确保 IdP 收到符合 SCIM 规范的错误体，并包含适当的 scimType backend/open_webui/routers/scim.py:51-68。

来源： backend/open_webui/routers/scim.py:1-68