implementing-scim-provisioning-with-okta

使用 Okta 实施 SCIM 配置

概述

SCIM（System for Cross-domain Identity Management，跨域身份管理系统）是一种开放标准协议（RFC 7644），用于自动化 Okta 等身份提供商与服务提供商之间的用户身份信息交换。本技能涵盖构建符合 SCIM 2.0 的 API 端点，并与 Okta 集成，实现包括用户配置、取消配置、配置文件更新和组管理在内的自动化用户生命周期管理。

前提条件

• 具有管理员访问权限的 Okta 租户（开发者或生产环境）
• 具有 REST API 用户管理能力的应用程序
• TLS 加密端点（必须使用 HTTPS）
• Okta API 令牌或 OAuth 2.0 客户端凭据
• Python 3.9+ 并安装 Flask 或 FastAPI

核心概念

SCIM 2.0 协议

SCIM 通过 JSON 定义了表示用户和组的标准 schema，以及 CRUD 操作的 RESTful API：

操作	HTTP 方法	端点	描述
创建用户	POST	/scim/v2/Users	配置新用户账户
读取用户	GET	/scim/v2/Users/{id}	获取用户详情
更新用户	PUT/PATCH	/scim/v2/Users/{id}	修改用户属性
删除用户	DELETE	/scim/v2/Users/{id}	删除用户账户
列出用户	GET	/scim/v2/Users	带过滤条件列出用户
创建组	POST	/scim/v2/Groups	创建组
管理组	PATCH	/scim/v2/Groups/{id}	添加/移除组成员

Okta SCIM 集成架构

Okta (IdP) ──SCIM 2.0 over HTTPS──> SCIM 服务器 ──> 应用数据库
     │                                     │
     ├── 用户分配                          ├── 创建/更新用户
     ├── 用户取消分配                      ├── 停用用户
     ├── 配置文件推送                      ├── 同步属性
     └── 组推送                           └── 管理组

必需的 SCIM 端点

1. ServiceProviderConfig (/scim/v2/ServiceProviderConfig)：公告 SCIM 功能
2. ResourceTypes (/scim/v2/ResourceTypes)：描述支持的资源类型
3. Schemas (/scim/v2/Schemas)：发布 SCIM schema 定义
4. Users (/scim/v2/Users)：用户生命周期操作
5. Groups (/scim/v2/Groups)：组管理操作

实施步骤

第 1 步：构建 SCIM 2.0 API 服务器

创建基于 Flask 的 SCIM 服务器，实现核心端点。服务器必须处理：

• 用户 CRUD：创建、读取、更新、删除和列出用户
• 过滤：支持 userName 上的 eq 过滤条件（Okta 要求）
• 分页：返回 startIndex、itemsPerPage 和 totalResults
• 认证：所有端点上的 Bearer Token 验证

from flask import Flask, request, jsonify
import uuid
from datetime import datetime

app = Flask(__name__)

# Okta 认证使用的 Bearer Token
SCIM_BEARER_TOKEN = "your-secure-token-here"

def require_auth(f):
    def wrapper(*args, **kwargs):
        auth = request.headers.get("Authorization", "")
        if not auth.startswith("Bearer ") or auth[7:] != SCIM_BEARER_TOKEN:
            return jsonify({"detail": "Unauthorized"}), 401
        return f(*args, **kwargs)
    wrapper.__name__ = f.__name__
    return wrapper

@app.route("/scim/v2/Users", methods=["POST"])
@require_auth
def create_user():
    data = request.json
    user_id = str(uuid.uuid4())
    user = {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
        "id": user_id,
        "userName": data.get("userName"),
        "name": data.get("name", {}),
        "emails": data.get("emails", []),
        "active": True,
        "meta": {
            "resourceType": "User",
            "created": datetime.utcnow().isoformat() + "Z",
            "lastModified": datetime.utcnow().isoformat() + "Z",
            "location": f"/scim/v2/Users/{user_id}"
        }
    }
    # 将用户持久化到数据库
    return jsonify(user), 201

@app.route("/scim/v2/Users", methods=["GET"])
@require_auth
def list_users():
    filter_param = request.args.get("filter", "")
    start_index = int(request.args.get("startIndex", 1))
    count = int(request.args.get("count", 100))
    # 解析过滤条件: userName eq "[email protected]"
    # 使用过滤条件查询数据库
    return jsonify({
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
        "totalResults": 0,
        "startIndex": start_index,
        "itemsPerPage": count,
        "Resources": []
    })

第 2 步：配置 Okta 应用程序

1. 创建 SCIM 应用集成：

   • 导航至"Okta Admin Console > Applications > Create App Integration"
   • 选择 SWA 或 SAML 2.0 作为登录方法
   • 在"General"选项卡中，为 Provisioning 选择 SCIM

2. 配置 SCIM 连接：

   • SCIM 连接器基础 URL：https://your-app.com/scim/v2
   • 唯一标识符字段：userName
   • 支持的配置操作：推送新用户、推送配置文件更新、推送组
   • 认证模式：HTTP Header（Bearer Token）

3. 启用配置功能：

   • 发送至应用：创建用户、更新用户属性、停用用户
   • 配置 Okta 配置文件与 SCIM schema 之间的属性映射

第 3 步：映射属性

将 Okta 用户配置文件属性映射到 SCIM schema：

Okta 属性	SCIM 属性	方向
login	userName	Okta -> 应用
firstName	name.givenName	Okta -> 应用
lastName	name.familyName	Okta -> 应用
email	emails[type eq "work"].value	Okta -> 应用
department	urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department	Okta -> 应用

第 4 步：实现错误处理

SCIM 指定了标准错误响应格式：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
  "detail": "用户已存在",
  "status": "409",
  "scimType": "uniqueness"
}

常见错误代码：400（错误请求）、401（未授权）、404（未找到）、409（冲突）、500（服务器内部错误）。

第 5 步：使用 Runscope/Okta SCIM 验证器测试

Okta 提供自动化 SCIM 测试套件（通过 Runscope/BlazeMeter），验证您的 SCIM 实现是否符合所有必需操作：

1. 从 OIN 提交门户导入 Okta SCIM 2.0 测试套件
2. 配置基础 URL 和认证令牌
3. 运行涵盖用户 CRUD、过滤和分页的完整测试套件
4. 在提交到 OIN 之前修复所有失败的测试

验证清单

• SCIM 服务器可通过 HTTPS 访问且拥有有效的 TLS 证书
• 所有端点强制执行 Bearer Token 认证
• 用户创建返回 201 及完整用户表示
• 按 userName eq "..." 过滤的用户搜索正常工作
• 分页参数（startIndex、count）正确处理
• 用户停用设置 active: false（而非硬删除）
• PATCH 操作支持 add、replace、remove 操作
• 组推送正确创建和管理组成员关系
• Okta SCIM 验证器测试套件通过所有测试
• 错误响应符合 SCIM 错误 schema

参考资料

• SCIM 2.0 协议 RFC 7644
• Okta SCIM 开发者指南
• 构建 SCIM API 服务 - Okta
• SCIM 核心 Schema RFC 7643