使用Cato SCIM API定制SCIM应用程序

本文描述如何使用Cato的SCIM API通过身份提供商（IdP）进行用户和用户组配置。

有关 IdP 租户中自定义 SCIM 应用程序的更多信息，请参见为 IdP 创建自定义 SCIM 应用程序。

自定义 Cato SCIM 应用

要使用定制SCIM应用来将用户和用户组配置到您的Cato账户，请在Cato管理应用程序（CMA）中创建该应用。此外，您需要将Cato SCIM属性映射到您的IdP属性。

在 CMA 中创建自定义 SCIM 应用

要使用SCIM API，您必须先在CMA中创建定制SCIM应用。此应用允许您将身份提供商（IdP）与Cato平台集成。

要在CMA中创建定制SCIM应用：

从导航菜单选择访问 > 目录服务。
在 SCIM 选项卡下，点击新建。期间Always-On和防篡改被禁用多久。
输入应用程序的名称。
在 提供商下，选择自定义。
点击生成令牌并复制该值；保存后将无法再次访问，您需要创建一个新令牌。
点击保存。
在调用下面描述的 SCIM API 端点时，您需要以下值进行身份验证：
- SCIM基本URL： 用作API请求的基本路径
- 持有者令牌： 用于API请求的身份验证

Cato SCIM属性

这些是Cato用户和用户组的SCIM属性，您需要映射到相应的IdP属性。

Cato用户属性	说明
userName	用于身份验证的用户名
user.firstName	用户的名字
user.lastName	用户的姓氏
user.email	电子邮件地址
user.displayName	用户的显示名称
phoneNumbers[type eq "work"].value	用户的工作电话号码（包括前缀）
externalId	用户的ID(用于事件中)

Cato用户组属性	说明
active	在SCIM应用中分配并激活用户
displayName	用户组名称
members	属于该用户组的用户
externalId	用户组的ID（用于事件中）

了解Cato SCIM API

对Cato SCIM API进行身份验证

客户端使用RFC 6750定义的持有者令牌身份验证对SCIM API进行认证。所有API请求必须包含以下HTTP头：

Authorization: Bearer <access_token>
Content-Type: application/json

您可以从Cato管理应用程序获取访问令牌。

SCIM端点的基础路径

所有SCIM API端点使用以下基础路径：

/scim/v2/{accountId}/{sourceId}

路径参数：

accountId (string): 您的Cato租户账户的唯一标识符
sourceId (integer): Cato分配的用于唯一表示特定IdP集成的标识符

这些参数在所有请求中是必需的，但为了简洁起见，在本文中省略了个别端点路径中的参数。

管理用户

本节介绍如何使用Cato SCIM API创建、更新、删除和检索SCIM用户实体。

创建用户

HTTP方法：POST /Users

必填字段：

userName (string): 唯一用户名（例如电子邮件地址）
externalId (string): 来自IdP的外部标识符
active (boolean): 必须为true以激活用户

注意：id由SCIM服务返回，必须在后续API调用中使用。 externalId是可选的，不能在API路径中使用。

响应：

状态：201 已创建

错误：

400 错误请求: 无效架构
401 未授权
409 冲突: 重复 userName 或 externalId

更新用户

PUT

HTTP方法：PUT /Users/{id}

必填字段：

id: 来自Cato的内部SCIM ID

响应：

状态：200 成功

错误：

401 未授权
404 未找到
409 冲突: 重复 userName 或 externalId

PATCH

HTTP方法：PATCH /Users/{id}

响应：

状态：200 成功

错误：

400 错误请求：无效的架构或PATCH语法
401 未授权
404 未找到
409 冲突: 重复标识符

删除用户

HTTP方法：DELETE /Users/{id}

响应：

状态：204 无内容

这是一次软删除。用户仍然存在于系统中，但在搜索中不显示。

通过ID获取用户

HTTP方法：GET /Users/{id}

响应：

状态：200 成功

错误：

401 未授权
404 未找到

搜索用户

HTTP方法：GET /Users

查询参数：

filter: 查询用户过滤条件（例如：userName eq "user@domain.com"）
count（可选）
startIndex（可选）

支持的过滤器：

只支持eq
支持的属性：userName、email、givenName、familyName

复合过滤器仅支持以下格式：

filter=emails[type eq "work"] 和 email eq "bob@cato.com"

响应：

状态：200 成功

错误：

401 未授权

管理群组

本节介绍如何使用SCIM API在您的Cato环境中创建、更新、删除和检索群组实体。

创建群组

HTTP方法：POST /Groups

响应：

状态：201 已创建

错误：

401 未授权
409 冲突：重复的displayName或对象ID

更新群组

PUT

HTTP方法：PUT /Groups/{id}

响应：

状态：200 成功

错误：

401 未授权
404 未找到
409 冲突

PATCH

HTTP方法：PATCH /Groups/{id}

支持的PATCH路径：

displayName
members

响应：

状态：200 成功

错误：

400 错误请求：无效的架构或PATCH语法
401 未授权
404 未找到
409 冲突

删除群组

HTTP方法：DELETE /Groups/{id}

响应：

状态：204 无内容

重要：
这是一次硬删除。该群组已被永久移除。

通过ID获取群组

HTTP方法：GET /Groups/{id}

可选查询参数：

excludeAttributes（例如，members）

响应：

状态：200 成功

错误：

401 未授权
404 未找到

搜索群组

HTTP方法：GET /Groups

查询参数：

filter：仅支持displayName eq "群组名称"
count（可选）
startIndex（可选）

复合筛选或不支持的操作符会返回所有群组，不进行筛选。

响应：

状态：200 成功

错误：

401 未授权

注意

创建时id字段的行为

在用户和群组创建请求中，id字段是可选的。
如果省略，SCIM服务会生成一个唯一的id。
在后续API调用中始终使用返回的id值。

重要：
除非有必要，否则避免使用客户端生成的ID。 SCIM id是权威标识符。

删除行为

通过DELETE /Users/{id}用户删除会通过设置active字段为false执行软删除。用户可以通过GET /Users/{id}检索，但在GET /Users结果中被排除。
通过DELETE /Groups/{id}群组删除执行硬删除。该群组已被永久移除。