入れ子になったアプリ認証

[アーティクル]
09/23/2024

注:

入れ子になったアプリ認証 (NAA) は、パブリック開発者プレビューでのみ使用できます。
NAA は、タブなどのシングルページアプリケーション (SPA) でのみサポートされます。

NAA は、Teams、Outlook、Microsoft 365 などのホスト環境に埋め込まれている SPA の新しい認証プロトコルです。これにより、認証プロセスが簡素化され、サポートされているホストアプリ内に入れ子になったアプリ全体でシングルサインオン (SSO) が容易になります。 NAA モデルでは、入れ子になったアプリの複数のアプリ ID を含むホストアプリのプライマリ ID がサポートされています。 Microsoft では、Teams タブ、個人用アプリ、および Office アドインでこのモデルを利用しています。

NAA モデルは、On-Behalf-Of (OBO) フローよりもいくつかの利点を提供します。

NAA では、MSAL.js ライブラリのみを使用する必要があります。 Teams JavaScript クライアントライブラリ (TeamsJS) で getAuthToken 関数を使用する必要はありません。
クライアントコードからのアクセストークンを SPA として使用して、Microsoft Graph などのサービスを呼び出すことができます。中間層サーバーは必要ありません。
スコープ (アクセス許可) には、増分同意と動的同意を使用できます。
エンドポイントを呼び出すために、Teams や Microsoft 365 などのホストを事前認証する必要はありません。

次の表は、Teams Microsoft Entra SSO と NAA の違いの概要を示しています。

開発に必要な手順	従来の Teams Entra SSO	NAA
リダイレクト URI を公開する	必須	必須
Microsoft Entra IDで API を登録する	必須
Microsoft Entra IDでカスタムスコープを定義する	必須
Teams クライアントアプリを承認する	必須
アプリマニフェスト (以前は Teams アプリマニフェストと呼ばれる) を修正する	必須	推奨*
TeamsJS SDK を使用してアクセストークンを取得する	必須
より多くのアクセス許可を求めるユーザーの同意を求める	必須
サーバーで OBO 交換を行う	必須

IT 管理者は、アプリをブロックしたり、Microsoft Entra ID内のアプリに対する特定のアクセス許可のみに同意したりする場合があります。これを回避するには、管理者が Teams 管理センターでアクセス許可を承認するために、アプリ ID と既定のリソースをアプリマニフェストに含める必要があります。

NAA のユースケース

シナリオ	説明
SSO (およびその他のアクセス許可) への同意	Contoso デザインチームの新しいメンバーである Tom は、Teams 会議で Contoso アプリを使用してホワイトボードで共同作業する必要があります。最初に使用すると、アバターのプロファイルの読み取り (User.Read) を含むアクセス許可の付与をトムに求めるダイアログが表示されます。同意を与えた後、Tom はデバイス間の将来の会議で Contoso をシームレスに使用できます。
再認証または条件付きアクセスのステップアップ認証	Tom は、オーストラリアから作業するときに、Teams で Contoso にアクセスするために多要素認証 (MFA) を必要とする条件付きアクセストリガーを検出します。ダイアログは、より多くの検証が必要であることを Tom に通知し、MFA プロセスを通じて Contoso の使用を続行します。
エラー	アカウント情報の取得に問題があるため、Tom は Contoso でサインインエラーに直面します。 Tom は、再認証を求める再試行ボタンを検出します。ただし、システム管理者が Contoso へのアクセスを制限している点が分かっています。

NAA の構成

注:

NAA は開発者プレビュー段階にあり、すべてのホスト環境でサポートされていないため、isNAAChannelRecommended() 関数を使用してサポート状態をチェックし、サポートされていない環境にフォールバックエクスペリエンスを提供してください。
API が値を trueとして返す場合は、NAA フローに対して Microsoft Authentication Library (MSAL) を呼び出します。 falseが返される場合は、引き続き既存のトークン取得メソッドを使用します。

入れ子になった認証を構成するには、次の手順に従います。

SPA を登録する
信頼できるブローカーを追加する
パブリッククライアントアプリを初期化する
最初のトークンを取得する
API を呼び出す

SPA を登録する

Azure portalでアドインのMicrosoft Entra IDアプリ登録を作成する必要があります。アプリの登録には、名前、サポートされているアカウントの種類、SPA リダイレクトが必要です。アプリの登録後、Azure portalはMicrosoft Entraアプリ登録 ID を生成します。アドインで NAA と SSO 以外の追加のアプリ登録が必要な場合は、「シングルページアプリケーションを登録する」を参照してください。

信頼できるブローカーを追加する

入れ子になったアプリ認証を構成するには、アプリのリダイレクト URI をアクティブに構成する必要があります。リダイレクト URI は、サポートされているホストによってアプリを仲介できることをMicrosoft ID プラットフォームに示します。アプリのリダイレクト URI は 、単一ページアプリケーション の種類で、次のスキームに準拠している必要があります。

brk-multihub://<your_domain>

ここで

brk-multihub では、Teams、Outlook、Microsoft365.com など、実行するように構成されている Microsoft 365 でサポートされているホストによって認証を仲介できます。
<your_domain> は、アプリがホストされている完全修飾ドメイン名です。たとえば、 brk-multihub://contoso.com。

ドメインには、サブパスではなく、配信元のみを含める必要があります。以下に例を示します。

✔️ brk-multihub://myapp.teams.microsoft.com
❌ brk-multihub://myapp.teams.microsoft.com/go

Outlook と Microsoft365.com で実行するように Teams アプリをアップグレードする方法の詳細については、「 Microsoft 365 全体で Teams アプリを拡張する」を参照してください。

パブリッククライアントアプリを初期化する

注:

認証を確実に成功させるには、MSAL を初期化する前に TeamsJS を初期化します。

MSAL を初期化し、必要に応じ、パブリッククライアントアプリのインスタンスを取得してアクセストークンを取得します。

JavaScript

import {
  AccountInfo,
  IPublicClientApplication,
  createNestablePublicClientApplication,
} from "@azure/msal-browser";

const msalConfig = {
  auth: {
    clientId: "your_client_id",
    authority: "https://login.microsoftonline.com/{your_tenant_id}",
    supportsNestedAppAuth: true
  },
};

let pca: IPublicClientApplication;

export function initializePublicClient() {
  console.log("Starting initializePublicClient");
  return createNestablePublicClientApplication(msalConfig).then(
    (result) => {
      console.log("Client app created");
      pca = result;
      return pca;
    }
  );
}

最初のトークンを取得する

入れ子になったアプリ認証によって MSAL.js によって取得されたトークンは、Microsoft Entra アプリ登録 ID に対して発行されます。 MSAL.js は、ユーザー認証のトークン取得を処理します。アクセストークンをサイレントモードで取得しようとします。失敗した場合は、ユーザーに同意を求めるメッセージが表示されます。トークンは、Microsoft Graph APIまたはその他のMicrosoft Entra ID保護されたリソースを呼び出すために使用されます。 OBO フローとは異なり、エンドポイントを呼び出すためにホストを事前認証する必要はありません。

トークンを取得するには、次の手順に従います。

MSAL.js を使用して、アプリ ID のトークンを取得します。詳細については、「アクセストークンの取得と使用」を参照してください。
getActiveAccount API を使用して、publicClientApplicationを呼び出すアクティブなアカウントがあるかどうかを確認します。アクティブなアカウントがない場合は、コンテキストインターフェイスからtenantID、homeAccountId、loginHintなどの追加のフィルターパラメーターを使用して、getAccountを使用してキャッシュから 1 つを取得してみてください。

注:

homeAccountId プロパティは、TeamsJS のuserObjectIdと同じです。
publicClientApplication.acquireTokenSilent(accessTokenRequest)を呼び出して、ユーザー操作なしでトークンをサイレントモードで取得します。 accessTokenRequest は、アクセストークンが要求されるスコープを指定します。 NAA では、増分同意と動的同意がサポートされます。コードのタスクを完了するために必要な最小限のスコープを常に要求してください。
使用可能なアカウントがない場合、MSAL.js は InteractionRequiredAuthErrorを返します。 publicClientApplication.acquireTokenPopup(accessTokenRequest)を呼び出して、ユーザーの対話型ダイアログを表示します。 acquireTokenSilent トークンの有効期限が切れた場合、またはユーザーが要求されたすべてのスコープに同意しなかった場合、失敗する可能性があります。

次のコードスニペットは、トークンにアクセスする例を示しています。

JavaScript


  // MSAL.js exposes several account APIs, logic to determine which account to use is the responsibility of the developer
  const account = publicClientApplication.getActiveAccount();

  const accessTokenRequest = {
  scopes: ["user.read"],
  account: account,
  };

  publicClientApplication
    .acquireTokenSilent(accessTokenRequest)
    .then(function (accessTokenResponse) {
      // Acquire token silent success
      let accessToken = accessTokenResponse.accessToken;
      // Call your API with token
      callApi(accessToken);
    })
    .catch(function (error) {
      //Acquire token silent failure, and send an interactive request
      if (error instanceof InteractionRequiredAuthError) {
        publicClientApplication
          .acquireTokenPopup(accessTokenRequest)
          .then(function (accessTokenResponse) {
            // Acquire token interactive success
            let accessToken = accessTokenResponse.accessToken;
            // Call your API with token
            callApi(accessToken);
          })
          .catch(function (error) {
            // Acquire token interactive failure
            console.log(error);
          });
      }
      console.log(error);
    });

API を呼び出す

トークンを受け取ったら、それを使用して API を呼び出します。これにより、API が有効なトークンで呼び出され、サーバーに対して認証された要求が行われます。

次の例は、Microsoft Graph API に対して認証された要求を行って Microsoft 365 データにアクセスする方法を示しています。

JavaScript


var headers = new Headers();
var bearer = "Bearer " + access_token;
headers.append("Authorization", bearer);
var options = {
    method: "GET",
    headers: headers
};

var graphEndpoint = "<https://graph.microsoft.com/v1.0/me>";

fetch(graphEndpoint, options)
    .then(function (response) {
        //do something with response
    });

ベストプラクティス

可能な限りサイレント認証を使用する: MSAL.js は、ユーザーにプロンプトを表示せずにサイレントトークン要求を行うことでトークンの更新を処理する acquireTokenSilent メソッドを提供します。メソッドはまず、ブラウザーストレージで有効なキャッシュされたトークンを検索します。見つからない場合、ライブラリはMicrosoft Entra IDに対してサイレント要求を行い、アクティブなユーザーセッション (Microsoft Entra ドメイン上のブラウザーで設定された Cookie によって決定される) がある場合、Microsoft Entra IDは新しいトークンを返します。ライブラリは、 acquireTokenSilent メソッドを自動的に呼び出しません。有効なトークンを取得するために API 呼び出しを行う前に、アプリで acquireTokenSilent を呼び出することをお勧めします。

場合によっては、 acquireTokenSilent メソッドを使用してトークンを取得しようとすると失敗します。たとえば、Microsoft Entra IDのユーザーセッションが期限切れになった場合や、アプリユーザーによるパスワードの変更がある場合、acquireTokenSilentは失敗します。対話型の取得トークンメソッド (acquireTokenPopup) を呼び出します。
フォールバックがある: NAA フローは、Microsoft エコシステム全体の互換性を提供します。ただし、アプリは、NAA をサポートするように更新されていない下位レベルのクライアントまたはレガシクライアントに表示される場合があります。このような場合、アプリではシームレス SSO をサポートできないため、ユーザーと対話して認証ダイアログを開くために特別な API を呼び出す必要がある場合があります。詳細については、「タブアプリの SSO を有効にする」を参照してください。

注:

Microsoft Entra以外の ID プロバイダーを使用している場合は、NAA を使用しないでください。代わりにポップアップ認証を使用できます。
NAA のサポート: NAA はすべてのホストアプリ環境でサポートされない場合があります。現在のクライアントがこの機能をサポートしているかどうかを確認するには、指定した API を呼び出して状態を確認できます。戻り値 true は NAA のサポートを示しますが、 false はサポートされていないことを示します。
複数の環境でアプリをテストする: アプリが Web ビューとブラウザーの両方のデプロイで動作することが予想される場合は、両方のデプロイ環境でアプリをテストして、期待どおりに動作することを確認することをお勧めします。ブラウザーで機能する特定の API が Web ビュー内で動作しない場合があります。

コードサンプル

サンプルの名前	説明	.NET	Node.js
入れ子になったアプリ認証	このサンプルでは、Teams、Outlook、Microsoft 365 などのホスト環境に埋め込まれた SPA 用の NAA プロトコルを構築する方法を示します。	表示	表示

次の方法で共有

入れ子になったアプリ認証

NAA のユースケース

NAA の構成

SPA を登録する

信頼できるブローカーを追加する

パブリッククライアントアプリを初期化する

最初のトークンを取得する

API を呼び出す

ベストプラクティス

コードサンプル

関連項目

その他のリソース

次の方法で共有

入れ子になったアプリ認証

NAA のユース ケース

NAA の構成

SPA を登録する

信頼できるブローカーを追加する

パブリック クライアント アプリを初期化する

最初のトークンを取得する

API を呼び出す

ベスト プラクティス

コード サンプル

関連項目

その他のリソース

NAA のユースケース

パブリッククライアントアプリを初期化する

ベストプラクティス

コードサンプル