使用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应用：

  1. 从导航菜单中，选择 访问 > 目录服务。

  2. 在 SCIM 选项卡下，点击 新建。

  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头：

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 错误请求: 无效架构或补丁语法

  • 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}群组删除执行硬删除。 该群组已被永久移除。

这篇文章有帮助吗？

0 人中有 0 人觉得有帮助

0 条评论