跳到主要内容

SCIM 2.0 支持

Open WebUI 支持 SCIM 2.0（跨域身份管理系统），用于从 Okta、Azure AD 和 Google Workspace 等身份提供商自动化用户和用户组预配。

概述​

SCIM 是一个允许自动化用户预配的开放标准。启用后，您的身份提供商可以自动：

  • 在将用户添加到您的组织时在 Open WebUI 中创建用户
  • 在信息更改时更新用户信息
  • 在用户从您的组织中移除时停用用户
  • 管理用户组成员资格

配置​

SCIM 完全通过环境变量进行配置。SCIM 设置没有 UI 配置选项。

环境变量​

通过设置以下环境变量配置 SCIM：

  • SCIM_ENABLED：设置为 true 以启用 SCIM 支持（默认：false）
  • SCIM_TOKEN：用于 SCIM 身份认证的 Bearer token（启用 SCIM 时必填）
  • SCIM_AUTH_PROVIDER：要与 SCIM externalId 值关联的 OAuth 提供商名称（例如 microsoft、oidc）。externalId 存储和账户关联所必需。
注意

安全说明 SCIM token 应该是安全的随机生成字符串。您可以使用以下命令生成：

openssl rand -base64 32

请妥善保管此 token，因为它提供对用户管理操作的访问权限。

配置示例​

# 启用 SCIM
export SCIM_ENABLED=true

# 设置安全 token（替换为您自己生成的 token）
export SCIM_TOKEN="your-secure-token-here"

# 设置用于 externalId 关联的 OAuth 提供商名称
export SCIM_AUTH_PROVIDER="microsoft"

SCIM API 配置​

配置您的身份提供商时，请使用以下设置：

  • SCIM 基础 URL：<your-openwebui-url>/api/v1/scim/v2/
  • 身份认证：Bearer Token
  • Token：Bearer <your-scim-token>

主流身份提供商配置示例​

Okta​

  1. 在 Okta 中添加 SCIM 应用
  2. 将 SCIM 连接器基础 URL 设置为：https://your-domain.com/api/v1/scim/v2/
  3. 将身份认证设置为"HTTP Header"
  4. 添加值为 Bearer your-scim-token 的 Authorization 请求头

支持的 SCIM 操作​

Open WebUI 的 SCIM 实现支持以下操作：

用户操作​

  • 创建用户（POST /Users）：创建新用户账户
  • 获取用户（GET /Users/{id}）：检索用户信息
  • 更新用户（PUT /Users/{id}、PATCH /Users/{id}）：更新用户属性
  • 删除用户（DELETE /Users/{id}）：停用用户账户
  • 列出用户（GET /Users）：列出所有用户（支持过滤）

用户组操作​

  • 创建用户组（POST /Groups）：创建新用户组
  • 获取用户组（GET /Groups/{id}）：检索用户组信息
  • 更新用户组（PUT /Groups/{id}、PATCH /Groups/{id}）：更新用户组成员
  • 删除用户组（DELETE /Groups/{id}）：移除用户组
  • 列出用户组（GET /Groups）：列出所有用户组（支持过滤）

支持的属性​

用户属性​

  • userName：用户的邮箱地址（必填，唯一）
  • name.givenName：名
  • name.familyName：姓
  • emails：邮箱地址（提供多个时，使用标记了 primary: true 的条目）
  • active：用户状态（活跃/非活跃）
  • externalId：来自身份提供商的外部标识符（按提供商存储在用户的 scim JSON 字段中，参见 externalId 与账户关联）

用户组属性​

  • displayName：用户组名称（必填）
  • members：用户成员数组
  • externalId：来自身份提供商的外部标识符

过滤支持​

SCIM API 支持对用户和用户组进行过滤：

GET /api/v1/scim/v2/Users?filter=userName eq "user@example.com"
GET /api/v1/scim/v2/Users?filter=externalId eq "abc-123"
GET /api/v1/scim/v2/Groups?filter=displayName eq "Engineering"

支持的过滤运算符：

  • eq：等于
  • ne：不等于
  • co：包含
  • sw：以...开头
  • ew：以...结尾
  • pr：存在（有值）
  • gt：大于
  • ge：大于或等于
  • lt：小于
  • le：小于或等于

externalId 与账户关联​

配置 SCIM_AUTH_PROVIDER 后，Open WebUI 将 externalId 值存储在用户 scim JSON 字段中的每提供商结构里：

{
  "microsoft": { "external_id": "abc-123" },
  "okta": { "external_id": "def-456" }
}

这实现了以下几种行为：

  • 通过 externalId 查找用户：当身份提供商发送 filter=externalId eq "..." 请求时，Open WebUI 会在 scim 字段中搜索已配置提供商的匹配条目。
  • OAuth 回退：如果通过 externalId 未找到用户，Open WebUI 会回退到与 OAuth sub 值匹配，自动将 SCIM 预配的账户与现有 OAuth 认证用户关联。
  • 创建和更新：通过 SCIM 创建或更新用户时，externalId 存储在 scim 字段中，并在后续响应中返回。
注意

如果在启用 SCIM 的情况下未设置 SCIM_AUTH_PROVIDER，任何需要 externalId 的操作（创建、查找或更新）都将返回 500 错误。启动时也会记录警告提醒您。

故障排查​

常见问题​

  1. 401 未授权错误

    • 验证 SCIM_ENABLED 是否设置为 true
    • 检查身份提供商中的 Bearer token 是否与 SCIM_TOKEN 匹配
    • 确保 Authorization 请求头格式为：Bearer <token>

  2. 404 未找到错误

    • 验证 SCIM 基础 URL 是否以 /api/v1/scim/v2/ 结尾
    • 检查路径是否包含 /api/v1 前缀

  3. 用户创建失败

    • 确保 userName 字段包含有效的邮箱地址
    • 检查邮箱或 externalId 是否已被使用

  4. externalId 操作返回 500 错误

    • 验证 SCIM_AUTH_PROVIDER 是否设置为正确的 OAuth 提供商名称

测试 SCIM 端点​

您可以使用 curl 测试 SCIM 端点：

# 测试身份认证并列出用户
curl -H "Authorization: Bearer your-scim-token" \
  https://your-domain.com/api/v1/scim/v2/Users

# 获取特定用户
curl -H "Authorization: Bearer your-scim-token" \
  https://your-domain.com/api/v1/scim/v2/Users/user-id

# 创建测试用户
curl -X POST \
  -H "Authorization: Bearer your-scim-token" \
  -H "Content-Type: application/scim+json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
    "userName": "test@example.com",
    "externalId": "idp-user-id-123",
    "displayName": "Test User",
    "name": {
      "givenName": "Test",
      "familyName": "User"
    },
    "emails": [{
      "value": "test@example.com",
      "primary": true
    }],
    "active": true
  }' \
  https://your-domain.com/api/v1/scim/v2/Users

安全注意事项​

  1. 使用 HTTPS：在生产环境中始终使用 HTTPS 来保护 Bearer token
  2. 安全 Token 存储：安全地存储 SCIM token 并定期轮换
  3. IP 白名单：考虑将 SCIM API 访问限制到您身份提供商的 IP 地址
  4. 审计日志：SCIM 操作会被记录以供安全审计

局限性​

  • 目前不支持自定义 Schema 扩展
  • 未实现批量操作
  • 不支持用于资源版本控制的 ETag

与 SSO 集成​

SCIM 与 SSO（单点登录）结合使用效果最佳。典型设置包括：

  1. SCIM 用于自动化用户预配
  2. OIDC 用于用户身份认证

这确保用户被自动创建并可以立即使用其企业凭据进行身份认证。

有关 SSO 配置，请参阅 SSO 文档。

本内容仅供参考，不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅您的许可协议 以了解适用条款。