Office ダイアログ API を使用して認証および承認する

常に Office ダイアログ API を使用して、Office アドインでユーザーを認証および承認します。 シングル サインオン (SSO) を使用できない場合にフォールバック認証を実装する場合は、Office ダイアログ API も使用する必要があります。

Office アドインは、Web 上の Office で開いたときに iframe で実行されます。 セキュリティで保護されたトークン サービス (STS) とも呼ばれる多くの ID 機関は、サインイン ページが iframe で開かないようにします。 これには、Microsoft アカウント、Microsoft 365 Education または職場アカウント、その他の一般的なアカウントなど、Microsoft ID プラットフォーム (旧称 Azure AD V 2.0) によって保護された Google、Facebook、およびサービスが含まれます。 また、Office アドインが Office on Windows または Office on Mac で実行されると、Web ビューに実装されるセキュリティ機能によって、サインイン ページが正しく動作しなくなる可能性があります。

承認が正しく機能するには、サインイン ページを別のブラウザーまたは Webview コントロール インスタンスで開く必要があります。 これが、Office が Office ダイアログ API、特に displayDialogAsync メソッドを提供する理由です。

この API で開かれたダイアログには、次の特性があります。

• モードレスです。
• これは作業ウィンドウとは完全に異なるブラウザー インスタンスで、次のことを意味します。
  • 独自のランタイム環境とウィンドウ オブジェクトとグローバル変数があります。
  • 作業ウィンドウと共有される実行環境はありません。
  • 作業ウィンドウと同じセッション ストレージ ( Window.sessionStorage プロパティ) は共有されません。
• ダイアログで開いた最初のページは、プロトコル、サブドメイン、ポート (存在する場合) など、作業ウィンドウと同じドメインでホストする必要があります。
• ダイアログは、 messageParent メソッドを使用して作業ウィンドウに情報を送信できます。 このメソッドは、作業ウィンドウと同じドメイン (プロトコル、サブドメイン、およびポートを含む) にホストされているページからのみ呼び出すことをお勧めします。 それ以外の方法を使用した場合、メソッドを呼び出してメッセージを処理する方法が複雑になります。 詳細については、「ホスト ランタイムへのクロスドメイン メッセージング」をご覧ください。

既定では、ダイアログは iframe ではなく新しい Web ビュー コントロールで開きます。 これにより、ID プロバイダーのサインイン ページを開くことができます。 この記事の後半で説明するように、Office ダイアログの特性は、Microsoft Authentication Library (MSAL) や Passport などの認証ライブラリまたは承認ライブラリの使用方法に影響します。

Office ダイアログを使用した認証フロー

標準的な認証フローを下に示します。

1. ダイアログで開く最初のページは、アドインのドメインでホストされているページ (またはその他のリソース) です。つまり、作業ウィンドウ ウィンドウと同じドメインです。 このページには、"お待ちください、 NAME-OF-PROVIDER にサインインできるページにリダイレクトされます" という UI のみを含めることができます。このページのコードは、「ダイアログに情報を渡す」で説明されているようにダイアログに渡されるか、web.config ファイルなどのアドインの構成ファイルにハードコーディングされた情報を使用 して 、ID プロバイダーのサインイン ページの URL を構築します。
2. 次に、ダイアログ ウィンドウはサインイン ページにリダイレクトします。 URL には、ユーザーがサインインしたらダイアログ ウィンドウを特定のページにリダイレクトするように ID プロバイダーに指示するクエリ パラメーターが含まれています。 この記事では、このページを redirectPage.html と呼びます。 このページでは、サインイン試行の結果を、messageParentの呼び出しで作業ウィンドウに渡すことができます。 これは、ホスト ウィンドウと同じドメイン内のページにすることをお勧めします。
3. ID プロバイダーのサービスは、ダイアログ ウィンドウから受信する GET 要求を処理します。 ユーザーが既にサインインしている場合は、ウィンドウが直ちに redirectPage.html にリダイレクトされ、クエリ パラメーターとしてユーザー データが含まれます。 ユーザーがまだサインインしていない場合は、プロバイダーのサインイン ページがウィンドウに表示されます。ユーザーはサインインします。 ほとんどのプロバイダーでは、ユーザーが正常にサインインできない場合、プロバイダーはダイアログ ウィンドウにエラー ページを表示し、 redirectPage.htmlにリダイレクトしません。 ユーザーは隅にある X を選択して、ウィンドウを閉じる必要があります。 ユーザーが正常にサインインした場合は、ダイアログ ウィンドウは redirectPage.html にリダイレクトされ、クエリ パラメーターとしてユーザー データが含まれます。
4. redirectPage.html ページが開くと、成功または失敗を作業ウィンドウ ページに報告するために messageParent が呼び出され、ユーザー データまたはエラー データも必要に応じて報告されます。 その他のメッセージには、アクセス トークンの受け渡しや、トークンがストレージにあるという作業ウィンドウへの伝達が含まれます。
5. DialogMessageReceived イベントが作業ウィンドウ ページで発生し、イベントのハンドラーによりダイアログ ウィンドウが閉じられ、メッセージはさらに処理される可能性があります。

複数の ID プロバイダーのサポート

アドインで Microsoft アカウント、Google、Facebook などのプロバイダーを選択できる場合は、ユーザーがプロバイダーを選択するための UI を提供するローカルの最初のページ (前のセクションを参照) が必要です。 選択すると、サインイン URL とその URL へのリダイレクトの構築がトリガーされます。

外部リソースへのアドインの承認

最新の Web において、ユーザーと Web アプリケーションはセキュリティ プリンシパルです。 アプリケーションには、Microsoft 365、Google+、Facebook、LinkedIn などのオンライン リソースに対する独自の ID とアクセス許可があります。 アプリケーションは、展開前にリソース プロバイダーに登録されます。 登録には以下が含まれています。

• アプリケーションが必要とするアクセス許可の一覧。
• アプリケーションがサービスにアクセスするときに、リソース サービスがアクセス トークンを返す宛先の URL。

リソース サービスのユーザーのデータにアクセスするアプリケーションでユーザーが関数を呼び出すと、ユーザーはサービスにサインインするように求められ、アプリケーションが必要とするユーザーのリソースへのアクセス許可をアプリケーションに付与するように求められます。 次に、サービスはサインイン ウィンドウを既に登録済みの URL にリダイレクトし、アクセス トークンを渡します。 アプリケーションはアクセス トークンを使用して、ユーザーのリソースにアクセスします。

このプロセスは Office ダイアログ API を使用して管理でき、これを行うにはユーザーのサインインについての説明でのフローと似たフローを使用します。 次の点のみが違います。

• ユーザーがアプリケーションに必要なアクセス許可を以前に付与していない場合は、サインイン後にダイアログでこれを行うよう求められます。
• ダイアログ ウィンドウのコードは、 messageParent を使用して文字列化されたアクセス トークンを送信するか、ホスト ウィンドウが取得できるアクセス トークンを格納することによって (また、 messageParent を使用して、トークンが使用可能であることをホスト ウィンドウに伝える) 方法で、アクセス トークンをホスト ウィンドウに送信します。 トークンには制限時間がありますが、制限時間内であれば追加のメッセージを表示することなく、ホスト ウィンドウはトークンを使用して、ユーザーのリソースに直接アクセスできます。

この目的のために Office ダイアログ API を使用するサンプル認証アドインが「サンプル」にいくつか記載されています。

ダイアログで認証ライブラリを使用する

Office ダイアログと作業ウィンドウは異なる ブラウザー ランタイム インスタンスで実行されるため、認証と承認が同じウィンドウで行われるときの認証/承認ライブラリの使用方法とは異なる方法で使用する必要があります。 次のセクションでは、これらのライブラリを使用できる方法と使用できない方法について説明します。

通常、ライブラリの内部キャッシュを使用してトークンを格納することはできません

通常、認証関連のライブラリでは、アクセス トークンを格納するためのメモリ内のキャッシュが提供されています。 その後に (Google、Microsoft Graph、Facebook などの) リソース プロバイダーに対する呼び出しが行われると、ライブラリは最初にライブラリのキャッシュ内のトークンの有効期限を確認します。 有効期限が切れていない場合、ライブラリは新しいトークンのために STS に新たにラウンドトリップを行うのではなく、キャッシュされたトークンを返します。 ただし、このパターンは Office アドインでは使用できません。サインイン プロセスは Office ダイアログのブラウザー インスタンスで行われるため、トークン キャッシュはそのインスタンスにあります。

これと密接に関連するのは、ライブラリは通常、トークンを取得するための方法として対話型のメソッドと "サイレント" メソッドの両方を提供しているということです。 リソースに対しての認証とデータの呼び出しの両方を同じブラウザー インスタンス内で行うことができる場合、コードは、トークンを取得するためにコードがトークンをデータの呼び出しに追加する直前にサイレント メソッドを呼び出します。 サイレント メソッドは期限が切れていないトークンがあるかどうかキャッシュを確認し、あった場合はトークンを返します。 それ以外の場合、サイレント メソッドは、STS のサインインにリダイレクトする対話型メソッドを呼び出します。 サインインが完了すると、対話型メソッドはトークンを返しますが、メモリにもキャッシュします。 ただし、Office ダイアログ API を使用している場合は、リソースへのデータ呼び出し (これは、サイレント メソッドを呼び出します) は、作業ウィンドウのブラウザー インスタンスにあります。 ライブラリのトークン キャッシュはそのインスタンスに存在しません。

別の方法として、アドインのダイアログ ブラウザー インスタンスは、ライブラリの対話型メソッドを直接呼び出すことができます。 そのメソッドがトークンを返す場合、コードは、 ローカル ストレージ やサーバー側データベースなど、作業ウィンドウのブラウザー インスタンスがトークンを取得できる場所にトークンを明示的に格納する必要があります。

別の方法としては、messageParent メソッドを使用してトークンを作業ウィンドウに渡す方法があります。 この方法は、対話型のメソッドが、アクセス トークンをコードが読み取ることができる場所に格納している場合にのみ可能です。 ライブラリの対話型メソッドは、コードがアクセスできないオブジェクトのプライベート プロパティにトークンを格納するように作られている場合があります。

通常、ライブラリの "認証コンテキスト" オブジェクトを使用することはできません

多くの場合、認証関連のライブラリには、トークンの対話的な取得と、メソッドが返す "認証コンテキスト" オブジェクトの作成の両方を行うメソッドがあります。 トークンはオブジェクトのプロパティです (プライベートで、コードから直接アクセスできない可能性があります)。 そのオブジェクトには、リソースからデータを取得するメソッドが備わっています。 これらのメソッドには、(Google、Microsoft Graph、Facebook などの) リソースプロバイダーに対して行う HTTP 要求内のトークンが含まれます。

これらの認証コンテキスト オブジェクトと、それらを作成するメソッドは、Office アドインでは使用できません。サインインは Office ダイアログのブラウザー インスタンスで行われるため、オブジェクトはそこで作成する必要があります。 ただし、リソースへのデータの呼び出しは作業ウィンドウのブラウザー インスタンスにあり、あるインスタンスから別のインスタンスにオブジェクトを移動する方法はありません。 たとえば、messageParent は文字列のみを渡すことができるため、messageParent を使用してオブジェクトを渡すことはできません。 メソッドを持つ JavaScript オブジェクトは、確実には文字化できません。

Office ダイアログ API でライブラリを使用する方法

ほとんどのライブラリでは、モノリシックの "認証コンテキスト" オブジェクトに加えてまたはその代わりとして、モノリシックの度合いがより低いヘルパー オブジェクトをコードが作成するできるようにする、抽象化レベルの低い API が提供されています。 たとえば、 MSAL.NET v. 3.x.x には、サインイン URL を構築する API と、コードからアクセスできるプロパティにアクセス トークンを含む AuthResult オブジェクトを構築する別の API があります。 Office アドインでの MSAL.NET の例については、「Office アドイン Microsoft Graph ASP.NET」および「Outlook アドイン Microsoft Graph ASP.NET」を参照してください。 アドインで msal.js を使用する例については、「Office アドイン Microsoft Graph React」を参照してください。

認証ライブラリおよび承認ライブラリの詳細については、「Microsoft Graph: 推奨されるライブラリ」および「その他の外部サービス: ライブラリ」を参照してください。

サンプル

• Office アドイン Microsoft Graph ASP.NET: MSAL.NET ライブラリと認証コード フローを使用してサインインし、Microsoft Graph データのアクセス トークンを取得する、ASP.NET ベースのアドイン (Excel、Word、または PowerPoint) です。
• Outlook アドイン Microsoft Graph ASP.NET: 上記のアドインと同様ですが、Office アプリケーションは Outlook です。
• Office アドイン Microsoft Graph React: サインインおよび Microsoft Graph データのアクセス トークンの取得に msal.js ライブラリと暗黙的フローを使用する、NodeJS ベースのアドイン (Excel、Word、PowerPoint) です。

関連項目

• Office アドインで外部サービスを承認する
• Office アドインで Office ダイアログ API を使用する