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 用户属性	类型	描述
`allowedInterfaces`	`ALLOWED_INTERFACES`	字符串	Defines which Snowflake interfaces the user can access. Specified as a comma-delimited list of interfaces. For a list of possible interfaces, see CREATE USER. If a value other than `ALL` is specified, then users can only access the interface specified and cannot interact with any Snowflake data outside of the interface specified.
`defaultWarehouse`	`DEFAULT_WAREHOUSE`	字符串	登录时默认为用户会话激活的虚拟仓库。
`defaultRole`	`DEFAULT_ROLE`	字符串	登录时默认为用户会话激活的主要角色。
`defaultSecondaryRoles`	`DEFAULT_SECONDARY_ROLES`	字符串	登录时在用户会话中处于活跃状态的辅助角色列表。您可以将此属性设置为 `ALL` 作为 `('ALL')` 的别名，也可以将此属性设置为 `NONE` 或 `""` 作为 `()` 的别名。
`type`	`TYPE`	字符串	用户的类型。默认：`person`。您可以将此属性设置为 `person`、`service`、`legacy_service` 或 `null`。有关用户类型的更多信息，请参阅用户类型。
`snowflakeTags`	`SNOWFLAKE_TAGS`	字符串	Assign or update tag values associated with a user. Specify a comma-separated list of tags and tag values that are to be provisioned. These tags must already exist in the account and the integration must be properly provisioned. The format of each entry is as follows: `database name.schema name.tag name:tag value`. Each entry must point to a different tag. Each entry may optionally be surrounded by `[ ]` (square brackets). Here is an example of creating two tags and assigning values to them: `[cost_management.tags.cost_center:finance,cost_management.tags.type:PowerUser]`

TYPE 属性的使用说明¶

备注

The LEGACY_SERVICE type is being deprecated. Use the SERVICE type for services and applications. For a timeline of the deprecation of LEGACY_SERVICE, see 为单因素密码登录的弃用做好计划.

此列表描述了设置以下 SCIM 请求中 TYPE 属性的效果：

POST 请求以创建用户，并且 type 属性未指定或为 NULL，则 TYPE 属性设置为 PERSON。
PATCH request with a replace operation that specifies the type attribute as NULL, TYPE property doesn't change.
PUT 带替换操作的请求，且 type 属性未指定或为 NULL，则 TYPE 属性设置为 PERSON。
PATCH request with a remove operation that unsets the type attribute, the TYPE property doesn't change.

检查用户是否存在¶

方法和端点:

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@example.com"}
  ],
  "displayName": "test user",
  "active": true
}

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

备注

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

{
  "active": true,
  "displayName": "test user",
  "emails": [
    {"value": "test.user@example.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": "TEST_USER"
  },
  "userName": "test.user@example.com"
}

Create a user and assign two tags: cost_center = finance and type = PowerUser:

{
  "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"
    "snowflakeTags": "[cost_management.tags.cost_center:finance,cost_management.tags.type:PowerUser]"
  },
  "userName": "USER5"
}

替换用户属性¶

方法和端点:

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" }}
  ],
}

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

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

Update a user with userName and loginName mapped to different values. If Okta is your identity provider, follow this procedure instead.

{
  "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"]
}

Update tag values assigned to a user:

{
  "Operations": [
    {
      "op": "replace",
      "path": "userName",
      "value": "test_updated_name"
    },
    {
      "op": "replace",
      "path": "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.snowflakeTags",
      "value": "[cost_management.tags.cost_center:finance,cost_management.tags.type:PowerUser]"
    }
  ],
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"]
}

更新用户¶

方法和端点:

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@example.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"
  }
}

Update a user and their tag values. Omitting a tag value or omitting the tag entirely from the request will remove the tag from the user.

{
  "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",
    "snowflakeTags": "[cost_management.tags.cost_center:finance,cost_management.tags.type:PowerUser]"
  }
}

删除用户¶

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