Cato SCIM APIを使用してカスタムSCIMアプリを作成する

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

IdPテナントにおけるカスタムSCIMアプリに関する詳細情報については、IdPのためのカスタムSCIMアプリの作成を参照してください。

カスタムCato SCIMアプリ

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

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

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

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

  1. ナビゲーションメニューからアクセス > ディレクトリサービスを選択します。

  2. SCIMタブの下で、新規作成をクリックしてください。

  3. アプリの名前を入力してください。
  4. プロバイダーの下で、カスタムを選択してください。
  5. トークン生成をクリックし、その値をコピーします。保存後は利用できなくなるため、新しいトークンを作成する必要があります。 

  6. 保存をクリックしてください。

  7. 以下に示すSCIM APIエンドポイントを呼び出す際には、認証に以下の値が必要です。

    • SCIMベースURL: APIリクエストのベースパスとして使用

    • Bearerトークン: APIリクエストの認証に使用

Cato SCIM属性

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

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 Management Applicationから取得できます。

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 Created

エラー： 

  • 400 Bad Request: 無効なスキーマ

  • 401 Unauthorized 

  • 409 Conflict: 重複するuserNameまたはexternalId

ユーザーの更新

PUT

HTTPメソッド： PUT /Users/{id} 

必須フィールド： 

  • id: Catoからの内部SCIM ID

レスポンス： 

  • ステータス: 200 OK

エラー： 

  • 401 Unauthorized 

  • 404 Not Found 

  • 409 Conflict: 重複するuserNameまたはexternalId

PATCH

HTTPメソッド： PATCH /Users/{id} 

レスポンス： 

  • ステータス: 200 OK

エラー： 

  • 400 Bad Request: 無効なスキーマまたはパッチ構文

  • 401 Unauthorized 

  • 404 Not Found 

  • 409 Conflict: 重複する識別子

ユーザーの削除

HTTPメソッド：DELETE /Users/{id}

レスポンス：

  • ステータス: 204 No Content

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

IDでユーザーを取得

HTTPメソッド：GET /Users/{id}

レスポンス：

  • ステータス: 200 OK

エラー：

  • 401 Unauthorized

  • 404 Not Found

ユーザーの検索

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 未承認

グループの管理

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

グループの作成

HTTP メソッド:POST /Groups

レスポンス:

  • ステータス: 201 作成済み

エラー:

  • 401 未承認

  • 409 競合: 重複したdisplayNameまたはオブジェクトID

グループの更新

PUT

HTTP メソッド:PUT /Groups/{id}

レスポンス:

  • ステータス: 200 OK

エラー:

  • 401 未承認

  • 404 見つかりません

  • 409 競合

PATCH

HTTP メソッド:PATCH /Groups/{id}

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

  • displayName

  • members

レスポンス:

  • ステータス: 200 OK

エラー:

  • 400 不正なリクエスト: 無効なスキーマまたはパッチ構文

  • 401 未承認

  • 404 見つかりません

  • 409 競合

グループの削除

HTTP メソッド:DELETE /Groups/{id}

レスポンス:

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

注記

重要: これは完全な削除です。 グループは永久に削除されます。

IDからグループを取得する

HTTP メソッド:GET /Groups/{id}

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

  • excludeAttributes (例: members)

レスポンス:

  • ステータス: 200 OK

エラー:

  • 401 未承認

  • 404 見つかりません

グループの検索

HTTP メソッド:GET /Groups

クエリパラメータ:

  • filter: displayName eq "Group Name"のみがサポートされています

  • count (オプション)

  • startIndex (オプション)

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

レスポンス:

  • ステータス: 200 OK

エラー:

  • 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件のコメント