SharePoint Framework ソリューションでの Azure AD でセキュリティ保護された API への接続

[アーティクル]
04/08/2023

SharePoint Framework ソリューションを構築する際に、Azure Active Directory (Azure AD) でセキュリティ保護された API に接続する必要がある場合があります。 SharePoint Framework では、ソリューションに必要な Azure AD アプリケーションとアクセス許可を指定することができ、全体管理者または SharePoint 管理者は、まだ必要なアクセス許可が付与されていない場合はそれらを付与することができます。 AadHttpClient を使用すれば、OAuth フローを自分で実装しなくても、Azure AD でセキュリティ保護された API に簡単に接続できます。

Web API アクセス許可の概要

Azure AD は、Office 365 から、組織が構築したカスタム基幹業務アプリケーションまで、さまざまなリソースをセキュリティで保護しています。これらのリソースに接続するには、アプリケーションが、特定のリソースへのアクセスを可能にする、有効なアクセストークンを取得する必要があります。アプリケーションは、アクセストークンを OAuth 承認フローの一部として取得できます。

SharePoint Framework ソリューションなど、シークレットを保存できないクライアント側のアプリケーションは、OAuth 暗黙的フローと呼ばれる特別な種類の OAuth フローを使用します。

クライアント側のソリューションを構築している開発者は、アプリケーション内で OAuth 暗黙的フローを使用することにより承認を実装する責任があります。 SharePoint Framework ソリューションでは、MSGraphClient と AadHttpClient (どちらも SharePoint Framework v1.4.1 で導入) 経由でフレームワークの一部として既に実装されています。

注:

v1.4.1 より前のバージョンの SharePoint Framework 上でソリューションを構築している場合でも、Azure AD でセキュリティ保護されたリソースに接続できます。この場合は、 Microsoft ID platfomr 認証ライブラリを直接使用して OAuth 暗黙的フローを実装する必要があります。詳細については、「Azure Active Directory でセキュリティ保護された API への接続」を参照してください。

SharePoint Framework の一部として、Azure AD でセキュリティ保護されたリソースへのアクセス許可を開発者が要求する方法と、管理者が管理する方法に関する特定のプロセスが定義されています。次の図はこの手順を示しています。

Azure AD アプリケーションへのアクセス許可の要求、付与、使用のフローを示す図

Azure AD で保護された特定のリソースへのアクセスを要求する SharePoint Framework ソリューションを構築している開発者は、これらのリソースと、必要なアクセス許可のスコープをソリューションマニフェストにリストします。ソリューションパッケージをアプリカタログに展開する際、SharePoint はアクセス許可要求を作成し、管理者に要求したアクセス許可を管理するよう求めます。要求されたアクセス許可それぞれに対して、全体管理者または SharePoint 管理者は特定のアクセス許可を付与するか、拒否するかを決定できます。

すべてのアクセス許可は、それを要求した特定のアプリケーションではなく、テナント全体に付与されます。管理者が特定のアクセス許可を付与すると、それは SharePoint Online クライアント拡張機能 の Azure AD アプリケーションに追加されます。そして、Microsoft によってすべての Azure AD でプロビジョニングされ、SharePoint Framework は、ソリューションに有効なアクセストークンを提供するために OAuth フローでそれを使用します。

利用可能なアプリケーションとアクセス許可を検索する

Office 365 テナントをセキュリティで保護しているターゲット Azure AD が、ソリューション内でアクセス許可を要求可能なアプリケーションを決定します。利用可能なアプリケーションのリストは、組織が使用している Office 365 ライセンスと、Azure AD に登録された基幹業務アプリケーションによって異なる場合があります。十分なアクセス許可を持っている場合は、テナントで利用可能なアプリケーションとアクセス許可のスコープを複数の方法で確認できます。

Azure portal または Azure AD 管理センターを使用する

Azure AD で使用可能なアプリケーションを確認する方法の 1 つとして、Azure portal または Azure AD 管理センターに移動します。

Azure AD 管理センターの左側のナビゲーションで、[エンタープライズアプリケーション] リンクを選択します。
[エンタープライズアプリケーション] ブレードの [管理] グループで、[すべてのアプリケーション] リンクを選択します。
接続したいアプリケーションを素早く探すには、アプリケーションの種類 (Microsoft アプリケーションまたはエンタープライズアプリケーション) で概要をフィルターにかけるか、名前または ID を使用して検索できます。

たとえば、Microsoft Graph への追加のアクセス許可を要求したい場合は、検索ボックスで graph を検索します。
アプリケーションを見つけたら、それを選択して追加の情報を確認します。アプリケーションのブレードの [管理] グループで、[プロパティ] を選択してアプリケーションのプロパティを開きます。
プロパティのリストから、[オブジェクト ID] プロパティの値をコピーします。これは、Microsoft Graph に追加のアクセス許可のスコープを要求するために必要です。代わりに、アプリケーションの [名前] をコピーし、アクセス許可要求内でそれを使用することもできます。

注:

[オブジェクト ID] はテナントごとに一意ですが、アプリケーションの [名前] はすべてのテナントで同じです。ソリューションを一度だけ構築して、それを異なるテナントに展開したい場合、ソリューションで追加のアクセス許可を要求する際にはアプリケーションの [名前] を使用する必要があります。

Azure PowerShell を使用する

注:

次のステップを実行する前に、Azure PowerShell をインストールする必要があります。または、Azure Cloud Shell PowerShell で、このセクションで説明されているコマンドレットを実行することもできます。

PowerShell で次を実行して、Azure サブスクリプションにサインインします (Azure Cloud Shell を使用している場合は必要ありません)。
```
Login-AzureRmAccount
```
次を入力してテナントで利用可能なアプリケーションを一覧表示します。
```
Get-AzureRmADServicePrincipal | sort DisplayName | ft DisplayName, Id
```
このコマンドレットを実行すると、テナントで使用可能なすべてのアプリケーションが一覧表示されます。アプリケーションごとに、その表示名とオブジェクト ID が表示されます。これらは、SharePoint Framework ソリューションでアプリケーションアクセス許可を要求するときに使用できます。

Azure CLI を使用する

注:

次の手順を実行する前に、Azure CLI をインストールする必要があります。または、Azure Cloud Shell で、あるいは Docker コンテナーとして Azure CLI を実行することもできます。

CLI を自分のマシンまたは Docker コンテナーで実行している場合は、まず、次を実行して、Azure サブスクリプションに接続します。
```
azure login
```
接続したら、次のコマンドを実行して、利用可能なすべての Azure AD アプリケーションを一覧表示します。
```
azure ad sp list --query "sort_by([*].{displayName: displayName, objectId: objectId}, &displayName)" -o table
```
このコマンドを実行すると、テナントで利用可能なすべての Azure AD アプリケーションが displayName の順に一覧表示されます。アプリケーションごとに、displayName と objectId がコマンドによって表示されます。加えて、その出力は表形式で表示されます。

アプリケーションによって公開されるアクセス許可のスコープのリストを取得する

各 Azure AD アプリケーションは、いくつかのアクセス許可のスコープを公開します。これらのアクセス許可のスコープは多くの場合、アプリケーション内の特定のリソースか操作と関連しています。接続したいアプリケーションで利用可能なアクセス許可のリストを取得するには、ドキュメンテーションを参照してください。 Microsoft Graph で利用可能なアクセス許可のスコープの一覧については、「Microsoft Graph のアクセス許可のリファレンス」を参照してください。

Azure AD アプリケーションへのアクセス許可を要求する

SharePoint Framework ソリューションが、Microsoft Graph やエンタープライズアプリケーションなど、Azure AD でセキュリティ保護された特定のリソースへのアクセス許可を必要とする場合、これらのリソースと、必要なアクセス許可をソリューションの構成で指定できます。

SharePoint Framework プロジェクトで、config/package-solution.json ファイルを開きます。
solution プロパティに、ソリューションに必要なすべてのリソースと対応するアクセス許可を一覧表示する webApiPermissionRequests プロパティを追加します。

次に、Microsoft Graph を使用してユーザーの予定表を読み取るためのアクセス許可を要求する SharePoint Framework ソリューションの例を示します。
```
{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}
```
注:

resource プロパティの値には、アクセス許可を要求するアプリケーションの displayName を指定する必要があります。リソースの指定に objectId を使用すると、アクセス許可の要求を承認しようとしたときにエラーが発生します。

特定のリソースへの複数のアクセス許可のスコープを要求したい場合、次の例のように別々のエントリで各スコープを指定します。

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "spfx-graph-client-side-solution",
    "id": "5d16587c-5e87-44d7-b658-1148988f212a",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "webApiPermissionRequests": [
      {
        "resource": "Microsoft Graph",
        "scope": "Calendars.Read"
      },
      {
        "resource": "Microsoft Graph",
        "scope": "User.ReadBasic.All"
      }
    ]
  },
  "paths": {
    "zippedPackage": "solution/spfx-graph.sppkg"
  }
}

このソリューションが SharePoint アプリカタログに展開されている場合、管理者は要求されたアクセス許可を確認し、それを付与または拒否するよう求められます。

注:

管理者が要求されたアクセス許可を拒否するか承認するかに関わりなく、ソリューションをサイトに展開して使用することができます。追加のアクセス許可を要求するソリューションを構築する場合、要求したアクセス許可は付与されていると想定するべきではありません。

アクセス許可要求を管理する

Azure AD アプリケーションにアクセス許可を要求する SharePoint Framework ソリューションを展開すると、管理者はソリューションで提供されているアクセス許可要求を管理するよう求められます。アクセス許可要求は、複数の方法で管理できます。

新しい SharePoint 管理センターのアクセス許可を管理する

新しい SharePoint 管理センターの API アクセスページを使用する方法については、「Azure AD でセキュリティ保護された API へのアクセスを管理する」を参照してください。

PowerShell でのアクセス許可の管理

全体管理者と SharePoint 管理者は、SharePoint Online 管理シェルを使用して SharePoint Online のアクセス許可とアクセス許可要求を管理することもできます。

すべての保留中のアクセス許可要求を表示するには、Get-SPOTenantServicePrincipalPermissionRequests コマンドレットを使用します。各アクセス許可要求に対して、コマンドレットは、ID (要求の承認または拒否に必要)、アクセス許可が要求されたリソース、および要求されたアクセス許可を一覧表示します。

注:

SharePoint は、要求されたアクセス許可がすでに付与されているかどうかを検証しないので、アクセス許可要求を承認または拒否する前に、テナントですでに付与されているアクセス許可を確認する必要があります。
特定のアクセス許可要求を承認するには、承認するアクセス許可要求の ID を指定して、Approve-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid> コマンドレットを使用します。

注:

既に付与されているアクセス許可の要求を承認しようとすると、エラーが表示されます。
アクセス許可要求を拒否するには (要求されたアクセス許可が既に付与されているか、要求が組織のポリシーに反している場合)、Deny-SPOTenantServicePrincipalPermissionRequest -RequestId <Guid> コマンドレットを使用して、拒否するアクセス許可要求の ID を指定します。

注:

SharePoint Framework アプリケーションが発行したアクセス許可要求を拒否しても、アプリケーションのアプリカタログへの展開と、サイトへのインストールは妨げられません。
テナントで付与されている権限を表示するには、Get-SPOTenantServicePrincipalPermissionGrants コマンドレットを使用します。許可ごとに、コマンドレットが次の情報を表示します。
- ClientId: (resourceId で示される) リソースにアクセスする際にユーザーに偽装する同意が与えられた、サービスプリンシパルの objectId です。
- ConsentType: 組織の管理者によって同意が与えられたか、または個人によって同意が与えられたか。可能な値は、"AllPrincipals" または "Principal" です。
- ObjectId: 付与済みのアクセス許可の一意識別子です。
- Resource: アクセスが許可されたリソースです。
- ResourceId: アクセスが許可されたリソースサービスプリンシパルの objectId です。
- Scope: リソースアプリケーションが予期すべき、OAuth 2.0 アクセストークン内のスコープ要求の値です。
以前に付与されたアクセス許可を取り消すには、Revoke-SPOTenantServicePrincipalPermission -ObjectId <String コマンドレットを>使用します。 ObjectId パラメーターで、取り消す許可の objectId を指定する必要があります。これは、Get-SPOTenantServicePrincipalPermissionGrants コマンドレットを使用して取得できます。

注:

アクセス許可を取り消しても、アプリカタログや展開されたアプリケーションには何の変更も加えられません。アクセス許可の取り消しによる唯一の影響は、テナントで使用されているすべてのアプリケーションが、アクセス許可が取り消されたリソースへの接続ができなくなるということです。

Microsoft 365 の CLI を使用してアクセス許可を管理する

全体管理者と SharePoint 管理者は、Microsoft 365 の CLI を使用して、SharePoint Online のアクセス許可とアクセス許可要求を管理できます。

注:

CLI for Microsoft 365 はオープンソースソリューションであり、アクティブなコミュニティでサポートが提供されています。 Microsoft からのオープンソースツールのサポート SLA はありません。

すべての保留中のアクセス許可要求を表示するには、spo serviceprincipal permissionrequest list コマンドを使用します。アクセス許可要求ごとに、コマンドは、ID (要求の承認または拒否に必要)、アクセス許可が要求されたリソース、および要求されたアクセス許可を一覧表示します。

注:

SharePoint は、要求されたアクセス許可がすでに付与されているかどうかを検証しないので、アクセス許可要求を承認または拒否する前に、テナントですでに付与されているアクセス許可を確認する必要があります。
特定のアクセス許可要求を承認するには、spo serviceprincipal permissionrequest approve コマンドを使用して、承認したいアクセス許可要求の ID を指定します。

注:

既に付与されているアクセス許可の要求を承認しようとすると、エラーが表示されます。
アクセス許可要求を拒否する (要求されたアクセス許可が既に付与されているか、要求が組織のポリシーに違反している場合) には、spo serviceprincipal permissionrequest deny コマンドを使用して、拒否したいアクセス許可要求の ID を指定します。

注:

SharePoint Framework アプリケーションが発行したアクセス許可要求を拒否しても、アプリケーションのアプリカタログへの展開と、サイトへのインストールは妨げられません。
テナントで付与されているアクセス許可を表示するには、spo serviceprincipal grant list コマンドを使用します。許可ごとに、コマンドが次の情報を表示します。
- ObjectId: 付与済みのアクセス許可の一意識別子です。
- Resource: アクセスが許可されたリソースです。
- ResourceId: アクセスが許可されたリソースサービスプリンシパルの objectId です。
- Scope: リソースアプリケーションが予期すべき、OAuth 2.0 アクセストークン内のスコープ要求の値です。
既に付与されたアクセス許可を取り消すには、spo serviceprincipal grant revoke コマンドを使用します。 grantId パラメーターで、取り消す許可の objectId を指定します。これは、spo serviceprincipal grant list コマンドを使用して取得できます。

注:

アクセス許可を取り消しても、アプリカタログや展開されたアプリケーションには何の変更も加えられません。アクセス許可の取り消しによる唯一の影響は、テナントで使用されているすべてのアプリケーションが、アクセス許可が取り消されたリソースへの接続ができなくなるということです。

AadHttpClient を使用する、Azure AD アプリケーションへの接続

v1.4.1で導入された SharePoint Framework は、Azure AD で保護された API への接続を簡素化します。新しい AadHttpClient を使用すれば、認証と承認を自分で実装しなくても、Azure AD でセキュリティ保護された API に簡単に接続できます。

内部的には、AadHttpClient は、SharePoint Online クライアント拡張サービスプリンシパルを使用して、Microsoft ID プラットフォーム認証ライブラリを利用して有効なアクセストークンを取得する Azure AD OAuth フローを実装します。 SharePoint Online クライアント機能拡張サービスプリンシパルは、Microsoft によってプロビジョニングされ、すべての Office 365 テナントの Azure AD で利用できます。

SharePoint Framework ソリューションで AadHttpClient を使用するには、メインの Web パーツファイルに次の import 句を追加します。
```
import { AadHttpClient, HttpClientResponse } from '@microsoft/sp-http';
```
接続したいリソースをパラメーターとして渡して、AadHttpClient の新しいインスタンスを取得します。
```
export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        // connect to the API
      });
  }

  // ...
}
```
注:

AadHttpClient の各インスタンスは特定のリソースにリンクされるので、接続したい各リソースに対してクライアントの新しいインスタンスを作成する必要があります。

リソースの AadHttpClient をインスタンス化したら、API と通信するための Web 要求を発行することができます。この例では、API がプロジェクトの他の場所で定義されたカスタム Order インターフェイスによって表現される順序の一覧を返します。

export default class HelloWorldWebPart extends BaseClientSideWebPart<IHelloWorldWebPartProps> {
  public render(): void {
    // ...

    this.context.aadHttpClientFactory
      .getClient('https://contoso.azurewebsites.net')
      .then((client: AadHttpClient): void => {
        client
          .get('https://contoso.azurewebsites.net/api/orders', AadHttpClient.configurations.v1)
          .then((response: HttpClientResponse): Promise<Order[]> => {
            return response.json();
          })
          .then((orders: Order[]): void => {
            // process data
          });
      });
  }

  // ...
}

考慮事項

Web API のアクセス許可を扱う際には、次の事柄を考慮する必要があります。

SharePoint Framework ソリューションを介してアクセス許可を要求する

現時点では、追加のアクセス許可を要求できるのは SharePoint Framework を介する場合のみです。アクセス許可要求を含むソリューションパッケージ (.sppkg) がアプリカタログに展開されると、要求が開始されます。要求が開始されると、全体管理者または SharePoint サービス管理者による承認または拒否が可能になります。

付与されたアクセス許可は、すべてのソリューションに適用される

Azre AD リソースへのアクセス許可は、1 つの SharePoint Framework ソリューションによって要求されますが、付与されると、テナント全体に適用されてそのテナントのすべてのソリューションで使用できるようになります。

ソリューションの削除はアクセス許可を取り消さない

最初に特定のアクセス許可を要求したソリューションを削除しても、付与されたアクセス許可は取り消されません。管理者は、SharePoint Framework アプリケーションの要求によって付与されたアクセス許可を、手動で取り消す必要があります。

以前に付与されたアクセス許可を取り消しても、発行されたアクセストークンは無効にならない

既に付与されたアクセス許可を取り消しても、ユーザーに発行されたアクセストークンは無効になりません。これらのアクセストークンは、期限が切れるまで有効に保たれます。

アクセス許可要求は、ソリューションの展開に影響しない

管理者が、ソリューションによって要求されたアクセス許可を拒否するか承認するかに関わりなく、ソリューションはサイトに展開して使用することができます。追加のアクセス許可を要求するソリューションを構築する場合、要求したアクセス許可は付与されていると想定するべきではありません。

SharePoint Online クライアントサービスプリンシパルのコントロール

Web API 要求によって付与されたすべてのアクセス許可は、SharePoint Online クライアント拡張機能の Azure AD アプリケーションに保存されます。管理者が、開発者に Web API 要求モデルと、MSGraphClient および AadHttpClient をソリューション内で使用させたくない場合、PowerShell で Disable-SPOTenantServicePrincipal コマンドレットを使用して、SharePoint Online クライアント拡張機能サービスプリンシパルを無効にできます。

サービスプリンシパルは、Enable-SPOTenantServicePrincipal コマンドレットを使用して再度有効にできます。代わりに、Microsoft 365 の CLI で spo serviceprincipal set コマンドを使用して、SharePoint Online クライアント拡張機能 サービスプリンシパルを有効または無効にすることもできます。

次の方法で共有

SharePoint Framework ソリューションでの Azure AD でセキュリティ保護された API への接続

Web API アクセス許可の概要