Skip to main content

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 令牌（启用 SCIM 时必填）
warning

安全提示 SCIM 令牌应是一个安全的、随机生成的字符串。您可以使用以下命令生成一个：

openssl rand -base64 32

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

配置示例​


# 启用 SCIM
export SCIM_ENABLED=true

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

SCIM API 配置​

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

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

常用身份提供商示例​

Okta​

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

支持的 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：电子邮件地址
  • active：用户状态（激活/停用）
  • externalId：来自身份提供商的外部标识符

组属性​

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

过滤支持​

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

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

支持的过滤操作符：

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

故障排除​

常见问题​

  1. 401 Unauthorized 错误

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

  2. 404 Not Found 错误

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

  3. 用户创建失败

    • 确保 userName 字段包含有效的电子邮件地址
    • 检查该电子邮件是否已被使用

测试 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",
    "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 令牌
  2. 安全令牌存储：安全地存储 SCIM 令牌并定期更换
  3. IP 白名单：考虑将 SCIM API 访问限制在身份提供商的 IP 地址范围内
  4. 审计日志：SCIM 操作会被记录以便进行安全审计

限制​

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

与 SSO 集成​

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

  1. 使用 SCIM 进行自动化的用户供应
  2. 使用 OIDC 进行用户身份验证

这可以确保用户被自动创建，并能立即使用其公司凭据进行身份验证。

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