クラウド ソリューション プロバイダーのアプリケーションからの Microsoft Graph の呼び出し

  • [アーティクル]

メモ： このトピックは、Microsoft Cloud Solution Provider (CSP) アプリケーション開発者 にのみ 適用されます。 Microsoft Cloud Solution Provider (CSP) プログラムを使用すると、Microsoft のパートナーは Microsoft Online サービスを顧客に再販および管理できます。

この記事では、 承認コード付与フロー または サービスからサービスへのクライアント資格情報フローを使用して、Microsoft Graph 経由でパートナーが管理する顧客データへのアプリケーション アクセスを有効にする方法について説明します。

重要

CSP アプリケーションからの Microsoft Graph の呼び出しは、ディレクトリ リソース (ユーザー、グループ、デバイス、organizationなど) とIntune リソースに対してのみサポートされます。

パートナー管理アプリケーションとは

CSP プログラムを使用すると、Microsoft のパートナーは、Microsoft Online Services (Microsoft 365、Microsoft Azure、CRM Online など) を顧客に再販および管理できます。 顧客サービスの管理は、委任された管理特権を使用して行われます。これにより、指定されたパートナー ユーザー (エージェントと呼ばれます) が顧客の環境にアクセスして構成できます。

さらに、パートナー開発者は、パートナー 管理アプリ を構築して顧客の Microsoft サービスを管理できます。 パートナーが管理するアプリは、多くの場合、すべての顧客がパートナーが管理するアプリに対して自動的に事前に管理されるため、 事前 調整済みアプリと呼ばれます。 つまり、いずれかの顧客テナントのユーザーがパートナーが管理するアプリのいずれかを使用している場合、ユーザーは同意を求めることなく使用できます。 パートナーが管理するアプリは、委任された管理特権も継承するため、パートナー エージェントはパートナーが管理するアプリケーションを通じて顧客に特権アクセスを取得することもできます。

パートナー管理アプリケーションのセットアップ方法

顧客のデータをアクセスする特権が付与された場合、アプリケーションはパートナー管理と表示されます。

注:パートナー管理アプリケーションはパートナーテナントにのみ設定でき、顧客テナントのリソースを管理するため、パートナー管理アプリケーションはマルチ テナント アプリケーションとして設定しなければなりません。

マルチテナント アプリを登録して構成する

ここで必要な最初の手順は、マルチテナント アプリケーションの登録と構成に使用されるのと同じ手順のほとんどに従います。

  1. Microsoft Entra 管理センターを使用して、パートナー テナントにアプリケーションを登録します。 パートナー管理アプリとして機能するには、 アプリケーションをマルチテナント アプリとして構成する必要があります。 さらに、アプリが複数の地理的リージョンにデプロイされ、販売されている場合は、 こちらの説明に従って、これらの各リージョンにアプリを登録する必要があります。
  2. 必要なアクセス許可を使用して、最小限の特権のアプローチを使用する必要があるマルチテナント アプリを、Microsoft Entra 管理センターを使用して再度構成します。

すべての顧客のためにアプリを事前に考える

最後に、パートナーが管理するアプリに、すべての顧客に対して構成されたアクセス許可を付与します。 これを行うには、Azure AD PowerShell V2 または Microsoft Graph PowerShell を使用して、アプリを表す servicePrincipal をパートナー テナントの Adminagents グループに追加します。 次の手順に従って 、Adminagents グループ servicePrincipal を見つけて、グループに追加します。

注:

Azure AD および MSOnline PowerShell モジュールは、2024 年 3 月 30 日の時点で非推奨となりました。 詳細については、 非推奨の更新プログラムに関するページを参照してください。 この日付以降、これらのモジュールのサポートは、Microsoft Graph PowerShell SDK への移行支援とセキュリティ修正に限定されます。 非推奨のモジュールは、2025 年 3 月 30 日まで引き続き機能します。

Microsoft Entra ID (旧称 Azure AD) と対話するには、Microsoft Graph PowerShell に移行することをお勧めします。 移行に関する一般的な質問については、移行に関する FAQ を参照してください。 メモ： バージョン 1.0.x の MSOnline では、2024 年 6 月 30 日以降に中断が発生する可能性があります。

  1. PowerShell セッションを開き、サインイン ウィンドウに、管理者資格情報を入力してパートナーのテナントに接続します。

    Connect-AzureAd

  2. Adminagents を表すグループを探します。

    $group = Get-AzureADGroup -Filter "displayName eq 'Adminagents'"

  3. 使用しているアプリケーションと同じ appId を持つサービス プリンシパルを検索します。

    $sp = Get-AzureADServicePrincipal -Filter "appId eq '{yourAppsAppId}'"

  4. 最後に、サービス プリンシパルを Adminagents グループに追加します。

    Add-AzureADGroupMember -ObjectId $group.ObjectId -RefObjectId $sp.ObjectId

トークン取得のフロー

パートナーが管理するアプリのトークン取得フロー ( 承認コード付与フロー と サービス間クライアント資格情報フロー ) は、通常のマルチテナント アプリと同じです。

すべての顧客テナントへの事前アクセスとは別に、パートナーが管理するアプリにはもう 1 つの機能があります。 これにより、エージェントはアプリを使用して顧客のテナント データにアクセスできます (委任された管理者特権を使用)。 概念的には次のように動作します。

  1. エージェントは、パートナー テナントが発行したエージェント自身のユーザー資格情報を使ってアプリケーションにサインインします。
  2. アプリケーションは目的となるパートナー管理顧客テナントへのアクセス トークンを要求します。
  3. アプリはアクセス トークンを使用して、Microsoft Graph を呼び出します。

これは、エージェントがパートナー アカウントを使用してサインインする必要がある点を除き、標準の 承認コード付与フローです。 これがどのように表示されるかを確認するには、パートナー テナントが partner.com (エージェントのホーム テナント) であり、顧客の 1 人が customer.com。

  1. 承認コードを取得します。アプリはエンドポイントに対して要求を/authorize行い、ターゲット テナントにcustomer.com対して顧客テナントを使用する必要があります。 エージェントは引き続き自分 username@partner.com のアカウントでサインインします。

    GET https://login.microsoftonline.com/customer.com/oauth2/authorize

  2. 承認コードを使用してアクセス トークンを取得します。この例 customer.com では、token エンドポイントに要求を送信するときに、アプリはターゲット テナントとして顧客テナントを使用する必要があります。

    POST https://login.microsoftonline.com/customer.com/oauth2/token

  3. トークンへのアクセスができたら、HTTP 認証ヘッダーにトークンを入れて Microsoft Graph を呼び出します。

    GET https://graph.microsoft.com/beta/users
Authorization: Bearer <token>

サポートする地域でのアプリケーションの登録

CSP カスタマー エンゲージメントは現在、1 つのリージョンに制限されています。 パートナーが管理するアプリケーションには、同じ制限があります。 つまり、販売するリージョンごとに個別のテナントが必要です。 たとえば、パートナーが管理するアプリが米国のテナントに登録されていても、顧客が EU にいる場合、パートナーが管理するアプリは機能しません。 リージョンの各パートナー テナントは、同じリージョン内の顧客を管理するために、独自のパートナー管理アプリのセットを維持する必要があります。 これには、顧客のサインイン ユーザー名を取得して、ユーザーにサービスを提供するために使用するリージョン固有のパートナーマネージド アプリ ID を決定するために、アプリで追加のロジック (サインイン前) が必要になる場合があります。

顧客作成後すぐに Microsoft Graph を呼び出す

パートナー センター API を使用して新しい顧客を作成すると、新しい顧客テナントが作成されます。 さらに、パートナー関係も作成されるため、この新しい顧客テナントのレコードのパートナーになります。 このパートナー関係は、新しい顧客テナントに反映されるまでに最大 3 分かかる場合があります。 アプリが作成直後に Microsoft Graph を呼び出した場合、アプリはアクセス拒否エラーを受け取る可能性があります。 既存の顧客が招待を受け入れると、同様の遅延が発生する可能性があります。 これは、事前コンデントが顧客テナントに存在するパートナー関係に依存しているためです。

この問題を回避するには、パートナー アプリで顧客の作成後 3 分待ってから、Microsoft Entra IDを呼び出してトークンを取得することをお勧めします (Microsoft Graph を呼び出す)。 ほとんどの場合がこれで解決します。 ただし、3 分待っても承認エラーが発生する場合は、60 秒以上待ってからやり直してください。

メモ：再試行時に、Microsoft Graph を呼び出す前に、Microsoft Entra IDから新しいアクセス トークンを取得する必要があります。 アクセス トークンは 1 時間に適しており、事前に同意されたアクセス許可の要求が含まれていないため、既に持っているアクセス トークンを使用して Microsoft Graph を呼び出しても機能しません。