Microsoft Graph Toolkit プロバイダー

  • [アーティクル]

Microsoft Graph Toolkit プロバイダーを使用すると、アプリケーションは Microsoft Identity で認証を行い、わずか数行のコードで Microsoft Graph にアクセスできます。 各プロバイダーは、このコードを自分で記述する必要がないように、ユーザー認証を処理し、Microsoft Graph API を呼び出すためにアクセス トークンを取得します。

コンポーネントなしでプロバイダーを独自に使用して、アプリの認証をすばやく実装し、JavaScript クライアント SDK を使用して Microsoft Graph を呼び出すことができます。

プロバイダーは、Microsoft Graph Toolkit コンポーネントを使用するコンポーネントが Microsoft Graph にアクセスするために使用する場合に必要です。 既に独自の認証があり、コンポーネントを使用する場合は、代わりに カスタム プロバイダー を使用できます。

ツールキットには、次のプロバイダーが含まれています。

プロバイダー 説明
Custom アプリケーションの既存の認証コードを使用して、Microsoft Graph への認証とアクセスを有効にするカスタム プロバイダーを作成します。
電子 電子アプリ内のコンポーネントへの Microsoft Graph アクセスを認証して提供します。
MSAL2 MSAL ブラウザーを使用してユーザーにサインインし、Microsoft Graph で使用するトークンを取得します。
プロキシ バックエンドを介して Microsoft Graph へのすべての呼び出しをルーティングすることで、バックエンド認証を使用できるようにします。
SharePoint SharePoint Web パーツ内のコンポーネントへの Microsoft Graph アクセスを認証して提供します。
TeamsFx Microsoft Teams アプリケーション内の TeamsFx プロバイダーを使用して、Microsoft Graph ツールキット コンポーネントに Microsoft Graph へのアクセスを提供します。

プロバイダーの初期化

アプリでプロバイダーを使用するには、新しいプロバイダーを初期化し、プロバイダー名前空間でグローバル プロバイダーとして設定する必要があります。 コンポーネントの使用を開始する前に、これを行うことをお勧めします。 これを行うには、次の 2 つの方法のいずれかを実行します。

オプション 1: プロバイダー コンポーネントを使用する

プロバイダーのコンポーネント バージョンは、HTML で直接使用できます。 バックグラウンドでは、新しいプロバイダーが初期化され、グローバル プロバイダーとして設定されます。 次の例は、MSAL2 プロバイダーを使用する方法を示しています。

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>

オプション 2: コードで初期化する

JavaScript コードでプロバイダーを初期化すると、より多くのオプションを提供できます。 これを行うには、新しいプロバイダー インスタンスを作成し、プロパティの値を Providers.globalProvider 使用するプロバイダーに設定します。 次の例は、MSAL2 プロバイダーを使用する方法を示しています。

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: "YOUR_CLIENT_ID",
});

メモ：アプリを登録してクライアント ID を取得する方法の詳細については、「Microsoft Entra アプリを作成する」を参照してください。

アクセス許可スコープ

プロバイダーを初期化するときに、アプリケーションで必要なすべてのアクセス許可スコープを scopes 属性またはプロパティに追加することをお勧めします (これは SharePoint プロバイダーには適用されません)。 これは省略可能ですが、コンポーネントごとに個別の画面を表示するのではなく、アプリ内のすべてのコンポーネントによって要求されたアクセス許可の集計リストを持つ 1 つの同意画面をユーザーに提示することで、ユーザー エクスペリエンスが向上します。 次の例は、MSAL2 プロバイダーでこれを行う方法を示しています。

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider
  client-id="YOUR_CLIENT_ID"
  scopes="user.read,people.read"
></mgt-msal2-provider>

コードでプロバイダーを初期化する場合は、 プロパティの配列にアクセス許可スコープを scopes 指定します。

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID'
  scopes:['user.read','people.read']
});

各コンポーネントに必要なアクセス許可スコープの一覧は、各コンポーネントのドキュメント ページの Microsoft Graph のアクセス許可 セクションにあります。

カスタム ホスト

Microsoft Graph クライアントのカスタム ホストを指定できます。 これにより、Microsoft Graph 以外のMicrosoft Entra IDセキュリティで保護された API を呼び出すことができます。 カスタム ホストを指定するときは、アクセス トークンのスコープを要求してください。

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider 
  client-id="YOUR_CLIENT_ID"
  custom-hosts="myapi.com,anotherapi.com"
></mgt-msal2-provider>

コードでプロバイダーを初期化する場合は、 プロパティの配列にホスト名を customHosts 指定します。

import { Providers } from "@microsoft/mgt-element";
import { Msal2Provider } from "@microsoft/mgt-msal2-provider";
Providers.globalProvider = new Msal2Provider({
  clientId: 'YOUR_CLIENT_ID',
  customHosts: ['myapi.com','anotherapi.com']
});

注: これらはホスト名であり、URI ではありません。

カスタム API を呼び出すには、その API スコープを要求します。

<mgt-get resource="https://myapi.com/v1.0/api" scopes="api://CUSTOM_API_GUID/SCOPE">
  ...
</mgt-get>

または、Javascript/Typescript を使用します。

import { prepScopes } from "@microsoft/mgt-element";

graphClient
  .api("https://myapi.com/v1.0/api")
  .middlewareOptions(prepScopes("api://CUSTOM_API_GUID/SCOPE"))
  .get();
...

プロバイダーの状態

プロバイダーは、ユーザーの認証状態を追跡し、コンポーネントに通信します。 たとえば、ユーザーが正常にサインインすると、 ProviderState が に SignedIn更新され、コンポーネントに通知され、Microsoft Graph を呼び出すことができるようになります。 列挙型は ProviderState 、次に示すように、3 つの状態を定義します。

export enum ProviderState {
  Loading,
  SignedOut,
  SignedIn,
}

一部のシナリオでは、ユーザーが正常にサインインした後にのみ、特定の機能を表示するか、アクションを実行する必要があります。 次の例に示すように、プロバイダーの状態にアクセスしてチェックできます。

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  //your code here
}

メソッドを使用して、プロバイダーの Providers.onProviderUpdated 状態が変更されるたびに通知を受け取ることもできます。

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

const providerStateChanged = () => {
  if (Providers.globalProvider.state === ProviderState.SignedIn) {
    // user is now signed in
  }
};

// register a callback for when the state changes
Providers.onProviderUpdated(providerStateChanged);

// remove callback if necessary
Providers.removeProviderUpdatedListener(providerStateChanged);

アクセス トークンの取得

各プロバイダーは、現在のアクセス トークンを取得したり、指定されたスコープの新しいアクセス トークンを取得したりできる という関数 getAccessToken を公開します。 次の例は、アクセス許可スコープを使用して新しいアクセス トークンを取得する方法を User.Read 示しています。

import { Providers, ProviderState } from "@microsoft/mgt-element";

//assuming a provider has already been initialized

if (Providers.globalProvider.state === ProviderState.SignedIn) {
  const token = await Providers.globalProvider.getAccessToken({
    scopes: ["User.Read"],
  });
}

Microsoft Graph を独自に呼び出す

(前のセクションで説明したように) プロバイダーを初期化する限り、すべてのコンポーネントは、カスタマイズを必要とせずに Microsoft Graph にアクセスできます。 Microsoft Graph を独自に呼び出す場合は、コンポーネントで使用されているのと同じ Microsoft Graph SDK への参照を取得します。 まず、グローバル IProvider への参照を取得し、次に示すように オブジェクトを graph 使用します。

import { Providers } from "@microsoft/mgt-element";

let provider = Providers.globalProvider;
if (provider) {
  let graphClient = provider.graph.client;
  let userDetails = await graphClient.api("me").get();
}

呼び出している API によっては、追加のアクセス許可を渡す必要がある場合があります。 次の例は、その方法を示しています。

import { prepScopes } from "@microsoft/mgt-element";

graphClient
  .api("me")
  .middlewareOptions(prepScopes("user.read", "calendar.read"))
  .get();

複数のプロバイダーを使用する

一部のシナリオでは、アプリケーションは異なる環境で実行され、それぞれに異なるプロバイダーが必要になります。 たとえば、アプリは Web アプリケーションと Microsoft Teams タブの両方として実行される場合があります。つまり、MSAL2 プロバイダーと Teams MSAL2 プロバイダーの両方を使用する必要がある場合があります。 このシナリオでは、次の depends-on 例に示すように、すべてのプロバイダー コンポーネントにフォールバック チェーンを作成するための属性があります。

<mgt-teams-msal2-provider
  client-id="[CLIENT-ID]"
  auth-popup-url="auth.html"
></mgt-teams-msal2-provider>

<mgt-msal2-provider
  client-id="[CLIENT-ID]"
  depends-on="mgt-teams-provider"
></mgt-msal2-provider>

このシナリオでは、アプリが Web アプリケーションとして実行されていて、Teams MSAL2 プロバイダーが現在の環境で使用できない場合にのみ、MSAL2 プロバイダーが使用されます。

コードで同じ操作を行うには、次に示すように、プロバイダーで プロパティを使用 isAvailable できます。

if (TeamsProvider.isAvailable) {
  Providers.globalProvider = new TeamsProvider(teamsConfig);
} else {
  Providers.globalProvider = new Msal2Provider(msalConfig);
}

ユーザー ログイン/ログアウト

アプリケーションに適したプロバイダーを初期化したら、Toolkit の Login コンポーネント を追加して、ユーザー ログインとログアウトを簡単かつ迅速に実装できます。 コンポーネントはプロバイダーと連携して、すべての認証ロジックとログイン/ログアウト機能を処理します。 次の例では、MSAL2 プロバイダーと Login コンポーネントを使用します。

<script type="module">
  import { registerMgtComponents, registerMgtMsal2Provider } from "https://unpkg.com/@microsoft/mgt@4";
  registerMgtMsal2Provider();
  registerMgtComponents();
</script>
<mgt-msal2-provider client-id="YOUR_CLIENT_ID"></mgt-msal2-provider>
<mgt-login></mgt-login>

Toolkit の Login コンポーネントを使用するのではなく、これを自分で実装するシナリオでは、プロバイダーの メソッドと logout メソッドを使用loginして実装できます。

独自のプロバイダーを実装する

既存の認証コードを使用して Toolkit コンポーネントをアプリケーションに追加するシナリオでは、定義済みのプロバイダーを使用するのではなく、認証メカニズムにフックするカスタム プロバイダーを作成できます。 ツールキットには、新しいプロバイダーを作成する 2 つの方法があります。

  • 関数を渡すことによって、認証コードからアクセス トークンを返す新しい SimpleProvider を作成します。
  • 抽象クラスを拡張します IProvider 。

各プロバイダーの詳細については、「 カスタム プロバイダー」を参照してください。