SCIM 用户 API 参考¶

您可以使用 SCIM 用户 API 来访问、创建和修改用户数据。

HTTP 标头¶

Snowflake SCIM API 使用持有者令牌进行 HTTP 身份验证。

向 Snowflake SCIM API 发出的每个 HTTP 请求都支持以下 HTTP 标头：

标头	值
:code:`Authorization`（必填）	`Bearer <access_token>`
`Content-Type`	`application/scim+json`
`Accept-Encoding`	`utf-8`
`Accept-Charset`	`utf-8`

用户属性¶

您可以在 API 请求正文中以 JSON 格式的键值对形式指定用户属性。这些对包含有关用户的信息，例如用户的显示名称或其电子邮件地址。身份提供商可以为每个属性指定自己的键名。例如，身份提供商可以使用 lastName 键取代 familyName，来标识用户的姓氏。Snowflake 不支持多值用户属性。

重要

下表中的 userName 和 loginName 属性均引用 userName 属性。Snowflake 支持为 userName 和 loginName 属性指定不同的值。

Snowflake 支持以下属性用于用户生命周期管理。

SCIM 用户属性	Snowflake 用户属性	类型	描述
`id`	`ID`	字符串	Snowflake 中用户不可变的唯一标识符 (GUID)。 Snowflake 不会在 DESCRIBE USER 或 SHOW USERS 输出中返回此值。对于需要此属性的端点上的请求，例如 `PATCH scim/v2/Users/{{id}}`，可使用 REST_EVENT_HISTORY 函数找到 `id`。检查 IdP 日志以确保值匹配。
`userName`	`NAME`、`LOGIN_NAME`	字符串	用于登录到 Snowflake 的标识符。有关这些属性的更多信息，请参阅 CREATE USER。
`name.givenName`	`FIRST_NAME`	字符串	用户的名字。
`name.familyName`	`LAST_NAME`	字符串	用户的姓氏。
`emails`	`EMAIL`	字符串	用户的电子邮件地址。
`displayName`	`DISPLAY_NAME`	字符串	提及用户时，用户界面中显示的文本。
`externalID`	不适用	字符串	预置客户端（例如 Azure、Okta）设置的唯一标识符。
`password`	`PASSWORD`	字符串	用户的密码。该值不会在 JSON 响应中返回。如果 SCIM 安全集成中的 `SYNC_PASSWORD` 属性设置为 `FALSE`，并且 SCIM API 请求指定 `password` 属性，Snowflake 会忽略 `password` 属性的值。API 请求中的所有其他属性都将正常处理。
`active`	`DISABLED`	布尔	设置为 `false` 时禁用用户。
`groups`	不适用	字符串	用户所属组的列表。`displayName` 组是必需的。用户的组不可变，必须使用 SCIM 组 API 更新其成员资格。
`meta.created`	`CREATED_ON`	字符串	将用户添加到 Snowflake 的时间。
`meta.lastModified`	`UPDATED_ON`	字符串	上次在 Snowflake 中修改用户的时间。
`meta.resourceType`	不适用	字符串	用户的资源类型。您应该使用 `user` 作为此属性的值。
`schemas`	不适用	字符串	以逗号分隔的字符串数组，用于指定命名空间 URIs。Snowflake 支持以下值： `urn:ietf:params:scim:schemas:core:2.0:User` `urn:ietf:params:scim:schemas:extension:enterprise:2.0:User` `urn:ietf:params:scim:schemas:extension:2.0:User`

自定义属性¶

您可以设置 RFC 7643 (https://datatracker.ietf.org/doc/html/rfc7643) 未定义的自定义属性，例如 defaultRole。

在执行 POST、PUT 和 PATCH 请求时，您可以使用以下命名空间来设置自定义属性：

urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

此命名空间是 Snowflake 中原始 SCIM 实现的一部分。在 Okta SCIM 安全集成中，只能使用此命名空间来设置自定义属性。

在 Microsoft Azure SCIM 安全集成或自定义 SCIM 集成中，您不能使用此命名空间来设置自定义属性。

urn:ietf:params:scim:schemas:extension:2.0:User

您可以使用此命名空间为所有 SCIM 集成设置自定义属性。在 Microsoft Azure SCIM 安全集成或自定义 SCIM 安全集成中，您必须使用此命名空间来设置自定义属性。

Snowflake 支持以下自定义属性：

SCIM 用户自定义属性	Snowflake 用户属性	类型	描述
`defaultWarehouse`	`DEFAULT_WAREHOUSE`	字符串	登录时默认为用户会话激活的虚拟仓库。
`defaultRole`	`DEFAULT_ROLE`	字符串	登录时默认为用户会话激活的主要角色。
`defaultSecondaryRoles`	`DEFAULT_SECONDARY_ROLES`	字符串	登录时在用户会话中处于活跃状态的辅助角色列表。您可以将此属性设置为 `ALL` 作为 `('ALL')` 的别名，也可以将此属性设置为 `NONE` 或 `""` 作为 `()` 的别名。
`type`	`TYPE`	字符串	用户的类型。默认：`null`。您可以将此属性设置为 `person`、`service`、`legacy_service` 或 `null`。有关用户类型的更多信息，请参阅 :ref:` 用户的 TYPE 对象属性 <label-user-type-property>`。

检查用户是否存在¶

方法和端点:

GET /scim/v2/Users?filter=userName eq "{{user_name}}"

描述:

返回与 userName 查询参数关联的用户的详细信息。

如果 HTTP 请求已成功完成，返回 HTTP 响应状态码 200。

获取用户详情¶

方法和端点:

GET /scim/v2/Users/{{user_id}}

描述:

返回与 user_id 路径参数关联的用户的详细信息。

如果 HTTP 请求已成功完成，返回 HTTP 响应状态码 200。

创建用户¶

方法和端点:

POST /scim/v2/Users

描述:

在 Snowflake 中创建一个用户。

如果 HTTP 请求已成功完成，返回 HTTP 响应状态码 201。

如果用户已存在或 HTTP 请求因不同的原因失败，Snowflake 将返回 HTTP 响应状态码 409。

示例:

创建 userName 和 loginName 映射到相同值的用户：

{
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:2.0:User"
  ],
  "userName": "test_user_1",
  "password": "test",
  "name": {
    "givenName": "test",
    "familyName": "user"
  },
  "emails": [
    {"value": "test.user@snowflake.com"}
  ],
  "displayName": "test user",
  "active": true
}

Copy

创建 userName 和 loginName 映射到不同值的用户：

备注

如果您使用 Okta 作为身份提供商，请按照此程序操作。

{
  "active": true,
  "displayName": "test user",
  "emails": [
    {"value": "test.user@snowflake.com"}
  ],
  "name": {
    "familyName": "test_last_name",
    "givenName": "test_first_name"
  },
  "password": "test_password",
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User",
    "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "snowflakeUserName": "USER5"
  },
  "userName": "USER5"
}

Copy

替换用户属性¶

方法和端点:

PATCH /scim/v2/Users/{{id}}

描述:

替换与 id 路径参数关联的用户的属性。

您必须将 op 设置为 replace，以执行此 HTTP 请求。

active 允许以下值：

false：停用用户。
true：激活用户。

如果 HTTP 请求已成功完成，返回 HTTP 响应状态码 200。

如果不成功，则返回 HTTP 响应代码 204。

示例:

停用用户并将其 givenName 更新为 deactivated_user：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "value": { "active": false }}
    {"op": "replace", "value": { "givenName": "deactivated_user" }}
  ],
}

Copy

更新 userName 和 loginName 映射到相同值的用户：

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {"op": "replace", "value": { "active": false }}
  ]
}

Copy

更新 userName 和 loginName 映射到不同值的用户。

如果 Okta 是身份提供商，请按照以下步骤操作。

{
  "Operations": [
    {
      "op": "replace",
      "path": "userName",
      "value": "test_updated_name"
    },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.snowflakeUserName",
      "value": "USER5"
    }
  ],
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]
}

Copy

更新用户¶

方法和端点:

PUT /scim/v2/Users/{{id}}

描述:

更新与 id 路径参数关联的用户的属性。

如果不成功，则返回 HTTP 响应代码 400。如果 HTTP 请求尝试更改不可变属性，或者所更改的属性在 Snowflake 中不存在，则请求不会成功。

示例:

更新用户及其 "defaultRole"、"defaultSecondaryRoles" 和 "defaultWarehouse" 属性。

要指定 "defaultRole"、"defaultSecondaryRoles" 和 "defaultWarehouse" 属性，您必须使用以下 extension 架构之一。defaultSecondaryRoles 属性仅接受 "ALL" 作为一个值。

备注

PUT 方法的成本比 PATCH 方法成本更高。改用 PATCH 操作。

{
  "schemas": [
   "urn:ietf:params:scim:schemas:core:2.0:User",
   "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
  ],
  "userName": "test_user_1",
  "password": "test",
  "name": {
    "givenName": "test",
    "familyName": "user"
  },
  "emails": [{
    "primary": true,
    "value": "test.user@snowflake.com",
    "type": "work"
  }
  ],
  "displayName": "test user",
  "active": true,
  "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
    "defaultRole" : "test_role",
    "defaultSecondaryRoles" : "ALL",
    "defaultWarehouse" : "test_warehouse"
  }
}

Copy

删除用户¶

方法和端点:: DELETE /scim/v2/Users/{{id}}
描述:: 删除与 id 路径参数关联的用户。