--- title: "使用Cato SCIM API定制SCIM应用程序" slug: "using-the-cato-scim-api-for-custom-scim-apps" updated: 2026-07-30T03:36:21Z published: 2026-07-30T03:36:21Z canonical: "knowledge.catonetworks.com/using-the-cato-scim-api-for-custom-scim-apps" --- > ## Documentation Index > Fetch the complete documentation index at: https://knowledge.catonetworks.com/llms.txt > Use this file to discover all available pages before exploring further. # 使用Cato SCIM API定制SCIM应用程序 本文描述如何使用Cato的SCIM API通过身份提供商(IdP)进行用户和用户组配置。 有关 IdP 租户中自定义 SCIM 应用程序的更多信息,请参见 [为 IdP 创建自定义 SCIM 应用程序](/v1/docs/creating-a-custom-scim-app-for-an-idp)。 ## 自定义 Cato SCIM 应用 要使用定制SCIM应用来将用户和用户组配置到您的Cato账户,请在Cato管理应用程序(CMA)中创建该应用。 此外,您需要将Cato SCIM属性映射到您的IdP属性。 ### 在 CMA 中创建自定义 SCIM 应用 要使用SCIM API,您必须先在CMA中创建定制SCIM应用。 此应用允许您将身份提供商(IdP)与Cato平台集成。 **要在CMA中创建定制SCIM应用:** 1. 从导航菜单选择**访问 > 目录服务**。 2. 在 SCIM 选项卡下,点击 **新建**。期间Always-On和防篡改被禁用多久。 3. 输入应用程序的名称。 4. 在 **提供商**下,选择**自定义**。 5. 点击**生成令牌**并复制该值;保存后将无法再次访问,您需要创建一个新令牌。 6. 点击 **保存**。 7. 在调用下面描述的 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头: ```plaintext Authorization: Bearer Content-Type: application/json ``` 您可以从Cato管理应用程序获取访问令牌。 ### SCIM端点的基础路径 所有SCIM API端点使用以下基础路径: ```plaintext /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` - 复合过滤器仅支持以下格式: ```plaintext 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 无内容` > [!NOTE] > 重要: > > 这是一次硬删除。 该群组已被永久移除。 ### 通过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`值。 > [!NOTE] > 重要: > > 除非有必要,否则避免使用客户端生成的ID。 SCIM id是权威标识符。 ### 删除行为 - 通过`DELETE /Users/{id}`**用户删除**会通过设置`active`字段为`false`执行*软删除*。 用户可以通过`GET /Users/{id}`检索,但在`GET /Users`结果中被排除。 - 通过`DELETE /Groups/{id}`**群组删除**执行*硬删除*。 该群组已被永久移除。