API 駆動型インバウンド プロビジョニングに関するよくあるご質問

  • [アーティクル]

この記事では、API 駆動型インバウンド プロビジョニングに関するよくあるご質問 (FAQ) とその回答を紹介します。

新しいインバウンド プロビジョニング /bulkUpload API と MS Graph Users API はどのように異なりますか?

プロビジョニング /bulkUpload API と MS Graph Users API エンドポイントには大きな違いがあります。

  • ペイロード形式: MS Graph Users API エンドポイントでは、OData 形式のデータが必要です。 新しいインバウンド プロビジョニング /bulkUpload API の要求ペイロード形式では、SCIM スキーマ コンストラクトが使用されます。 この API を呼び出す際には、'Content-Type' ヘッダーを application/scim+json に設定します。
  • 操作の終了結果:
    • MS Graph Users API エンドポイントに送信された ID データはすぐに処理され、Microsoft Entra のユーザー プロファイルで作成、更新、削除操作が実行されます。
    • プロビジョニング /bulkUpload API に送信された要求データは、Microsoft Entra プロビジョニング サービスによって "非同期的" に処理されます。 プロビジョニング ジョブでは、IT 管理者によって構成されたスコーピング規則、属性マッピング、変換が適用されます。これにより、Microsoft Entra ユーザー プロファイルまたはオンプレミス AD ユーザー プロファイルに対する Create/Update/Delete 操作が開始されます。
  • IT 管理者による制御が維持される: API 駆動型インバウンド プロビジョニングを使用すると、IT 管理者は、受信 ID データの処理方法と Microsoft Entra の属性へのマップ方法をいっそう細かく制御できます。 ユーザー プロファイルで属性値を設定する前に、特定の種類の ID データ (請負業者データなど) を除外するようにスコーピング規則を定義し、変換関数を使用して新しい値を派生させることができます。

インバウンド プロビジョニング /bulkUpload API は標準の SCIM エンドポイントですか?

MS Graph インバウンド プロビジョニング /bulkUpload API は、要求ペイロードで SCIM スキーマを使用しますが、これは標準化された SCIM API エンドポイントではありません。 次に、その理由を示します。

通常、SCIM サービス エンドポイントは、SCIM ペイロードを使用して HTTP 要求 (POST、PUT、GET) を処理し、それらを ID ストアの (作成、更新、ルックアップ) のそれぞれの操作に変換します。 SCIM サービス エンドポイントは、ID を作成、更新、削除するかどうかの操作セマンティクスを指定する責任をSCIM API クライアントに委ねます。 このメカニズムは、ID ストア内のユーザーに対してどの操作を実行するかを API クライアントが認識しているシナリオに適しています。

MS Graph インバウンド プロビジョニング /bulkUpload は、次の 3 つの固有の要件に由来する異なるエンタープライズ ID 統合シナリオを処理するように設計されています。

  1. レコードを一括で非同期的に処理する機能 (たとえば、50,000 を超えるレコードの処理)
  2. ペイロードに任意の ID 属性を含める機能 (costCenter、pay grade、badgeId など)
  3. 操作セマンティクスを認識していない API クライアントをサポートする。 これらのクライアントは、生の "ソース データ" (CSV ファイル、SQL テーブル、HR レコードに含まれるレコードなど) のみにアクセスできる非 SCIM API クライアントです。 これらのクライアントには、各レコードを読み取り ID ストアでの Create/Update/Delete の操作セマンティクスを決定する処理機能がありません。

MS Graph インバウンド プロビジョニング /bulkUpload API の主な目的は、お客様が Microsoft Entra プロビジョニング サービスによる最終的な処理のために、"任意" の ID データ ソース (CSV、SQL、HR など) から "任意" の ID データ (costCenter、pay grade、badgeId など) を送信できるようにすることです。 Microsoft Entra プロビジョニング サービスは、このエンドポイントで受信した一括ペイロード データを使用し、IT 管理者によって構成された属性マッピング規則を適用して、データ ペイロードによってターゲット ID ストア (Microsoft Entra ID、オンプレミス AD) で (作成、更新、有効化、無効化) 操作が行われるかどうかを判断します。

プロビジョニング /bulkUpload API では、ターゲットとしてオンプレミスの Active Directory ドメインがサポートされていますか?

はい。プロビジョニング API では、ターゲットとしてオンプレミスの AD ドメインがサポートされます。

プロビジョニング アプリ用に /bulkUpload API エンドポイントを取得するにはどうすればよいですか?

/bulkUpload API は、"Microsoft Entra ID への API 駆動型インバウンド プロビジョニング" と "オンプレミスの Active Directory への API 駆動型インバウンド プロビジョニング" の種類のアプリでのみ使用できます。 各プロビジョニング アプリの一意な API エンドポイントは、プロビジョニング ブレードのホーム ページから取得できます。 [現在までの統計情報]>[技術情報の表示] と移動し、プロビジョニング API エンドポイント URL をコピーします。

形式は以下のとおりです。

https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/bulkUpload

プロビジョニング /bulkUpload API を使用して完全同期を実行するにはどうすればよいですか?

完全同期を実行するには、API クライアントを使用して、信頼できるソースからすべてのユーザーのデータを一括要求として API エンドポイントに送信します。 すべてのデータを API エンドポイントに送信したら、次の同期サイクルですべてのユーザー レコードが処理され、プロビジョニング ログ API エンドポイントを使用して進行状況を追跡できます。

プロビジョニング /bulkUpload API を使用して差分同期を実行するにはどうすればよいですか?

差分同期を実行するには、API クライアントを使用して、信頼されたソース上でデータが変更されたユーザーに関する情報のみを送信します。 すべてのデータを API エンドポイントに送信したら、次の同期サイクルですべてのユーザー レコードが処理され、プロビジョニング ログ API エンドポイントを使用して進行状況を追跡できます。

プロビジョニングの再起動はどのように動作しますか？

[プロビジョニングの再起動] オプションは、必要な場合にのみ使用します。 しくみは次のとおりです。

シナリオ 1:[プロビジョニングの再開] ボタンをクリックし、ジョブが現在実行中の場合、ジョブは既にステージングされている既存のデータの処理を続行します。 [プロビジョニングの再起動] 操作では、既存のサイクルは中断されません。 後続のサイクルでは、プロビジョニング サービスによってエスクローがクリアされ、新しい一括要求が選択され処理されます。

シナリオ 2:[プロビジョニングの再起動] ボタンをクリックし、ジョブが実行されていない場合には、後続のサイクルを実行する前に、プロビジョニング エンジンは再起動前にアップロードされたデータを消去し、エスクローをクリアし、新しい受信データのみを処理します。

プロビジョニング /bulkUpload API エンドポイントを使用してユーザーを作成するにはどうすればよいですか?

/bulkUpload API エンドポイントに関連付けられているプロビジョニング ジョブが、受信したユーザー ペイロードを処理する方法を以下に示します。

  1. ジョブは、プロビジョニング ジョブに対する属性マッピングを取得して、一致する属性ペアを記録します (既定では、Microsoft Entra ID の employeeId との照合には、externalId API 属性が使われます)。
  2. この既定の属性照合ペアは変更できます。
  3. 一括要求ペイロード内に存在する各操作を抽出します。
  4. ジョブは、要求で値が一致する ID (既定では属性 externalId) を調べ、それを使って、employeeId の値が一致するユーザーが Microsoft Entra ID に存在するかどうかを調べます。
  5. 一致するユーザーが見つからない場合、同期規則を適用し、ターゲット ディレクトリに新しいユーザーを作成します。

Microsoft Entra ID で適切なユーザーが作成されるようにするには、ソースと Microsoft Entra ID でユーザーを一意に識別する、適切な一致属性ペアをマッピングで定義します。

UPN 用の一意な値を生成するにはどうすればよいですか?

プロビジョニング サービスでは、重複している userPrincipalName (UPN) をチェックして競合を処理する機能は提供されません。 UPN 属性の既定の同期規則で既存の UPN 値が生成された場合、ユーザー作成操作は失敗します。

一意な UPN を生成するために検討できるオプションを以下に示します。

  1. API クライアントに一意な UPN 生成のロジックを追加します。
  2. UPN 属性の同期規則を RandomString 関数を使用するように更新し、マッピングの適用パラメーターを On object creation only に設定します。 例:

Join("", Replace([userName], , "(?<Suffix>@(.)*)", "Suffix", "", , ), RandomString(3, 3, 0, 0, 0, ), "@", DefaultDomain())

  1. オンプレミスの Active Directory にプロビジョニングする場合は、SelectUniqueValue 関数を使用し、マッピングの適用パラメーターを On object creation only に設定できます。

プロビジョニング /bulkUpload API エンドポイントに、より多くの HR 属性を送信するにはどうすればよいですか?

既定では、API エンドポイントでは、SCIM コア ユーザー スキーマとエンタープライズ ユーザー スキーマの一部である属性の処理がサポートされます。 さらに属性を送信する場合は、プロビジョニング アプリ スキーマを拡張し、新しい属性を Microsoft Entra の属性にマップして、それらの属性を送信するように一括要求を更新できます。 チュートリアル「API 主導のプロビジョニングを拡張してカスタム属性を同期する」を参照してください。

プロビジョニング フローから特定のユーザーを除外するにはどうすればよいですか?

すべてのユーザーを API エンドポイントに送信するが、プロビジョニング フローには特定のユーザーのみを含め、残りのユーザーを除外したいというシナリオもあり得ます。

これはスコープ フィルターを使用して実現できます。 プロビジョニング アプリの構成では、ソース オブジェクトスコープを定義し、"包含ルール" (たとえば、部門 EQUALS Sales のユーザーのみを処理) または "除外ルール" (たとえば、部門 NOT EQUALS Sales で Sales に属するユーザーを除外) を使用して特定のユーザーを処理から除外できます。

「スコープ フィルターを使用してプロビジョニングするユーザーまたはグループのスコープを設定する」を参照してください。

プロビジョニング /bulkUpload API エンドポイントを使用してユーザーを更新するにはどうすればよいですか?

/bulkUpload API エンドポイントに関連付けられているプロビジョニング ジョブが、受信したユーザー ペイロードを処理する方法を以下に示します。

  1. プロビジョニング ジョブは、プロビジョニング ジョブに対する属性マッピングを取得して、一致する属性ペアを記録します (既定では、Microsoft Entra ID の employeeId との照合には、externalId API 属性が使われます)。 この既定の属性照合ペアは変更できます。
  2. ジョブは、一括要求ペイロードから操作を抽出します。
  3. ジョブは、SCIM 要求で値が一致する ID (既定では API 属性 externalId) を調べ、それを使って、employeeId の値が一致するユーザーが Microsoft Entra ID に存在するかどうかを調べます。
  4. 一致するユーザーが見つかると、同期規則が適用され、ソース プロファイルとターゲット プロファイルが比較されます。
  5. 一部の値が変更されたと判断された場合は、ディレクトリ内の対応するユーザー レコードが更新されます。

Microsoft Entra ID で適切なユーザーが更新されるようにするには、ソースと Microsoft Entra ID でユーザーを一意に識別する、適切な一致属性ペアをマッピングで定義します。

API 駆動型インバウンド プロビジョニングをサポートする複数のアプリを作成できますか?

はい、できます。 複数のプロビジョニング アプリが必要になるシナリオを次に示します。

シナリオ 1: たとえば、3 つの信頼できるデータ ソースがあるとします。1 つは従業員用、もう 1 つは請負業者用、もう 1 つはベンダー用です。 ID の種類ごとに 1 つずつ、独自の属性マッピングを使用して、3 つの個別のプロビジョニング アプリを作成できます。 各プロビジョニング アプリには一意な API エンドポイントがあり、それぞれのペイロードを各エンドポイントに送信できます。

各ジョブの一意な API エンドポイントは、プロビジョニング ブレードのホーム ページから取得できます。 [現在までの統計情報]>[技術情報の表示] と移動し、プロビジョニング API エンドポイント URL をコピーします。

シナリオ 2: 信頼できるソースが複数あり、それぞれに独自の属性が設定されているとします。 たとえば、HR はジョブ情報属性 (jobTitle、employeeType など) を提供し、Badging System はバッジ情報属性 (拡張属性を使用して表される badgeId など) を提供します。 このシナリオでは、次の 2 つのプロビジョニング アプリを構成できます。

  • HR ソースから属性を受け取り、ユーザーを作成するプロビジョニング アプリ #1。

  • Badging システムから属性を受け取り、ユーザー属性のみを更新するプロビジョニング アプリ #2。 このアプリの属性マッピングはバッジ情報属性に制限され、[ターゲット オブジェクト アクション] では更新のみが有効になります。

  • 両方のアプリで同じ照合 ID ペアが使用されます (externalId<->employeeId)

/bulkUpload API エンドポイントを使用して終了を処理するにはどうすればよいですか?

終了を処理するには、Microsoft Entra ID で accountEnabled フラグを設定するために使用されるソース内の属性を特定します。 オンプレミスの Active Directory にプロビジョニングする場合は、そのソース属性を accountDisabled 属性にマップします。

既定では、SCIM コア ユーザー スキーマ属性 active に関連付けられている値によって、ターゲット ディレクトリ内のユーザーのアカウントの状態が決まります。

属性が true に設定されている場合、既定のマッピング規則によりアカウントが有効になります。 属性が false に設定されている場合、既定のマッピング規則によりアカウントが無効になります。

不注意によるユーザーの無効化/削除を防ぐにはどうすればよいですか?

誤削除を防止するには、また誤削除から復旧するには、プロビジョニング アプリで誤削除のしきい値を構成し、オンプレミスの Active Directory のごみ箱を有効化することをお勧めします。 プロビジョニング アプリの [属性マッピング] ブレードの [対象オブジェクトのアクション] で、削除操作を無効にします。

削除されたアカウントの復旧

  • 操作のターゲット ディレクトリが Microsoft Entra ID の場合、一致したユーザーは論理的に削除されます。 ユーザーは、削除後 30 日間は Microsoft Entra 管理センターの [削除済みのユーザー] ページに表示され、その期間内であれば復元できます。
  • 操作のターゲット ディレクトリがオンプレミスの Active Directory の場合、一致するユーザーは物理的に削除されます。 Active Directory のごみ箱が有効になっている場合は、削除されたオンプレミス AD ユーザー オブジェクトを復元できます。

毎回の要求で HR システムからすべてのユーザーを送信する必要がありますか?

いいえ、毎回の要求で HR システム/"信頼できるソース" からすべてのユーザーを送信する必要はありません。 作成または更新したいユーザーのみを送信してください。

API はすべての HTTP アクション (GET/POST/PUT/PATCH) をサポートしていますか?

いいえ。/bulkUpload プロビジョニング API エンドポイントは POST HTTP アクションのみをサポートします。

ユーザーを更新する場合、PUT/PATCH 要求を送信する必要がありますか?

いいえ。API エンドポイントは PUT/PATCH 要求をサポートしていません。 ユーザーを更新するには、POST 一括要求ペイロードでユーザーに関連付けられているデータを送信します。

API エンドポイントによって受信されたデータを処理するプロビジョニング ジョブは、POST 要求ペイロードで受信したユーザーを、作成、更新、有効化、無効化する必要があるかどうかを構成された同期規則に基づいて自動的に検出します。 API クライアントとしては、ユーザー プロファイルを更新する場合は、これ以上の手順を実行する必要はありません。

書き戻しはどのようにサポートされていますか?

現在の API では、インバウンド データのみがサポートされています。 ここでは、Microsoft Entra ID によって生成されたメール、ユーザー名、電話など、HR システムに戻すことができる属性の書き戻しの実装に関して考慮すべきいくつかのオプションを示します。

  • オプション 1 – HR エンドポイント/プロキシ サービスへの SCIM 接続で、HR ソースの更新を行う

    • レコード システムがユーザー更新用の SCIM エンドポイントを提供する場合エンタープライズ アプリ ギャラリーでカスタム SCIM アプリケーションを作成し、 ドキュメントに従ってプロビジョニングを構成することができます。
    • レコードのシステムで SCIM エンドポイントが提供されない場合は、更新を受け取り、変更を HR システムに伝達するプロキシ SCIM サービスを設定する可能性を検討します。

  • オプション 2 – 書き戻しシナリオに Microsoft Entra ECMA コネクタを使用する

    • 顧客の要件に応じて、ECMA コネクタの 1 つを使用できるかどうかを検討します (PowerShell/SQL/Web サービス)。

  • オプション 3 – Joiner ワークフローでライフサイクル ワークフロー カスタム拡張機能タスクを使用する

次のステップ