SCIM APIを使ってユーザーとグループの管理を自動化する方法

概要

SCIM（クロスドメインID管理システム）は、ユーザーとグループのプロビジョニングやプロビジョニング解除、ユーザーデータとグループデータの更新をお客様のIDプロバイダー（IdP）で行い、Udemy for Businessアカウントに自動で反映するための標準APIです。SCIMは、Okta、Azure AD、OneLoginなど多くのIDプロバイダーにサポートされていますが、独自のツールを作成してUdemy for Business SCIM APIを操作することも可能です。 

SCIMでは、JSON形式のデータによる標準化されたREST APIが使用されます。Udemy for Businessは、SCIM規格バージョン2.0をサポートしています。このAPIは、エンタープライズプランに加入しているすべてのお客様にご利用いただけます。

Udemy for Business SCIM APIでは、以下の機能をサポートしています。 

• ユーザーのプロビジョニング
• ユーザーのプロビジョニング解除（非アクティブ化/匿名化）
• メールアドレスの変更
• ユーザーの詳細情報の変更
• グループのプロビジョニング
• グループへのユーザーの追加/削除

SCIMプロトコルの説明

SCIMプロトコルは、ウェブ上でIDデータのプロビジョニングと管理を行うためのアプリケーションレベルのRESTプロトコルです。クライアントサーバー方式のプロトコルであり、クライアントがIDプロバイダー（IdP）でサーバーがUdemy for Businessです。

基本のフローは次のとおりです。

• お客様がIdPでユーザーにUdemy for Businessへのアクセスを許可すると、IdPからUdemy for Businessにこのユーザーがデータベースに存在するかどうかをチェックするためのリクエストが送信されます。発行されるのは、userNameまたはemailなどの属性によるユーザー検索リクエストです。
• ユーザーが存在しない場合は、IdPからユーザーの作成リクエストが送信されます。
• ユーザーが存在する場合は、IdPからユーザーの更新リクエストが送信されます。
• Udemy for Businessへのアクセスが取り消された場合は、IdPからUdemy for Businessのデータベースでユーザーを非アクティブ化または削除するためのリクエストが送信されます。
• IdPからは、ユーザーの詳細情報を変更するためのリクエストも送信可能です。

APIへのアクセス方法

SCIM APIに接続するための認証資格情報を取得するには、Udemy for Businessアカウントで管理 -> 設定 -> プロビジョニング（SCIM）ページを開き、SCIM統合を設定します。このページにアクセスできるのは管理者のみです。 

設定を開始をクリックします。

次に、プロバイダーを選択ドロップダウンでその他を選択します。

   トークンを作成するをクリックします。

この画面で、コピーをクリックして、Bearerトークンをクリップボードにコピーします。

リクエストには、次のようにBearerトークンのAuthorization HTTPヘッダーを指定します。

GET /scim/v2/Users HTTP/1.1

Host: myorganization.udemy.com

Accept: application/scim+json

Authorization: Bearer <ここにBearerトークンを入力>

Content-Type: application/scim+json

Udemy for Business SCIM APIにはHTTPプロトコルが使用されており、セキュアなHTTPS接続でのみ利用可能です。

APIのベースURLはhttps://<organization>.udemy.com/scim/v2/です。 

Udemy for Business SCIM APIと接続するアプリケーションを構築する場合は、この文書の末尾に付記されているSCIMのRFC文書を参照してください。Udemy for Business SCIM APIの実装は、この規格に準拠しています。

SCIM APIエンドポイント

情報エンドポイント

これらのエンドポイントは情報であり、クライアントの設定に使用します。認証は要求されません。したがって、これらのエンドポイントにアクセスする際に Authorizationヘッダーを指定する必要はありません。

GET /ServiceProviderConfiguration

サポートされているメソッドなど、Udemy for Business SCIMの実装に関する詳細情報を返します。

GET /Schemas

Udemy for Business SCIMの実装でサポートされているスキーマについての情報を返します。サポートされているスキーマは、UsersとGroupsです。

GET /Schemas/Users

Userリソースでサポートされているすべての属性を返します

GET /Schemas/Groups

Groupリソースでサポートされているすべての属性を返します。

Userエンドポイント

これらのエンドポイントを使用すれば、ユーザーのリスト、属性によるフィルタリング、新規ユーザーの追加、ユーザー情報の更新、ユーザーの非アクティブ化や匿名化を実行できます。アクセスできるユーザーは、SCIM APIを使って作成したユーザーに限られます。Udemy for Businessで作成したユーザーにアクセスするには、これらのユーザーをSCIMで調整する必要があります。調整についての詳細は以下のとおりです。

サポートされている属性

SCIM属性	必須か	説明
userName	はい	IdPでのuserName。一意でなければなりません。
name, { givenName, familyName }	いいえ	ユーザーの氏名。必須ではありませんが、ユーザーの特定に役立つため、これらの属性を常に指定することをお勧めします。
emails[type=”work”]]['value’]	はい	ユーザーのメールアドレス。一意でなければなりません。
active	はい	ユーザーを非アクティブ化/再アクティブするためのフラグ
title	いいえ	Userの肩書。例：「シニアエンジニア」。
externalId	はい	IdPにおけるユーザーのexternalId。一意でなければなりません。

注意：このリストに記載されていない属性を指定した場合は、無視されます。

GET /Users

ページ分割されたユーザーリストを返します。デフォルトでページ当たり12ユーザーです。countとstartIndexパラメーターを指定することで、結果セットをページ分割できます。例:

GET /scim/v2/Users?startIndex=1&count=100 HTTP/1.1

Host: myorganization.udemy.com

Accept: application/scim+json

Authorization: Bearer <ここにBearerトークンを入力>

• startIndexは、現在のリスト結果セットの冒頭の結果に適用される1から始まるインデックス（オフセット）
• countは、返されるリストの1ページに表示するリソース数（上限）。1回のリクエストで取得できるユーザー数は1,000人未満です。この項目を省略すると、デフォルトの12になります。

GET /Users?filter=

このエンドポイントは、特定の属性でユーザーをフィルタリングするために使用します。たとえば、userName属性を使えば次のような検索が可能です。

GET /Users?filter=userName eq "gloria.graynor”

注意：URLパラメーターはURLエンコードが必要です。この例では次のようになります。
GET /Users?filter=userName%20eq%20%22gloria.graynor%22

これにより、ユーザーリソースのリストが返されます。結果がない場合は、空のリストが返されます。

サポートされているフィルターは以下の通りです。

• userName
• externalID
• emails[type eq=”work”]

サポートされている演算子は以下の通りです。

• and
• eq

レスポンス:

• 成功した場合は、HTTPステータスコード200とエンティティのリスト
• サポートされていないフィルターが指定された場合は、HTTPステータスコード501

POST /Users

このエンドポイントは、Udemy for Businessで新規ユーザーを作成（プロビジョニング）するために使用します。 

レスポンスにはid属性が含まれます。これは、その後のあらゆるリクエストでこのユーザーを参照するために使用します。

注意：

• この方法で作成された新規ユーザーは、初回のサインインをするまでライセンスを消費しません。
• このユーザーにすでに保留中の招待状がある場合は、この時点で使用されます。
  ユーザーは、招待状に指定された内容にしたがってグループに追加され、適切な役割やコースを割り当てられます。
• すでにUdemy for Businessに存在しているユーザーを新規作成しようとした場合は、そのユーザーがSCIMの管理下に入ります（ 「ユーザー管理」ページで小さなリンクアイコンが表示されます）。ユーザーのステータスやライセンスの使用状況に変更は生じません。ユーザーがアクティブな場合は引き続きアクティブであり、非アクティブ化されている場合は非アクティブ化されたままです。

レスポンス:

• 成功した場合は、HTTPステータスコード201とユーザーのリソース
• 組織に同じuserNameがすでに存在している場合は、HTTPステータスコード409
• リクエストが検証をパスしなかった場合は、HTTPステータスコード400とエラーの詳細情報を記したレスポンスボディ

GET /Users/<id>

このエンドポイントは、特定のユーザーの詳細情報を取得するために使用します。上記リクエストのidパラメーターには、SCIMでユーザーを作成した際に返されたか、既存のすべてのユーザーを一覧表示した際に示された一意の識別子を指定します。

レスポンス:

• 成功した場合は、HTTPステータスコード200とユーザーリソース
• ユーザーが見つからなかった場合は、HTTPステータスコード404

PUT /Users/<id>

このエンドポイントは、Udemy for Businessのユーザー詳細情報の置き換え（上書き）に使用します。指定した場合、active属性を使用して、ユーザーを非アクティブ化や再アクティブ化できます。

レスポンス:

• HTTPステータスコード200と更新されたユーザーリソース
• ユーザーが存在しない場合は、HTTPステータスコード404。 
• 組織の所有者を非アクティブ化しようとした場合は、HTTPステータスコード400。

PATCH /Users/<id>

このエンドポイントは、Udemy for Businessのシステムでユーザー詳細情報の一部分を更新する場合に使用します。ユーザーの一部の属性だけを変更できます。ユーザー全体を置き換えるPUTとは異なります。 

active属性を含めた場合、ユーザーを非アクティブ化や再アクティブ化できます。

• 各リクエストのボディの「schemas」属性には必ず「urn:ietf:params:scim:api:messages:2.0:PatchOp」というURL値を指定します。
• HTTP PATCHリクエストのボディには「Operations」属性を必ず指定します。この値は1つ以上のPATCH操作の配列です。各PATCH操作オブジェクトには、必ず1つだけ「op」メンバーを指定して実行する処理を指示します。値には「add」、「remove」、「replace」の中の1つを記載できます。
• 「path」属性は空でもかまいませんが、その場合、「value」は{“path”: “value”}形式の辞書となります。

レスポンス:

• 成功した場合は、HTTPステータスコード200と更新されたユーザーのリソース
• ユーザーが見つからなかった場合は、HTTPステータスコード404
• 組織の所有者を非アクティブ化しようとした場合、または不正な操作を行った場合は、HTTPステータスコード400。

DELETE /Users/<id>

このエンドポイントは、Udemy for Businessのユーザーを削除またはプロビジョニング解除するために使用します。このリクエストが受理されるとユーザーは匿名化され、ユーザーの全データは完全に削除されます。これは危険な操作です。代わりにPUTまたはPATCHのアクティブ属性をfalseに設定することで、ユーザーを非アクティブ化することをお勧めします。

レスポンス:

• 成功した場合は、HTTPステータスコード204。

• ユーザーが見つからなかった場合は、HTTPステータスコード404。

グループエンドポイント

サポートされている属性

SCIM属性	必須か	説明
displayName	はい	グループ名。すべてのUdemy for Businessグループ内で一意でなければなりません。
externalId	いいえ	IDプロバイダーによるグループのexternalId

注意：このリストに記載されている以外の属性を指定した場合は、無視されます。

GET /Groups

このエンドポイントは、プロビジョニングしたすべてのグループのページ分割されたリストを取得するために使用します。結果をページ分割するには、startIndexとcountクエリストリングパラメーターが必要です。 

取得できるのはSCIMを使って作成したグループのみです。Udemy for Businessで作成したグループは取得できません。

GET /Groups?filter=

このエンドポイントは、特定の属性でグループをフィルタリングするために使用します。たとえば、displayName属性を使えば次のような検索が可能です。

GET /Groups?filter=displayName eq "Marketing”

これにより、グループリソースのリストを取得できます。結果がない場合は、空のリストが返されます。

パラメーターはURLエンコードする必要があります。したがって、上記リクエストは次のようになります。
GET /Groups?filter=displayName%20eq%20%22Marketing%22

サポートされているフィルターは以下の通りです。

• displayName
• externalId
• Id
• member.value

サポートされている演算子は以下の通りです。

• and
• eq

レスポンス:

• 成功した場合は、HTTPステータスコード200とエンティティのリスト
• サポートされていないフィルターが使われた場合は、HTTPステータスコード501

POST /Groups

このエンドポイントは、Udemy for Businessで新規グループを作成（プロビジョニング）するために使用します。 

レスポンス:

• 組織にプロビジョニングされた同名のグループがすでに存在している場合は、HTTPステータスコード409が返されます。Udemy for Businessでは409（Conflict）とともにuniquenessのscimTypeエラーコードが返されます。
• グループの作成に成功した場合は、グループの完全なレプリゼンテーションとHTTPステータスコード201（Created）とともに、作成されたグループリソースのURLを記したLocationヘッダーが返されます。

GET /Groups/<id>

このエンドポイントは、Udemy for Businessのグループ詳細情報を取得するために使用します。 

レスポンス:

• HTTPステータスコード200とグループリソース
• グループが見つからなかった場合は、HTTPステータスコード404

PUT /Groups/<id>

このエンドポイントは、Udemy for Businessのグループ詳細情報を置き換えるために使用します。

レスポンス:

• HTTPステータスコード200と更新されたグループリソース 
• グループが存在しない場合は、HTTPステータスコード404。 

PATCH /Groups/<id>

このエンドポイントは、Udemy for Businessにおけるグループ詳細情報の部分的な更新を行うために使用します。 

PATCHエンドポイントでは、さまざまな操作とその組み合わせが可能なため、他のエンドポイントよりも扱いにくい面があります。

• replaceは、特定の値を変更する操作です。Udemy for Businessの場合は、グループ名かメンバーです。
• removeは、グループからメンバーを削除する操作です。
• addは、グループにメンバーを追加する操作です。

ルールは以下の通りです。

• たとえば、メンバーを「replace」する操作の場合、プロビジョニングされていないメンバーはグループから削除されません。
• PATCHリクエストは、操作数に関係なくアトミックなものとして扱われます。

インプットの検証は次の通りです。

• 各リクエストのボディの「schemas」属性には必ず「urn:ietf:params:scim:api:messages:2.0:PatchOp」というURL値を指定します。
• HTTP PATCHリクエストのボディには「Operations」属性を必ず指定します。この値は1つ以上のPATCH操作の配列です。各PATCH操作オブジェクトには、必ず1つだけ「op」メンバーを指定して実行する処理を指示します。値には「add」、「remove」、「replace」の中の1つを記載できます。
• 「path」属性は空でもかまいませんが、その場合、「value」は{“path”: “value”}形式の辞書となります。
• 「Remove」操作の場合は「members」パスが必要です。
• 「Add」操作の場合は「members」または「externalId」「path」が必須です。
• 「Replace」操作の場合は、「members」パスを指定できます。指定されていない場合、グループ名などのグループ詳細情報は変更されますが、メンバーは変更されません。

ご注意：

• グループへのユーザーの割り当てと割り当て解除は非同期で行われます。そのため、変更はすぐにはUdemy for Businessに反映されません。
• ネスト化されたグループはサポートしていないため、このリクエストでは無視されます。

レスポンス:

• 操作に成功した場合は、HTTPステータスコード204。
• グループが存在しない場合は、HTTPステータスコード404。
• 組織のメンバーでないユーザーにグループを割り当てようとした場合は、HTTPステータスコード404とエラー詳細情報。
• リクエストが検証をパスしなかった場合は、HTTPステータスコード400とレスポンスボディのエラー詳細情報。

DELETE /Groups/<id>

このエンドポイントは、Udemy for Businessにおけるグループの削除またはプロビジョニング解除するために使用します。 

ルールは以下の通りです。

• グループにプロビジョニングされていないメンバーがいる場合は、プロビジョニングされているメンバーがグループから削除され、「OrganizationSCIMGroup」レコードが消去されます。

レスポンス:

• 操作に成功した場合は、HTTPステータスコード204。
• グループが存在しない場合は、HTTPステータスコード404。

参考文献

• SCIM overview: http://www.simplecloud.info
• RFC 7642, SCIM - Definitions, Overview, Concepts, and Requirements: https://tools.ietf.org/pdf/rfc7642.pdf
• RFC 7643, SCIM - Core Schema: https://tools.ietf.org/pdf/rfc7643.pdf
• RFC 7644, SCIM - Protocol: https://tools.ietf.org/pdf/rfc7644.pdf