跳到主要内容

SCIM 2.0 支持

OPL 数据空间 支持 SCIM 2.0（System for Cross-domain Identity Management），可与 Okta、Azure AD、Google Workspace 等身份提供方联动，实现用户和用户组的自动开通。

组织感知下发

在启用了 组织 的部署里，SCIM 下发应与落地组织行为一起评估。即便新账号创建时没有显式组织上下文，它也仍然需要一个有效的归属组织。

概览​

SCIM 是一个开放标准，用于自动化用户生命周期管理。启用后，身份提供方可以自动：

  • 在用户加入组织时于 OPL 数据空间 中创建账号
  • 在用户信息发生变化时同步更新
  • 在用户被移除时停用账号
  • 管理用户组成员关系

如果你的身份流程在下发时没有附带显式组织信息， OPL 数据空间 会按照当前配置的落地组织规则解析新用户的归属组织。上线前建议同时阅读 组织 和 组织维护。

配置​

SCIM 完全通过环境变量配置，没有 UI 设置入口。

环境变量​

  • SCIM_ENABLED：设为 true 启用 SCIM（默认 false）
  • SCIM_TOKEN：SCIM 认证用 Bearer Token（启用 SCIM 时必填）
  • SCIM_AUTH_PROVIDER：将 externalId 绑定到哪个 OAuth provider，例如 microsoft、oidc
注意

SCIM_TOKEN 应使用安全的随机字符串生成，例如：

openssl rand -base64 32

请把它当成高敏感凭据管理。

配置示例​

SCIM_ENABLED=true
SCIM_TOKEN="your-secure-token-here"
SCIM_AUTH_PROVIDER="microsoft"

IdP 侧接入参数​

  • SCIM Base URL：<your-openwebui-url>/api/v1/scim/v2/
  • Authentication：Bearer Token
  • Token：Bearer <your-scim-token>

以 Okta 为例​

  1. 在 Okta 中添加 SCIM 应用
  2. 把 Connector Base URL 设为 https://your-domain.com/api/v1/scim/v2/
  3. 认证方式选 “HTTP Header”
  4. 添加 Authorization: Bearer your-scim-token

支持的 SCIM 操作​

用户操作​

  • Create User（POST /Users）
  • Get User（GET /Users/{id}）
  • Update User（PUT /Users/{id} / PATCH /Users/{id}）
  • Delete User（DELETE /Users/{id}，表现为停用）
  • List Users（GET /Users，支持过滤）

用户组操作​

  • Create Group（POST /Groups）
  • Get Group（GET /Groups/{id}）
  • Update Group（PUT /Groups/{id} / PATCH /Groups/{id}）
  • Delete Group（DELETE /Groups/{id}）
  • List Groups（GET /Groups，支持过滤）

支持的属性​

用户属性​

  • userName：用户邮箱（必填且唯一）
  • name.givenName：名
  • name.familyName：姓
  • emails：邮箱列表；若有多个，会优先使用 primary: true
  • active：账号是否启用
  • externalId：身份提供方的外部标识，会按 provider 存入用户的 scim JSON 字段

用户组属性​

  • 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 后， OPL 数据空间 会把 externalId 按 provider 存进用户 scim 字段，例如：

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

这会带来几种关键行为：

  • 按 externalId 查找用户
  • 找不到时回退到 OAuth sub 关联
  • 创建和更新用户时保留 externalId，并在后续响应中返回
注意

如果启用了 SCIM，但没有配置 SCIM_AUTH_PROVIDER，任何依赖 externalId 的操作都可能返回 500，启动时也会记录警告。

故障排查​

常见问题​

  1. 401 Unauthorized

    • 确认 SCIM_ENABLED=true
    • 确认 IdP 侧 Bearer Token 与 SCIM_TOKEN 一致
    • 确认请求头格式是 Bearer <token>

  2. 404 Not Found

    • 确认 SCIM Base URL 以 /api/v1/scim/v2/ 结尾
    • 确认路径带了 /api/v1

  3. 用户创建失败

    • userName 必须是有效邮箱
    • 邮箱或 externalId 不能已被占用

  4. 涉及 externalId 的 500

    • 确认 SCIM_AUTH_PROVIDER 配置正确

用 curl 测试​

curl -H "Authorization: Bearer your-scim-token" \
  https://your-domain.com/api/v1/scim/v2/Users
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
  2. 安全存储并定期轮换 SCIM_TOKEN
  3. 按需对 SCIM API 做 IP 白名单
  4. 审计 SCIM 操作日志

限制​

  • 暂不支持自定义 schema extension
  • 未实现 bulk operations
  • 不支持资源版本管理用的 ETag

与 SSO 的配合​

SCIM 最适合与 SSO 一起使用：

  1. SCIM 负责自动开通用户与用户组
  2. OIDC / SSO 负责用户实际登录

这样可以做到：账号自动创建完成后，用户即可直接用企业身份登录使用。

SSO 配置请看 SSO 文档。