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

[アーティクル]
05/11/2022

注: このトピックは Microsoft クラウドソリューションプロバイダー (CSP) アプリケーション開発者のみに適用されます。Microsoft クラウドソリューションプロバイダー (CSP) プログラムは、マイクロソフトパートナーが Microsoft Online サービスを再販し、管理することを可能とします。

このトピックは、パートナーが管理する顧客のアプリケーションへのアクセスを Microsoft Graph を介し、認証コードの許可のフローまたはサービス間クライアント資格情報フローにより許容する方法を説明します。

重要: CSP アプリケーションからの Microsoft Graph の呼び出しは、ディレクトリリソース (user、group、device、organization など) と Intune リソースでのみサポートされています。

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

CSP プログラムは、マイクロソフトパートナーが Microsoft Online サービス (Microsoft 365、Microsoft Azure、CRM Online など) を再販し、管理することを可能とします。顧客サービスの管理は、特に任命されたパートナーユーザー (エージェントといいます) にその顧客の環境をアクセスし、設定する権限を与える Delegated Admin 権限により行います。

さらに、パートナー開発者は顧客の Microsoft サービスを管理する パートナー管理アプリケーション を作成できます。すべての顧客は自動的にパートナー管理アプリケーションを事前承認するため、パートナー管理アプリケーションは 事前承認 アプリケーションとも呼ばれます。つまり、顧客テナントのユーザーがパートナー管理アプリケーションを使用するには、同意のプロンプトは不要です。パートナー管理アプリケーションは Delegated Admin 権限を継承するため、パートナーエージェントもパートナー管理アプリケーションを介して顧客にアクセスする権限を持ちます。

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

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

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

マルチテナントアプリケーションの登録と構成

ここで必要な最初の手順は、他のマルチテナントのアプリケーションの登録と設定の手順とほぼ同じです。

Azure ポータルを使い、パートナーテナントにアプリケーションを登録します。パートナー管理アプリケーションとして機能するよう、アプリケーションを multi-tenant app として設定します。また、アプリが複数の地域で配布、販売される場合は、ここで示すようにそれぞれの地域で登録する必要があります。
再度 Azure ポータルから、最小限の特権のアプローチにより 必要となる権限 でマルチテナントのアプリケーションを設定します。

最後に、パートナー管理アプリに、すべての顧客に対して設定された権限を付与します。これは、Azure AD powershell V2 または Microsoft Graph PowerShell を使用して、アプリを表す servicePrincipal を Partner テナントの Adminagents グループに追加することで行えます。以下の手順に従って、Adminagents グループ、servicePrincipal を検索し、グループに追加します。

Azure AD PowerShell
Microsoft Graph PowerShell

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

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

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

使用しているアプリケーションと同じ appId を持つサービスプリンシパルを検索します。
```
$sp = Get-AzureADServicePrincipal -Filter "appId eq '{yourAppsAppId}'"
```
最後に、サービスプリンシパルを Adminagents グループに追加します。
```
Add-AzureADGroupMember -ObjectId $group.ObjectId -RefObjectId $sp.ObjectId
```

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

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

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

使用しているアプリケーションと同じ appId を持つサービスプリンシパルを検索します。
```
$sp = Get-MgServicePrincipal -Filter "appId eq '{yourAppsAppId}'"
```
最後に、サービスプリンシパルを Adminagents グループに追加します。
```
New-MgGroupMember -GroupId $group.Id -DirectoryObjectId $sp.Id
```

トークン取得のフロー

パートナー管理アプリケーションのトークン取得フロー、つまり認証コード付与のフローとサービス間クライアント資格情報のフローは、普通のマルチテナントのアプリケーションと同じです。

すべての顧客テナントへの事前承認済みアクセス以外に、パートナー管理アプリケーションにはもうひとつの機能があります。それは、エージェントがアプリケーションを使って顧客テナントのデータへアクセスできるようにする機能です (delegated admin 権限を使って)。概念的には次のように動作します。

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

これは、標準的な認証コード付与のフローですが、エージェントがパートナーのアカウントを使用してサインインする必要がある点が異なります。わかりやすくするため、パートナーテナントを partner.com (エージェントのホームテナント) とし、顧客を customer.com とします。

認証コードを取得するアプリケーションは /authorize エンドポイントに要求を送信します。ターゲットテナントとして 顧客テナント (この例では customer.com) を指定しなくてはなりません。エージェントは、引き続き自分の username@partner.com アカウントでサインインします。
```
GET https://login.microsoftonline.com/customer.com/oauth2/authorize
```
承認コードを使用してアクセストークンを取得します。この例 customer.com では、token エンドポイントに要求を送信するときに、アプリはターゲットテナントとして 顧客テナント を使用する必要があります。
```
POST https://login.microsoftonline.com/customer.com/oauth2/token
```
トークンへのアクセスができたら、HTTP 認証ヘッダーにトークンを入れて Microsoft Graph を呼び出します。
```
GET https://graph.microsoft.com/beta/users
Authorization: Bearer <token>
```

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

今のところ、CSP 顧客契約は 1 つの地域に限定されています。パートナー管理アプリケーションには、いくつかの制限があります。つまり、販売を展開する地域ごとにテナントを用意する必要があります。たとえば、パートナー管理アプリケーションを米国のテナントに登録し、顧客は EU に在住している場合は、パートナー管理アプリケーションは機能しません。同一地域の顧客を管理するには、各地域パートナーのテナントは、各自の一連のパートナー管理アプリケーションを維持する必要があります。これにより、アプリケーションに顧客のサインイン名を取得し、地域専用のどのパートナー管理アプリケーションを使用するか決定するための (サインイン前の) ロジックを追加する必要が生じることがあります。

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

Partner Center API を使用して新しい顧客を作成すると、新しい顧客テナントも作成されます。さらに、パートナーの関連付けが行われ、この新しい顧客テナントとレコードのパートナーとしての関連付けが行われます。このパートナー関係が新しい顧客テナントに反映されるには最長 3 分かかることがあります。作成後すぐにアプリケーションが直接に Microsoft Graph を呼び出すと、アクセス拒否エラーを受け取ることがあります。既存の顧客が招待を受け付けると、これと同じ遅延が発生することがあります。このため、事前承認は顧客テナントに存在しているパートナー関係に依存します。

この問題を回避するには、顧客の作成後、パートナーアプリケーションは (Microsoft Graph 呼び出しのための) トークン取得のために Azure AD を呼び出す前に 3 分間 待機することを推奨します。ほとんどの場合がこれで解決します。3 分待機しても認証エラーが発生する場合は、さらに 60 秒間待機してからもう一度お試しください。

注: 再試行のためには、Microsoft Graph を呼び出す前に Azure AD から新しいアクセストークンを取得する必要があります。既存のアクセストークンを使用して Microsoft Graph を呼び出すことはできません。アクセストークンは 1 時間のみ有効で、事前承認の要求が含まれないためです。

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