入れ子になったアプリ認証を使用して Office アドインで SSO を有効にする

入れ子になったアプリ認証で MSAL.js ライブラリを使用して、Office アドインの SSO を使用できます。 入れ子になったアプリ認証を使用すると、On-Behalf-Of (OBO) フローよりもいくつかの利点があります。

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

NAA でサポートされているアカウントとホスト

NAA では、Microsoft アカウントとMicrosoft Entra ID (職場/学校) の両方の ID がサポートされています。 企業間 ID 管理シナリオでは、Azure Active Directory B2C はサポートされていません。 次の表では、プラットフォームごとの現在のサポートについて説明します。 一般公開 (GA) として一覧表示されているプラットフォームは、アドインで運用環境で使用する準備ができています。

アプリケーション	Web	Windows	Mac	iOS/iPad	Android
Excel	プレビュー	プレビュー	プレビュー	iPad のプレビュー中	該当なし
Outlook	GA	現在のチャネルの GA、他のすべてのチャネルでのプレビュー	GA	GA (iOS)	GA
PowerPoint	プレビュー	プレビュー	プレビュー	iPad のプレビュー中	該当なし
Word	プレビュー	プレビュー	プレビュー	iPad のプレビュー中	該当なし

重要

プレビュー段階のプラットフォームで NAA を使用するには、Microsoft 365 Insider Program (https://insider.microsoft365.com/join) に参加し、[ 現在のチャネル (プレビュー)] を選択します。 プレビュー プラットフォームの運用環境アドインでは NAA を使用しないでください。 テスト環境または開発環境で NAA を試し、GitHub を通じてエクスペリエンスに関するフィードバックを歓迎することをお勧めします (このページの最後にある フィードバック セクションを参照してください)。

シングルページ アプリケーションを登録する

Azure portalでアドインの Microsoft Azure アプリ登録を作成する必要があります。 アプリの登録には、少なくとも次のものが必要です。

• 名前
• サポートされているアカウントの種類
• SPA リダイレクト

アドインで NAA と SSO 以外の追加のアプリ登録が必要な場合は、「 シングルページ アプリケーション: アプリの登録」を参照してください。

SPA リダイレクトを使用して信頼できるブローカーを追加する

NAA を有効にするには、アプリの登録に特定のリダイレクト URI を含め、アドインでサポートされているホストによるブローカーが許可されていることをMicrosoft ID プラットフォームに示す必要があります。 アプリケーションのリダイレクト URI は 、単一ページ アプリケーション の種類で、次のスキームに準拠している必要があります。

brk-multihub://your-add-in-domain

たとえば、localhost サーバー上のポート 3000 でアドインをテストする場合は、リダイレクト値として brk-multihub://localhost:3000 を使用します。

信頼されたブローカー グループは設計上動的であり、今後更新して、アドインが NAA フローを使用する可能性がある追加のホストを含めることができます。 現在、brk-multihub グループには、Office Word、Excel、PowerPoint、Outlook、Teams が含まれています (Office が内部でアクティブ化されている場合)。

NAA を使用するように MSAL 構成を構成する

MSAL で createNestablePublicClientApplication 関数を呼び出して、NAA を使用するようにアドインを構成します。 MSAL は、ネイティブ アプリケーション ホスト (Outlook など) に入れ子にして、アプリケーションのトークンを取得できるパブリック クライアント アプリケーションを返します。

次の手順では、yo office (Office アドイン作業ウィンドウ プロジェクト) でビルドされたプロジェクトで、taskpane.jsまたはtaskpane.ts ファイルで NAA を有効にする方法を示します。

1. @azure/msal-browser パッケージをプロジェクトのpackage.json ファイルのdependencies セクションに追加します。 このパッケージの詳細については、「 Microsoft Authentication Library for JavaScript (MSAL.js) for Browser-Based Single-Page Applications」を参照してください。 最新バージョンのパッケージを使用することをお勧めします (前回の記事の更新時点では 3.26.0 でした)。

   "dependencies": {
       "@azure/msal-browser": "^3.26.0",
       ...
   

2. npm installを保存して実行して、@azure/msal-browserをインストールします。

3. taskpane.js または taskpane.ts ファイルの先頭に次のコードを追加します。 これにより、MSAL ブラウザー ライブラリがインポートされます。

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

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

次に、MSAL を初期化し、 パブリック クライアント アプリケーションのインスタンスを取得する必要があります。 これは、必要に応じアクセス トークンを取得するために使用されます。 パブリック クライアント アプリケーションを作成するコードを Office.onReady メソッドに配置することをお勧めします。

• Office.onReady関数で、次に示すように createNestablePublicClientApplication への呼び出しを追加します。 Enter_the_Application_Id_Here プレースホルダーを、前に保存した Azure アプリ ID に置き換えます。

  let pca = undefined;
  Office.onReady(async (info) => {
    if (info.host) {
      document.getElementById("sideload-msg").style.display = "none";
      document.getElementById("app-body").style.display = "flex";
      document.getElementById("run").onclick = run;
  
      // Initialize the public client application
      pca = await createNestablePublicClientApplication({
        auth: {
          clientId: "Enter_the_Application_Id_Here",
          authority: "https://login.microsoftonline.com/common"
        },
      });
    }
  });
  

注:

前のコード サンプルでは、職場と学校のアカウントまたは個人の Microsoft アカウントをサポートする共通の権限を設定します。 1 つのテナントまたはその他のアカウントの種類を構成する場合は、「追加の権限 オプションのアプリケーション構成オプション 」を参照してください。

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

NAA 経由で MSAL.js によって取得されたトークンは、Azure アプリ登録 ID に対して発行されます。 このコード サンプルでは、Microsoft Graph APIのトークンを取得します。 ユーザーがMicrosoft Entra IDでアクティブなセッションを持っている場合、トークンはサイレントで取得されます。 そうでない場合、ライブラリは対話形式でサインインするようにユーザーに求めます。 その後、トークンを使用して Microsoft Graph APIを呼び出します。

次の手順は、トークンの取得に使用するパターンを示しています。

1. スコープを指定します。 NAA では増分同意と動的同意がサポートされているため、コードがタスクを完了するために必要な最小限のスコープを常に要求します。
2. acquireTokenSilent を呼び出します。 これにより、ユーザーの操作を必要とせずにトークンが取得されます。
3. acquireTokenSilent失敗した場合は、acquireTokenPopupを呼び出して、ユーザーの対話型ダイアログを表示します。 acquireTokenSilent トークンの有効期限が切れている場合、またはユーザーが要求されたすべてのスコープにまだ同意していない場合は失敗する可能性があります。

次のコードは、この認証パターンを独自のプロジェクトに実装する方法を示しています。

1. taskpane.jsまたはtaskpane.tsのrun関数を次のコードに置き換えます。 このコードでは、ユーザーのファイルを読み取るために必要な最小スコープを指定します。

   async function run() {
   // Specify minimum scopes needed for the access token.
   const tokenRequest = {
     scopes: ["Files.Read", "User.Read", "openid", "profile"],
   };
   let accessToken = null;
   
   // TODO 1: Call acquireTokenSilent.
   
   // TODO 2: Call acquireTokenPopup.
   
   // TODO 3: Log error if token still null.
   
   // TODO 4: Call the Microsoft Graph API.
   
   }
   

2. TODO 1 を次のコードに置き換えます。 このコードは acquireTokenSilent を呼び出してアクセス トークンを取得します。

   try {
     console.log("Trying to acquire token silently...");
     const userAccount = await pca.acquireTokenSilent(tokenRequest);
     console.log("Acquired token silently.");
     accessToken = userAccount.accessToken;
   } catch (error) {
     console.log(`Unable to acquire token silently: ${error}`);
   }
   

3. TODO 2 を次のコードに置き換えます。 このコードは、アクセス トークンが取得されているかどうかを確認します。 そうでない場合は、 acquireTokenPopupを呼び出してアクセス トークンを対話形式で取得しようとします。

   if (accessToken === null) {
     // Acquire token silent failure. Send an interactive request via popup.
     try {
       console.log("Trying to acquire token interactively...");
       const userAccount = await pca.acquireTokenPopup(tokenRequest);
       console.log("Acquired token interactively.");
       accessToken = userAccount.accessToken;
     } catch (popupError) {
       // Acquire token interactive failure.
       console.log(`Unable to acquire token interactively: ${popupError}`);
     }
   }
   

4. TODO 3 を次のコードに置き換えます。 サイレント サインインと対話型サインインの両方が失敗した場合は、エラーをログに記録して返します。

   // Log error if both silent and popup requests failed.
   if (accessToken === null) {
     console.error(`Unable to acquire access token.`);
     return;
   }
   

API を呼び出す

トークンを取得した後、それを使用して API を呼び出します。 次の例では、Authorization ヘッダーにトークンがアタッチされた fetch を呼び出して、Microsoft Graph APIを呼び出す方法を示します。

• TODO 4 を次のコードに置き換えます。

  // Call the Microsoft Graph API with the access token.
  const response = await fetch(
    `https://graph.microsoft.com/v1.0/me/drive/root/children?$select=name&$top=10`,
    {
      headers: { Authorization: accessToken },
    }
  );
  
  if (response.ok) {
    // Write file names to the console.
    const data = await response.json();
    const names = data.value.map((item) => item.name);
  
    // Be sure the taskpane.html has an element with Id = item-subject.
    const label = document.getElementById("item-subject");
  
    // Write file names to task pane and the console.
    const nameText = names.join(", ");
    if (label) label.textContent = nameText;
    console.log(nameText);
  } else {
    const errorText = await response.text();
    console.error("Microsoft Graph call failed - error text: " + errorText);
  }
  

前のすべてのコードが run 関数に追加されたら、作業ウィンドウのボタンが run 関数を呼び出していることを確認します。 その後、アドインをサイドロードし、コードを試すことができます。

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

入れ子になったアプリ認証を使用すると、サポートされている Microsoft アプリケーション内に入れ子になっているアプリケーションの SSO が有効になります。 たとえば、Excel on Windows では、Web ビュー内でアドインが実行されます。 このシナリオでは、アドインは Excel 内で実行されている入れ子になったアプリケーションであり、これがホストです。 NAA では、Teams の入れ子になったアプリもサポートされています。 たとえば、Teams タブが Excel をホストしていて、アドインが読み込まれている場合、アドインは Excel 内に入れ子になり、Teams 内にも入れ子になります。 ここでも、NAA はこの入れ子になったシナリオをサポートしており、SSO にアクセスして、サインインしているユーザーのユーザー ID とアクセス トークンを取得できます。

ベスト プラクティス

NAA で MSAL.js を使用する場合は、次のベスト プラクティスをお勧めします。

可能な限りサイレント認証を使用する

MSAL.js は、ユーザーにプロンプトを表示せずにサイレント トークン要求を行うことでトークンの更新を処理する acquireTokenSilent メソッドを提供します。 メソッドは、最初に有効なキャッシュされたトークンを検索します。 見つからない場合、ライブラリはサイレント要求をMicrosoft Entra IDし、アクティブなユーザー セッションがある場合は、新しいトークンが返されます。

場合によっては、 acquireTokenSilent メソッドによるトークンの取得が失敗します。 たとえば、Microsoft Entra IDを使用したユーザー セッションが期限切れになっている場合や、ユーザーによるパスワードの変更があり、ユーザーの操作が必要な場合です。 acquireTokenSilent が失敗した場合は、対話型の acquireTokenPopup トークン メソッドを呼び出す必要があります。

NAA がサポートされていない場合にフォールバックを行う

Microsoft エコシステム全体でこれらのフローとの高度な互換性を提供するよう努めていますが、アドインは NAA をサポートしていない古い Office ホストに読み込まれる場合があります。 このような場合、アドインはシームレス SSO をサポートしていないため、ユーザーを認証する別の方法にフォールバックする必要がある場合があります。 一般に、 OFFICE JS ダイアログ API で MSAL SPA 認証パターンを使用する必要があります。

アドインの読み込み時に NAA がサポートされているかどうかをチェックするには、次のコードを使用します。

   Office.context.requirements.isSetSupported("NestedAppAuth", "1.1");

詳細については、次の資料を参照してください。

• Outlook サンプル: フォールバックしてインターネット エクスプローラー 11 をサポートする方法
• Office ダイアログ API を使用して認証と承認を行います。
• SPA と JavaScript の Microsoft ID サンプル
• さまざまなアプリの種類とフレームワークの Microsoft ID サンプル

NAA でサポートされている MSAL.js API

次の表は、MSAL 構成で NAA が有効になっている場合にサポートされる API を示しています。

メソッド	NAA でサポートされる
acquireTokenByCode	いいえ (例外をスローします)
acquireTokenPopup	はい
acquireTokenRedirect	いいえ (例外をスローします)
acquireTokenSilent	はい
addEventCallback	はい
addPerformanceCallback	いいえ (例外をスローします)
disableAccountStorageEvents	いいえ (例外をスローします)
enableAccountStorageEvents	いいえ (例外をスローします)
getAccountByHomeId	はい
getAccountByLocalId	はい
getAccountByUsername	はい
getActiveAccount	はい
getAllAccounts	はい
getConfiguration	はい
getLogger	はい
getTokenCache	いいえ (例外をスローします)
handleRedirectPromise	いいえ
initialize	はい
initializeWrapperLibrary	はい
loginPopup	はい
loginRedirect	いいえ (例外をスローします)
logout	いいえ (例外をスローします)
logoutPopup	いいえ (例外をスローします)
logoutRedirect	いいえ (例外をスローします)
removeEventCallback	はい
removePerformanceCallback	いいえ (例外をスローします)
setActiveAccount	いいえ
setLogger	はい
ssoSilent	はい

セキュリティ レポート

ライブラリまたはサービスに関するセキュリティの問題が見つかる場合は、問題を報告して、提供できる限り詳細に secure@microsoft.com してください。 提出物は、Microsoft 報奨金プログラムを通じて 報奨金 の対象となる場合があります。 GitHub やその他のパブリック サイトにセキュリティの問題を投稿しないでください。 問題レポートを受け取った直後に、お客様に連絡します。 セキュリティ アドバイザリ アラートをサブスクライブするには、 Microsoft のテクニカル セキュリティ通知 にアクセスして、新しいセキュリティ インシデント通知を受け取ることをお勧めします。

コード サンプル

サンプルの名前	説明
入れ子になったアプリ認証を使用した SSO を使用した Office アドイン	Office アドイン MSAL.js 入れ子になったアプリ認証 (NAA) を使用して、サインインしているユーザーの Microsoft Graph API にアクセスする方法を示します。 このサンプルでは、サインインしているユーザーの名前と電子メールが表示されます。 また、ユーザーの Microsoft OneDrive アカウントのファイルの名前もドキュメントに挿入されます。
入れ子になったアプリ認証を使用した SSO を使用した Outlook アドイン	Outlook アドイン MSAL.js 入れ子になったアプリ認証 (NAA) を使用して、サインインしているユーザーの Microsoft Graph API にアクセスする方法について説明します。 このサンプルでは、サインインしているユーザーの名前と電子メールが表示されます。 また、ユーザーの Microsoft OneDrive アカウントのファイルの名前を新しいメッセージ本文に挿入します。

関連項目

• NAA FAQ