Microsoft Graph のアクセス許可とスコープを使用してタブアプリを拡張する

[アーティクル]
11/17/2023

Microsoft Graph を使用してタブアプリを拡張し、アプリユーザープロファイルの表示、メールの読み取りなど、追加のユーザーアクセス許可を許可できます。アプリユーザーの同意時にアクセストークンを取得するには、アプリで特定のアクセス許可スコープを要求する必要があります。

User.ReadやMail.Readなどのグラフスコープは、Teams ユーザーアカウントからアプリがアクセスできる内容を示します。承認要求でスコープを指定する必要があります。この記事では、Teams タブアプリの Microsoft Graph のアクセス許可とスコープを構成する手順について説明します。

Microsoft Entra ID で API アクセス許可を構成する

アプリの Microsoft Entra ID で追加の Graph スコープを構成できます。これらは委任されたアクセス許可であり、サインインアクセスを必要とするアプリによって使用されます。サインインしているアプリユーザーまたは管理者は、最初にそれらに同意する必要があります。その後、タブアプリは、Microsoft Graph を呼び出すときにサインインしているユーザーの代わりに同意できます。

サインインしているユーザーに委任されたアクセス許可を使用することをお勧めします。アプリケーションにサインインユーザーが必要ない場合は、アプリケーションのアクセス許可 (アプリ専用アクセスシナリオとも呼ばれます) の使用を検討してください。アプリケーションのアクセス許可に同意を付与できるのは管理者だけです。詳細については、「アプリケーションのアクセス許可」を参照してください。

API のアクセス許可を構成するには

Azure portal で登録したアプリを開きます。
左側のウィンドウから [ 管理>API アクセス許可 ] を選択します。

[API のアクセス許可] ページが表示されます。
[ + アクセス許可の追加] を 選択して、Microsoft Graph API のアクセス許可を追加します。

[要求 API のアクセス許可] ページが表示されます。
[Microsoft Graph] を選択します。

Graph アクセス許可のオプションが表示されます。
委任されたアクセス許可またはアプリケーションのアクセス許可の一覧をそれぞれ表示するには、[委任されたアクセス許可] または [アプリケーションのアクセス許可] を選択します。
アプリに関連するアクセス許可を選択し、[アクセス許可を追加する] を選択します。

検索ボックスにアクセス許可名を入力して検索することもできます。

アクセス許可が更新されたことを示すメッセージがブラウザーに表示されます。

追加されたアクセス許可は、[API アクセス許可] ページに表示されます。

これで、Microsoft Graph のアクセス許可を使用してアプリを構成しました。

さまざまなプラットフォーム向け認証を構成する

アプリを対象とするプラットフォームまたはデバイスによっては、リダイレクト URI、特定の認証設定、プラットフォーム固有の詳細など、追加の構成が必要になる場合があります。

注:

タブアプリに IT 管理者の同意が付与されていない場合、アプリユーザーは別のプラットフォームでアプリを初めて使用する際に同意する必要があります。
タブアプリでシングルサインオン (SSO) が有効になっている場合、暗黙的な許可は必要ありません。

URL が一意である限り、複数のプラットフォームの認証を構成することができます。

プラットフォームの認証を構成するには

Azure portal で登録したアプリを開きます。
左側のウィンドウで、[管理]>[認証] の順に選択します。

[プラットフォームの構成] ページが表示されます。
[プラットフォームの追加] を選択します。

[プラットフォームの構成] ページが表示されます。
タブアプリ用に構成するプラットフォームを選択します。プラットフォームの種類は 、Web または シングルページアプリケーションから選択できます。

特定のプラットフォームの種類に対して複数のプラットフォームを構成できます。リダイレクト URI が、構成するすべてのプラットフォームで一意であることを確認します。

構成 Web ページが表示されます。

注:

構成は、選択したプラットフォームによって異なります。
プラットフォームの構成の詳細を入力します。
1. リダイレクト URI を入力します。 URI は一意である必要があります。
2. フロントチャネルのログアウト URL を入力します。
3. Microsoft Entra ID でアプリに送信するトークンを選択します。
[構成] を選択します。

プラットフォームが構成され、[プラットフォームの構成] ページに表示されます。

MS Graph 向けアクセストークンの取得

Microsoft Graph のアクセストークンを取得する必要があります。これを行うには、Microsoft Entra on-behalf-of (OBO) フローを使用します。

シングルサインオン (SSO) の現在の実装はユーザーレベルのアクセス許可に制限されています。これは Graph 呼び出しには使用できません。 Graph 呼び出しを行うために必要なアクセス許可とスコープを取得するには、SSO アプリでカスタム Web サービスを実装して、Teams JavaScript ライブラリから受け取ったトークンを、必要なスコープを含むトークンと交換する必要があります。 Microsoft Authentication Library (MSAL) を使用して、クライアント側からトークンを取得できます。

Microsoft Entra ID で Graph のアクセス許可を構成したら、Teams クライアントからトークン ID を取得し、それをサーバー側のトークンと交換する必要があります。

Teams クライアントからトークン ID を取得する

Teams クライアントからトークン ID を取得する例を次に示します。

microsoftTeams.authentication.getAuthToken().then((result) => {
    //result contains the id token
            console.log(result);
        })

トークン ID をサーバー側トークンと交換する

MSAL を使用して Teams クライアントからアクセストークンをフェッチする OBO フローの例を次に示します。

C#
Node.js

IConfidentialClientApplication app = ConfidentialClientApplicationBuilder.Create(<"Client id">)
                                                .WithClientSecret(<"Client secret">)
                                                .WithAuthority($"https://login.microsoftonline.com/<"Tenant id">")
                                                .Build();
            try
            {
                var idToken = <"Client side token">;
                UserAssertion assert = new UserAssertion(idToken);
                List<string> scopes = new List<string>();
                scopes.Add("https://graph.microsoft.com/User.Read");
                // Acquires an access token for this application (usually a Web API) from the authority configured in the application.
                var responseToken = await app.AcquireTokenOnBehalfOf(scopes, assert).ExecuteAsync();
                return responseToken.AccessToken.ToString();
            }
            catch (Exception ex)
            {
                return ex.Message;
            }
        }

ConfidentiaClientApplication クラス SDK リファレンス | サンプルコード

// Exchange client Id side token with server token
  app.post('/getProfileOnBehalfOf', function(req, res) {
        var tid = < "Tenant id" >
    var token = < "Client side token" >
    var scopes = ["https://graph.microsoft.com/User.Read"];

        // Creating MSAL client
        const msalClient = new msal.ConfidentialClientApplication({
            auth: {
                clientId: < "Client ID" >,
                clientSecret: < "Client Secret" >
      }
        });

        var oboPromise = new Promise((resolve, reject) => {
            msalClient.acquireTokenOnBehalfOf({
                authority: `https://login.microsoftonline.com/${tid}`,
                oboAssertion: token,
                scopes: scopes,
                skipCache: true
            }).then(result => {
                console.log("Token is: " + result.accessToken);
            }).catch(error => {
                reject({ "error": error.errorCode });
            });
        });

Microsoft Graph データにアクセスする必要がある場合は、サーバー側のコードで次の操作を行う必要があります。

アクセストークンを検証する。詳細については、アクセストークンの検証に関するページを参照してください。
Microsoft ID プラットフォームを呼び出して、OAuth 2.0 OBO フローを開始します。これには、アクセストークン、ユーザーに関するメタデータ、およびタブアプリの資格情報 (ID とクライアントシークレット) を含めます。 Microsoft ID プラットフォームは、Microsoft Graph へのアクセスに使用できる新しいアクセストークンを返します。
新しいトークンを使用して Microsoft Graph からデータを取得します。
必要に応じて、MSAL.NET でトークンキャッシュのシリアル化を使用して、複数の新しいアクセストークンをキャッシュします。

重要

セキュリティのベストプラクティスとして、常にサーバー側のコードを使用して、アクセストークンを渡す必要がある Microsoft Graph 呼び出しまたはその他の呼び出しを行います。これにより、トークンが傍受またはリークされないように保護できます。クライアントが Microsoft Graph への直接呼び出しを行えるようにするため、OBO トークンをクライアントに返さないでください。
Microsoft Entra ID に登録されている 2 つのアプリには、アプリごとに個別のトークンが必要です。 OBO フローを使用して、アプリ間の通信を有効にします。
notifySuccess結果を使用してトークン情報を親ページに返さないでください。 localStorageを使用してトークンを保存し、notifySuccess経由でアイテムキーを渡します。

アプリは、テナント管理者からグローバルに、またはユーザーごとに個別に Graph アクセス許可に対する同意を取得できます。

テナント管理者から

組織の代わりに同意する簡単な方法は、管理者の同意を取得することです。

ユーザーから

Microsoft Teams JavaScript クライアントライブラリ (TeamsJS) 認証機能を使用して追加のユーザーの同意を求める場合は、次の考慮事項に注意してください。

個人用タブで SSO 認証を実装するには、次の手順に従います。

getAuthToken()を使用して取得したトークンは、Microsoft Entra OBO フローを使用してサーバー側で交換して、他の Graph API にアクセスする必要があります。この交換に Microsoft Entra v2 エンドポイントを使用していることを確認します。
ユーザーのトークン交換を初めて実行しようとすると、Microsoft Entra がトークンの交換を拒否した場合、ユーザーがユーザーのデータに対するアクセス許可をアプリに付与することに同意していない可能性があります。このような場合は、 invalid_grant または interaction_required のいずれかのエラーで交換が失敗します。 invalid_grantエラーの例としては、同意が必要な場合やauth_codeされたとき、アサーション、または更新トークンの有効期限が切れている場合、失効した場合、形式が正しくない場合、または存在しない場合などがあります。 interaction_requiredの例としては、多要素認証や企業デバイス登録が必要な場合などがあります。
invalid_grantまたはinteraction_requiredエラーが原因で交換が失敗した場合は、ユーザーに同意を求める必要があります。ユーザーの操作はクライアントからのみ行うことができるため、サーバーは同意が必要な兆候をクライアントアプリに返す必要があります。その後、ユーザーインターフェイス (UI) を使用して、アプリユーザーに他の同意を求めることができます。 UI には、 Microsoft Entra の同意ダイアログをトリガーするボタンが含まれている必要があります。
アプリがデータにアクセスするための同意をユーザーに求める場合は、クエリ文字列パラメーターに prompt=consent プロパティを Microsoft Entra ID に含める必要があります。
- ?scope={scopes} の代わりに、 ?prompt=consent&scope={scopes} を使用します。
- {scopes} プロパティに、ユーザーに求めるすべてのスコープが含まれていることを確認します。たとえば、Mail.Read および User.Read が禁止となります。
タブアプリの増分同意を処理するには、「増分と動的なユーザーの同意」を参照してください。
アプリユーザーにより多くのアクセス許可が付与されたら、OBO フローを再試行して、追加の Graph API にアクセスします。詳細については、「 Teams 個人用タブ SSO 認証のサンプルコード」を参照してください。

無効な許可例外の後に OBO 呼び出しを行うときの競合状態

ユーザーがこれらのスコープに対して Microsoft Entra アプリケーションの同意を付与していない場合、OBO 呼び出しは invalid_grant または interaction_required エラーで失敗します。このエラーは、ユーザーに同意を求める必要があることを通知します。

ユーザーが同意を提供し、すぐに OBO 呼び出しを行おうとすると、Microsoft Entra ID がこの同意を伝達し、OBO 要求が行われる間に競合状態が発生することがあります。これにより、OBO 呼び出しが同じ invalid_grant または interaction_required エラーで失敗する可能性があります。

アプリケーションがこの動作に気付かない場合は、ユーザーに複数回同意を求める場合があります。ベストプラクティスは、この最適でないユーザーエクスペリエンスを回避するために、意味のある待機と再試行のメカニズムを構築する方法です。

ユーザーが必要なスコープに同意した場合、待機と再試行のメカニズムは追跡する必要があります。 OBO 要求を含む API 呼び出しが上記のエラーで失敗したが、ユーザーが既に同意している場合は、同意プロンプトをユーザーに表示しないようにします。代わりに、API 呼び出しを再試行する前にしばらく待ちます。通常、Microsoft Entra ID は 3 ~ 5 秒以内に同意を送信します。サンプルアプリケーションの 1 つでは、1 秒の待機から開始して、各再試行の間の待機時間を 2 倍にして最大 3 回再試行します。

3 ~ 5 回試行しても OBO フローが失敗した場合、ユーザーが必要なすべてのスコープに同意していない可能性があり、もう一度同意するように求める必要がある場合があります。

この方法は、ユーザーが複数回同意を求められる可能性を減らすのに役立ちます。

コードサンプル

サンプルの名前	説明	C#	Node.js
タブ Microsoft Entra SSO	Microsoft Teamsタブ用のサンプルアプリ Microsoft Entra SSO。OBO フローを使用して Graph API を呼び出します。	表示	表示

次の方法で共有

Microsoft Graph のアクセス許可とスコープを使用してタブアプリを拡張する

Microsoft Entra ID で API アクセス許可を構成する

API のアクセス許可を構成するには

さまざまなプラットフォーム向け認証を構成する

プラットフォームの認証を構成するには

MS Graph 向けアクセストークンの取得

Teams クライアントからトークン ID を取得する

トークン ID をサーバー側トークンと交換する

テナント管理者から

ユーザーから

無効な許可例外の後に OBO 呼び出しを行うときの競合状態

コードサンプル

関連項目

その他のリソース

次の方法で共有

Microsoft Graph のアクセス許可とスコープを使用してタブ アプリを拡張する

Microsoft Entra ID で API アクセス許可を構成する

API のアクセス許可を構成するには

さまざまなプラットフォーム向け認証を構成する

プラットフォームの認証を構成するには

MS Graph 向けアクセス トークンの取得

Teams クライアントからトークン ID を取得する

トークン ID をサーバー側トークンと交換する

同意を得る

テナント管理者から

ユーザーから

無効な許可例外の後に OBO 呼び出しを行うときの競合状態

コード サンプル

関連項目

その他のリソース

Microsoft Graph のアクセス許可とスコープを使用してタブアプリを拡張する

MS Graph 向けアクセストークンの取得

コードサンプル