SCIM 2.0 支持

Open WebUI 支持 SCIM 2.0（跨域身份管理系统，System for Cross-domain Identity Management），以实现从 Okta、Azure AD 和 Google Workspace 等身份提供商（IdP）自动配置用户和用户组。

概述

SCIM 是一项用于实现用户自动配置的开放标准。启用后，您的身份提供商可以自动执行以下操作：

当用户被添加到您的组织时，自动在 Open WebUI 中创建用户
当用户基本信息发生更改时，自动进行更新
当用户从您的组织中移除时，自动在 Open WebUI 中停用用户
自动管理用户组成员身份

配置

SCIM 完全通过环境变量进行配置。在 UI 界面中没有 SCIM 配置设置项。

环境变量

通过设置以下环境变量来配置 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 (Base URL)：<your-openwebui-url>/api/v1/scim/v2/
身份验证 (Authentication)：Bearer Token
Token：Bearer <your-scim-token>

常用身份提供商示例

Okta

在 Okta 中，添加 SCIM 应用程序
将 SCIM 连接器基准 URL 设置为：https://your-domain.com/api/v1/scim/v2/
将身份验证方式设置为 "HTTP Header"
添加 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：电子邮件地址（当提供多个时，使用标记为 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：等于 (Equals)
ne：不等于 (Not equals)
co：包含 (Contains)
sw：以...开始 (Starts with)
ew：以...结束 (Ends with)
pr：存在值 (Present)
gt：大于 (Greater than)
ge：大于等于 (Greater than or equal)
lt：小于 (Less than)
le：小于等于 (Less than or equal)

externalId 与账号关联

配置 SCIM_AUTH_PROVIDER 后，Open WebUI 将在用户的 scim JSON 字段中以提供商为单位存储 externalId 值：

{
  "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 错误。启动时也会记录一条警告以向您发出警示。

故障排除

常见问题

401 Unauthorized 错误
- 验证 SCIM_ENABLED 是否设置为 true
- 检查身份提供商中的 Bearer Token 是否与 SCIM_TOKEN 匹配
- 确保 Authorization 请求头的格式为：Bearer <token>
404 Not Found 错误
- 验证 SCIM 基准 URL 是否以 /api/v1/scim/v2/ 结尾
- 检查路径中是否包含 /api/v1 前缀
用户创建失败
- 确保 userName 字段包含合法的电子邮件地址
- 检查该电子邮件或 externalId 是否已被占用
对 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

安全注意事项

使用 HTTPS：在生产环境中始终使用 HTTPS，以保护 Bearer Token
安全的 Token 存储：安全地存储 SCIM Token 并定期进行轮换
IP 白名单：考虑将 SCIM API 的访问限制为您身份提供商的 IP 地址段
审计日志：记录 SCIM 操作日志以用于安全审计

局限性

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

与 SSO 集成

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

使用 SCIM 进行用户自动配置
使用 OIDC 进行用户身份验证

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

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

This content is for informational purposes only and does not constitute a warranty, guarantee, or contractual commitment. Open WebUI is provided "as is." See your license for applicable terms.

概述​

配置​

环境变量​

示例配置​

SCIM API 配置​

常用身份提供商示例​

Okta​

支持的 SCIM 操作​

用户操作​

用户组操作​

支持的属性​

用户属性​

用户组属性​

过滤支持​

externalId 与账号关联​

故障排除​

常见问题​

测试 SCIM 接口端点​

安全注意事项​

局限性​

与 SSO 集成​

概述

配置