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

入れ子になったアプリ認証で MSAL.js ライブラリ (バージョン 3.11 以降) を使用して、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 はサポートされていません。 次の表に、プレビューでの現在のサポートについて説明します。 「近日公開予定」と記載されているものは、NAA が一般公開されるまでにサポートされます。

* - Outlook でのイベント ベースのアクティブ化の NAA は、現在ベータ チャネルでサポートされています。

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

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」を参照してください。

   "dependencies": {
       "@azure/msal-browser": "^3.15.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"
        },
      });
    }
  });
  

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

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 認証パターンを使用する必要があります。 詳細については、次の資料を参照してください。

• Office ダイアログ API を使用して認証と承認を行います。
• SPA と JavaScript の Microsoft ID サンプル
• さまざまなアプリの種類とフレームワークの Microsoft ID サンプル

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

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

セキュリティ レポート

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

コード サンプル