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 に設定します。
• 操作の終了結果:
  • ID データが MS Graph Users API エンドポイントに送信されると、すぐに処理され、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 クライアントに負わせます。 このメカニズムは、API クライアントが ID ストア内のユーザーに対して実行する操作を認識しているシナリオに適しています。

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 データ (costCenter、Pay Grade、badgeId など) を 任意 の ID データ (CSV/SQL/HR など) から送信できるようにすることです。 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. このジョブは、プロビジョニング ジョブの属性マッピングを取得し、一致する属性ペアを書き留めます (既定では、 API 属性は Microsoft Entra ID のとの照合に使用されます)。
2. この既定の属性照合ペアは変更できます。
3. ジョブは、一括要求ペイロードに存在する各操作を抽出します。
4. ジョブは、要求内の値と一致する識別子 (既定では属性 externalId) をチェックし、それを使用して、一致する employeeId 値を持つユーザーが Microsoft Entra ID に存在するかどうかを確認します。
5. ジョブで一致するユーザーが見つからない場合、ジョブは同期規則を適用し、ターゲット ディレクトリに新しいユーザーを作成します。

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

UPN の一意の値を生成する方法

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

一意の UPN を生成するために考慮できるオプションを次に示します。

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

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

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

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

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

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

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

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

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

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

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

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

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

API 主導の受信プロビジョニングをサポートする複数のアプリを作成できますか?

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

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

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

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

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

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

• 両方のアプリで同じ一致する識別子ペアが使用されます (externalId<->employeeId)

/bulkUpload API エンドポイントを使用して終了を処理する方法

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

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

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

ユーザーの誤った無効化/削除を防ぐにはどうすればよいですか?

誤って削除されないようにして回復するには、プロビジョニング アプリで 誤削除しきい値を構成 し、 オンプレミスの Active Directory のごみ箱を有効にすることをお勧めします。 プロビジョニング アプリの [属性マッピング] ブレードの [ ターゲット オブジェクト アクション ] で、 削除 操作を無効にします。

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

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

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

いいえ、すべてのリクエストで人事システム／「信頼できる情報源」からすべてのユーザーを送信する必要はありません。 作成または更新したいユーザーを送信してください。

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

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

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

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

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

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

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

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

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

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

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

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

  • ライフサイクル ワークフローで、Joiner ワークフローを定義し、 Logic Apps プロセスを呼び出すカスタム拡張機能タスクを定義します。このタスクは、人事システムを更新するか、HR システムによって使用される CSV ファイルを生成します。

次のステップ

• API 駆動型インバウンド プロビジョニング アプリを構成する
• API ドリブンの受信プロビジョニングの詳細については、 インバウンド ユーザー プロビジョニング API の概念に関するページを参照してください。