SCIMユーザーAPIリファレンス¶

SCIMユーザーAPIを使用して、ユーザーデータへのアクセス、作成、変更を行うことができます。

HTTPヘッダー¶

Snowflake SCIM API は、 HTTP 認証にベアラートークンを使用します。

Snowflake SCIM API への各 HTTP リクエストは、以下の HTTP ヘッダーを許可します。

ヘッダー	値
`Authorization` （必須）	`Bearer <access_token>`
`Content-Type`	`application/scim+json`
`Accept-Encoding`	`utf-8`
`Accept-Charset`	`utf-8`

ユーザー属性¶

JSONフォーマットのキーと値のペアとして、APIリクエストの本文でユーザー属性を指定できます。これらのペアには、ユーザーの表示名やメールアドレスなど、ユーザーに関する情報が含まれています。IDプロバイダーは、各属性に独自のキー名を指定できます。たとえば、IDプロバイダーは、 familyName の代わりに、 lastName というキーを使用してユーザーの姓を表すことができます。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`	N/A	文字列	プロビジョニングクライアント（例: Azure、Okta）によって設定された一意の識別子。
`password`	`PASSWORD`	文字列	ユーザーのパスワード。この値は JSON 応答で返されません。 SCIM セキュリティ統合の `SYNC_PASSWORD` プロパティが `FALSE` に設定され、 SCIM API リクエストが `password` 属性を指定している場合、Snowflakeは `password` 属性の値を無視します。APIリクエストにある他のすべての属性は、正常に処理されます。
`active`	`DISABLED`	boolean	`false` に設定されている場合は、ユーザーを無効にします。
`groups`	N/A	文字列	ユーザーが属するグループのリスト。グループ `displayName` は必須です。ユーザーのグループは不変であり、そのメンバーシップは SCIM グループ API を使って更新する必要があります。
`meta.created`	`CREATED_ON`	文字列	ユーザーがSnowflakeに追加された時間。
`meta.lastModified`	`UPDATED_ON`	文字列	ユーザーがSnowflakeで最後に変更された時刻。
`meta.resourceType`	N/A	文字列	ユーザーのリソースの種類。この属性の値として `user` を使うべきです。
`schemas`	N/A	文字列	名前空間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`

カスタム属性¶

defaultRole など、 RFC 7643 で定義されていないカスタム属性を設定できます。

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` のいずれかに設定できます。ユーザーのタイプの詳細については、ユーザーの TYPE オブジェクトプロパティを参照してください。

ユーザーが存在するかどうかを確認する¶

メソッドおよびエンドポイント:

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

説明:

userName クエリパラメーターに関連付けられたユーザーの詳細を返します。

HTTP リクエストが正常に完了した場合、 HTTP 応答ステータスコード 200 を返します。

ユーザーの詳細を取得¶

メソッドおよびエンドポイント:

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

説明:

user_id pathパラメーターに関連付けられているユーザーに関する詳細を返します。

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をIDプロバイダーとして使用している場合は、この手順に従ってください。

{
  "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 Pathパラメーターに関連付けられたユーザーの属性を置き換えます。

この HTTP リクエストを実行するには、 op を replace に設定する必要があります。

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がIDプロバイダーである場合は、この手順に従います。

{
  "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 path パラメータに関連付けられているユーザーの属性を更新します。

失敗した場合は、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 path パラメータに関連付けられているユーザーを削除します。