Cato SCIM APIを利用したカスタムSCIMアプリの使用方法

この記事では、アイデンティティプロバイダ（IdP）を使用して、ユーザーおよびユーザーグループをプロビジョニングするためのCatoのSCIM APIの使用方法について説明します。

IdPテナントでのカスタムSCIMアプリに関する詳細については、「IdP用カスタムSCIMアプリの作成」をご覧ください。

カスタムCato SCIMアプリ

カスタムSCIMアプリを使用してユーザーとユーザーグループをCatoアカウントにプロビジョニングするには、Cato管理アプリケーション（CMA）でアプリを作成します。さらに、Cato SCIM属性をIdPの属性にマッピングする必要があります。

CMAでカスタムSCIMアプリを作成する

SCIM APIを使用するには、まずCMAでカスタムSCIMアプリを作成する必要があります。このアプリを使用して、アイデンティティプロバイダ（IdP）をCatoプラットフォームと統合することができます。

CMAでカスタムSCIMアプリを作成するための手順：

ナビゲーションメニューから、アクセス > ディレクトリサービスを選択します。
SCIMタブの下で、新規をクリックします。
アプリの名前を入力してください。
プロバイダ でカスタムを選択します。
トークン生成をクリックして、その値をコピーします。保存後は利用できなくなり、新しいトークンを作成する必要があります。
保存をクリックします。
以下のSCIM APIエンドポイントを呼び出す際、認証に必要な値は次の通りです：
- SCIMベースURL: APIリクエストの基準パスとして使用
- ベアラートークン: APIリクエストを認証するために使用

CatoのSCIM属性

これらは、IdPの対応する属性にマッピングする必要があるCatoのユーザーおよびユーザーグループのSCIM属性です。

Catoユーザー属性	説明
ユーザー名	認証用のユーザー名
user.firstName	ユーザーの名
user.lastName	ユーザーの姓
user.email	メールアドレス
user.displayName	ユーザーの表示名
phoneNumbers[type eq "work"].value	ユーザーの勤務先電話番号（プレフィックスを含む）
externalId	ユーザーのID (イベントで使用)

Catoユーザーグループ属性	説明
アクティブ	ユーザーが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 (文字列): Catoテナントアカウントの一意の識別子
sourceId (整数): CatoによってIdP統合を一意に表すために割り当てられた識別子

これらのパラメータはすべてのリクエストで必要ですが、簡潔さのためにこの記事では個々のエンドポイントパスから省略されています。

ユーザー管理

このセクションでは、Cato SCIM APIを使用してSCIMユーザーエンティティを作成、更新、削除、および取得する方法について説明します。

ユーザーを作成する

HTTP方法:POST /Users

必須フィールド:

userName (文字列): 一意のユーザー名（例：メールアドレス）
externalId (文字列): IdPからの外部識別子
active (ブール値): ユーザーを有効化するにはtrueである必要があります

注:idはSCIMサービスによって返され、その後のAPI呼び出しで使用されなければなりません。 externalIdはオプションであり、APIパスで使用できません。

レスポンス:

ステータス: 201 作成済み

エラー:

400 不正なリクエスト: 無効なスキーマ
401 認証されていません
409 コンフリクト: 重複する userName または externalId

ユーザーを更新する

PUT

HTTP方法:PUT /Users/{id}

必須フィールド:

id: Catoからの内部SCIM ID

レスポンス:

ステータス: 200 OK

エラー:

401 認証されていません
404 見つかりません
409 コンフリクト: 重複するuserNameまたはexternalId

PATCH

HTTP方法:PATCH /Users/{id}

レスポンス:

ステータス: 200 OK

エラー:

400 不正なリクエスト: 無効なスキーマまたはパッチ構文
401 認証されていません
404 見つかりません
409 コンフリクト: 重複する識別子

ユーザーを削除する

HTTP方法:DELETE /Users/{id}

レスポンス：

ステータス: 204 コンテンツなし

これはソフト削除です。ユーザーはシステムに残りますが、検索結果には表示されません。

IDでユーザーを取得する

HTTP方法:GET /Users/{id}

レスポンス：

ステータス: 200 OK

エラー：

401 認証されていません
404 見つかりません

ユーザーを検索

HTTP方法:GET /Users

クエリパラメータ：

filter: ユーザーをフィルタするクエリ（例：userName eq "user@domain.com"）
count (オプション)
startIndex (オプション)

サポートされるフィルタ：

eqのみに対応しています
サポートされている属性: userName, email, givenName, familyName
複合フィルタはこの形式のみサポートされます：
```
filter=emails[type eq "work"] and email eq "bob@cato.com"
```

レスポンス：

ステータス: 200 OK

エラー：

401 認証されていません

グループ管理

このセクションでは、Cato環境でSCIM APIを使用してグループエンティティを作成、更新、削除、および取得する方法について説明します。

グループを作成

HTTP方法:POST /Groups

レスポンス：

ステータス: 201 作成済み

エラー：

401 認証されていません
409 コンフリクト: 重複する displayName またはオブジェクトID

グループを更新

PUT

HTTP方法:PUT /Groups/{id}

レスポンス：

ステータス: 200 OK

エラー：

401 認証されていません
404 見つかりません
409 コンフリクト

PATCH

HTTP プロトコル種別：PATCH /グループ/{id}

サポートされているパッチパス：

表示名
メンバー

対応：

ステータス: 200 OK

エラー：

400 Bad Request: 無効なスキーマまたはパッチ構文
401 認証されていません
404 見つかりません
409 競合

グループを削除する

HTTP プロトコル種別：DELETE /グループ/{id}

対応：

ステータス: 204 コンテンツなし

重要：
これはハード削除です。該当のグループは永久に削除されます。

ID でグループを取得

HTTP プロトコル種別：GET /グループ/{id}

オプションクエリパラメーター：

属性を除外 (例: メンバー)

対応：

ステータス: 200 OK

エラー：

401 認証されていません
404 見つかりません

グループを検索

HTTP プロトコル種別：GET /グループ

クエリパラメーター：

フィルター: 例： displayName eq "グループ名"のみがサポートされています
カウント (オプション)
開始インデックス (オプション)

複合フィルターまたはサポートされていない演算子はフィルタリングせずにすべてのグループを返します。

対応：

ステータス: 200 OK

エラー：

401 認証されていません

注意

作成時のidフィールドの動作

id フィールドはユーザーおよびグループの作成リクエストでオプションです。
省略された場合、SCIM サービスが一意の id を生成します。
後続のAPI呼び出しでは、常に返されたid値を使用してください。

重要：
必要ない限り、クライアント生成のIDの使用を避けてください。 SCIM id は権威ある識別子です。

削除の動作

ユーザー削除は、DELETE /Users/{id}を介してソフト削除を実行し、activeフィールドをfalseに設定します。ユーザーはGET /ユーザー/{id} を介して取得可能ですが、GET /ユーザー結果からは除外されます。
グループの削除は、DELETE /グループ/{id}を介してハード削除を実行します。該当のグループは永久に削除されます。