演習 - シングルサインオンを実装するWord用の Office アドインを作成する - Training

18 分

この演習では、Microsoft Graph を使用して現在ログインしているユーザーに関する詳細を挿入する Word アドインを作成します。このプロセスでは、シングルサインオン (SSO) 認証スキームを使用します。

前提条件

Microsoft Word 用の Office アドインを開発するには、Web クライアントまたは以下のデスクトップクライアントが必要です。

Windows v16.0.12215.20006 (またはそれ以降)
macOS v16.32.19102902 (またはそれ以降)

このモジュールでは、Node.js を使用して、カスタム Word アドインを作成します。このモジュールの演習では、開発者のワークステーションに、次のツールがインストールされていることを前提としています。

重要

ほとんどの場合、次のツールの最新バージョンをインストールすることをお勧めします。ここに記載されているバージョンのリストは、このモジュールが発行され、最後にテストしたときに使用されたものです。

Node.js (アクティブ LTS バージョン)
NPM (Node.jsと共にインストール)
Yeoman - v4.x (以上)
Microsoft Office 用 Yeoman ジェネレーター - v1.8.8
Visual Studio Code

重要

この演習は、Microsoft Office v1.8.8 用 Yeoman Generator で動作するように記述されています。 コマンド npm install generator-office@1.8.8 --global を使用して、特定のバージョンをインストールして、このバージョンを使用していることを確認します。ジェネレーターの以降のバージョンでは、このラボの手順に一致しない SSO プロジェクトスキャフォールディングが削除され、変更されました。

アドインプロジェクトの作成

次のコマンドを実行し、Yeoman ジェネレーターを使用してアドインプロジェクトを作成します。

yo office

注:

yo officeコマンドを実行すると、Yeoman のデータ収集ポリシーと Office アドイン CLI ツールに関するプロンプトが表示される場合があります。提供された情報を使用して、必要に応じてプロンプトに応答します。

プロンプトが表示されたら、以下の情報を入力してアドインプロジェクトを作成します。

プロジェクトの種類の選択 シングルサインオンをサポートする Office Add-in Task Pane プロジェクト
スクリプトの種類の選択 JavaScript
What would you want to name your add-in? (アドインの名前を何にしますか) MyWordSsoAddin
Which Office client application would you like to support?: (どの Office クライアントアプリケーションをサポートしますか) Word

Yeoman ジェネレーターのプロンプトと応答のスクリーンショット。

プロンプトを完了すると、ジェネレーターによってプロジェクトが作成され、サポートしているノードコンポーネントがインストールされます。

最初のプロジェクトを見つける

すべての Word アドインプロジェクトには、Microsoft Word のアドインを実装するさまざまなフォルダーやファイルが含まれています。アドインは、主に ./src/commands フォルダーと ./src/taskpane フォルダーに実装されています。これらの 2 つのフォルダー内のファイルは、基本的な作業ウィンドウのアドインと、アドインをトリガーするオプションのコマンドを実装しています。

ユーザー向けの SSO エクスペリエンスの実装をサポートする、プロジェクトに追加された他のファイルのいくつかを見てみましょう。これらのファイルは、./src/helpers フォルダーにあります。

documentHelper.js: このファイルは Office JavaScript API ライブラリを使用して、Microsoft Graph からデータを取得し、Word ドキュメントに追加します。
fallbackauthdialog.html: このファイルは、フォールバック認証戦略の JavaScript をロードする UI のないページです。
fallbackauthdialog.js: このファイルには、JavaScript 用の Microsoft 認証ライブラリ (MSAL.js) を使用してユーザーにサインインする認証戦略用の JavaScript が含まれています。
fallbackauthhelper.js: このファイルには、SSO 証がサポートされていないシナリオでフォールバック認証戦略を呼び出す作業ウィンドウの JavaScript が含まれています。
ssoauthhelper.js: このファイルには、SSO API を呼び出し、getAccessToken()、ブートストラップトークンを受信し、ブートストラップトークンを Microsoft Graph の呼び出しに使用できるアクセストークンと交換する JavaScript が含まれています。このファイルには、Microsoft Graph エンドポイントを呼び出すためのコードも含まれています。

重要

この演習のサンプルは、学習リソースとしてのみ使用することを目的としており、Microsoft Graph に要求を送信するために使用される OAuth トークンをクライアントに渡して直接呼び出しを行うため、運用環境のシナリオでは使用しないことを目的としています。

ベストセキュリティプラクティスとして、常にサーバー側のコードを使用して、Microsoft Graph 呼び出し、またはアクセストークンを渡す必要があるその他の呼び出しを行います。クライアントから Microsoft Graph への直接呼び出しを有効にするために、クライアントに OBO トークンを返しません。これにより、トークンが傍受またはリークされないように保護できます。適切なプロトコルフローの詳細については、 OAuth 2.0 プロトコルの図を参照してください。

Azure Active Directory (Azure AD) アプリを登録する。

前の単元で、ユーザーがサインインして Microsoft Graph を呼び出すためのアクセストークンを取得するには、Office アドインに Azure AD アプリケーションの登録が関連付けられている必要があることを学びました。

プロジェクトをテストする前に、Azure AD アプリケーションを登録してから、Azure AD アプリケーションを使用するようにプロジェクトを更新する必要があります。

ヒント

Azure AD アプリケーションを手動で登録する方法の詳細については、「シングルサインオンを使用する Node.js Office アドインを作成する: Azure AD v2.0 エンドポイントにアドインを登録する」を参照してください。

Office アドインプロジェクトには、Azure AD アプリの登録を作成してプロジェクトを更新できるユーティリティが含まれています。

コマンドプロンプトから、現在プロジェクトのルートフォルダーにいることを確認します。次のコマンドを実行します。

npm run configure-sso

このコマンドはブラウザーを起動し、Azure AD にサインインするように求めるプロンプトを表示します。 グローバル管理者の役割に割り当てられたユーザーなど、Azure AD アプリケーションを登録するためのアクセス許可を持つユーザーとしてサインインするようにしてください。

認証後、スクリプトは次のタスクを実行します。

Azure AD にアプリケーションを登録する
アプリケーションのアクセス許可と権限の設定を構成する
新しいクライアントシークレットを作成し、開発者ワークステーションのシークレットストアに保存する
Azure AD アプリケーションのクライアント ID でプロジェクトを更新する

configure-sso スクリプトの実行からの出力のスクリーンショット。

警告

Azure AD テナントが多要素認証 (MFA)/ 2 要素認証用に構成されている場合、configure-sso コマンドは失敗します。この場合、「シングルサインオンを使用する Node.js Office アドインを作成する: Azure AD v2.0 エンドポイントにアドインを登録する」の記事で概説されているように、Azure AD アプリの登録を手動で作成する必要があります。

configure-sso スクリプトが実行した作業を調べてみましょう。

ブラウザーを開き、Azure Active Directory 管理センター (https://aad.portal.azure.com) に移動します。テナントに対するグローバル管理者権限が付与されている職場または学校のアカウントを使用してサインインします。

左端のナビゲーションで、[Azure Active Directory] を選択します。

アプリの登録

左端のナビゲーションで、[管理]>[アプリの登録] を選択します。

Azure Active Directory 管理センターポータルでのアプリ登録のスクリーンショット。

[アプリの登録] ページで、[MyWordSsoAddin] を選択します。これは、以前にYeoman Generator for Microsoft Office で作成したアプリと同じ名前です。

MyWordSsoAddin ページで、アプリケーション ID をメモします。この Azure AD アプリケーションを作成した configure-sso スクリプトは、プロジェクトの .ENV ファイルに次の値を設定します。

CLIENT_ID=056b1e8c-747d-4b45-94b1-f61ac2c19a5e
GRAPH_URL_SEGMENT=/me
NODE_ENV=development
PORT=3000
QUERY_PARAM_SEGMENT=
SCOPE=User.Read

認証

左端のナビゲーションで、[管理]>[認証] を選択します。アプリのリダイレクト URI が taskpane.html ページと fallbackauthdialog.html ページに設定されていることに注意してください。

リダイレクト URI セクションのスクリーンショット。

また、「暗黙的な許可およびハイブリッドフロー」セクションが更新され、ユーザーがアプリに対して認証されたときに Azure AD がアクセストークンと ID トークンを返すようになっていることにも注意してください。

暗黙的な付与とハイブリッドフローの選択のスクリーンショット。

証明書とシークレット

左端のナビゲーションで、[管理]>[認証] を選択します。 [リダイレクト URI] が左端のナビゲーションで、[証明書&シークレットの管理>] を選択します。

configure-sso スクリプトは、アプリのクライアントシークレットを作成しました。これは、前に見たようにコマンドプロンプトに表示され、開発者ワークステーションのシークレットストアが追加されました。

API アクセス許可

左端のナビゲーションで、[管理]>[API 権限] を選択します。アプリに対して複数の委任された権限がどのように構成されているかに注目してください。また、console-sso スクリプトは、テナント内のすべてのユーザーに管理者の同意を付与したため、ユーザーがアプリを初めて使用するときにアプリに同意するように求められることはありません。

アプリで構成および付与された権限のスクリーンショット。

APIを公開する: アプリケーション ID URI

最後に、左端のナビゲーションで [管理]>[API の公開] を選択します。このページでは、注意すべき点が複数あります。

まず、アプリケーション ID の URI に注目してください。これは、アプリケーションの一意の ID です。完全な文字列でアプリケーションの ID を持っていることに注意してください。

API の公開: API によって定義されたスコープ

次のセクションには、API によって定義されたスコープが含まれています。これらは、API によって保護されているデータと機能へのアクセスを制限できるカスタムスコープにすることができます。この場合、configure-sso アプリでは、次のスコープが追加されました。

api://localhost:3000/056b1e8c-747d-4b45-94b1-f61ac2c19a5e/access_as_user

スコープの ID は、アプリケーションの ID と一致します。スコープの終わりに注意してください。このスコープでは、access_as_user を使用すると、Office クライアントアプリケーションは、現在サインインしているユーザーと同じ権限でアドインの Web API を使用できます。

API の公開：認証されたクライアントアプリケーション

最後のセクションは、API がこれらの特定のアプリケーションを自動的に信頼し、アプリケーションがこの API を呼び出すときにユーザーに同意を求めないことを示しています。

これにより、Office デスクトップおよび Web アプリケーションがアドインの API を呼び出すことが許可されます。

リストされているアプリケーションは次のとおりです。

Microsoft Office: d3590ed6-52b3-4102-aeff-aad2292ab01c
Microsoft Office: ea5a67f6-b6f3-4338-b240-c655ddc3cc8e
Office on the web: 57fb890c-0dab-4253-a5e0-7188c88b2bb4
Office on the web: 08e18876-6177-487e-b8b5-cf950c1e598c
Outlook on the web: bc59ab01-8403-45c6-8796-ac3ef710b3e3

これらのアプリの 1 つを選択した場合、それぞれのアプリには、以前に承認されたスコープとして定義されたスコープがあります。

アドイン API にアクセスできる ID と承認されたクライアントを示すスクリーンショット。

アプリケーションのビルドとテスト

コマンドプロンプトで次のコマンドを実行して、デバッグプロセスをトランスパイルして開始します。

npm start

開始スクリプトは 3 つのことを行います。

アドインプロジェクトのビルド
ローカル Web サーバーを起動して、ローカルワークステーションでアドインをホストする
Office クライアントを起動し、Office アドインをサイドロードする

ヒント

コマンドプロンプトを必ず監視してください。起動、サイドロード、およびデバッグのプロセスを完了するために、パスワードの入力を求められる場合があります。

Word デスクトップクライアントでアドインをテストします

しばらくすると、Word がリボンにあるアドインのボタンを読み込み、作業ウィンドウで読み込まれます。

Word のアドインのスクリーンショット。

アドインをテストするには、[ユーザープロファイル情報を取得する] ボタンを選択します。

Office クライアントでまだサインインしていない場合は、サインインするように求められます。

Word でのサインインのスクリーンショット。

ユーザーがサインインすると、アドインは Microsoft Graph から基本的なプロファイル情報を取得し、ドキュメントに追加します。

Word で成功したテストのスクリーンショット。

Word Web クライアントでアドインをテストします

SSO の動作を確認するには、OneDrive の Office Web クライアントでアドインを試してください。

ブラウザーを開いて OneDrive (https://onedrive.com) に移動します。 職場または学校アカウントを使用してサインインします。

[新規] ボタンを選択して新しい Word 文書を追加し、[Word 文書] を選択します。

Word アドインをサイドロードしてインストールします。リボンから、[挿入]>[アドイン] を選択します。

[Office アドイン] ダイアログで、[マイアドインのアップロード] を選択します。

プロジェクトのルートにある manifest.xml ファイルを選択し、[アップロード] を選択します。

Microsoft Word は、デスクトップクライアントと同じように、アドインをサイドロードし、リボンに [作業ウィンドウの表示] ボタンを表示します。

[作業ウィンドウの表示] ボタンを選択してから、[ユーザープロファイル情報を取得する] ボタンを選択します。

既にサインインしているため、しばらくすると、サインインしなくても同じプロファイル情報がドキュメントに表示されます。

プロジェクトを探究する

次に、Word アドインが SSO を使用して Microsoft Graph に接続し、現在サインインしているユーザーのプロファイル情報をドキュメントに表示する方法について説明します。

この演習の最初に作成したプロジェクトを Visual Studio Code で開きます。

./manifest.xml ファイルを検索して開きます。アドインマニフェスト内で、SourceLocation 要素を見つけます。

<OfficeApp>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:{PORT}/taskpane.html"/>
  </DefaultSettings>
</OfficeApp>

この要素の値は、ホスティング Office クライアントに作業ウィンドウ IFRAME にロードする URL を指示します。

./src/taskpane/taskpane.html ファイルを検索して開きます。このファイルで注意すべき点が 2 つあります。

ページの<head>セクション内で、office.js ファイルへの<script>参照に注目してください。これは、アドインがホスト Office クライアントとの通信に使用できる Office JavaScript SDK です。
ファイルの一番下までスクロールして <button id="getGraphDataButton"> ボタンを押します。これは、ユーザーが Microsoft Graph から現在サインインしているユーザーのプロファイル情報を要求するためのアクセストークンを取得するプロセスを開始するボタンです。

./src/taskpane/taskpane.js ファイルを検索して開きます。ホスティング Office クライアントがアドインをロードすると、作業ウィンドウのボタンのクリックイベントに ssoAuthHelper.getGraphData() メソッドがアタッチされます。

./src/helpers/ssoauthhelper.js ファイルを検索して開きます。このファイルには、SSO を使用してユーザーを認証し、Microsoft Graph からユーザーのプロファイルデータを取得するほとんどの作業を実行するコードが含まれています。これらはすべて getGraphData() メソッドで実装されます。このメソッドは次のことを行います。

Azure AD からアクセストークンを取得して、ユーザーにサインインします。このアクセストークンは bootstrapToken と呼ばれ、ID トークンとアクセストークンが含まれています。
アクセストークンを Azure AD と交換して、Microsoft Graph の呼び出しに使用できるトークンに交換します。

最初のステップで取得した bootstrapToken には、ユーザーの認証と ID トークンの取得に使用されるため、Microsoft Graph を呼び出すために必要なスコープが含まれていません。

注:

このステップで呼び出される sso.getGraphToken() メソッドは、https://graph.microsoft.com/v1.0/auth エンドポイントを呼び出して、Microsoft Graph に使用できるアクセストークンを取得します。
HTTP リクエストを Microsoft Graph の REST API に送信して、ユーザーのプロファイルデータを取得します。これは、sso.makeGraphApiCall() メソッドを呼び出すことによって行われます。

注:

sso.makeGraphApiCall() メソッドは https://graph.microsoft.com/v1.0/getuserdata エンドポイントを呼び出して、ユーザーのプロファイル情報を取得します。

認証プロセスが失敗した場合、コードは ./src/helpers/fallbackauth*.* ファイルを使用してフォールバック認証プロセスを使用します。

Microsoft Office 用 Yeoman ジェネレーターによって最初のアドインプロジェクトに追加されたコードは、Microsoft Graph からユーザーのプロファイル情報を取得します。このモジュールの他の演習では、Microsoft Graph に追加情報を要求する方法を示します。

自分の知識をテストする

シングルサインオンプロセスでは、Microsoft Graph の呼び出しに使用できる、現在サインインしているユーザーのアクセストークンを取得できます。

False

True

シングルサインオンプロセスで Office アドインを使用するには、ユーザーは個人用アカウントか、仕事用と学校用の Azure AD アカウントにサインインしている必要があります。

False

True

ユーザーがアドインから初めてサインインするときに、Office クライアントがユーザーに同意を求めるアクセス許可は何ですか?

Office がユーザーに対して同意を求めるのは、OpenID のアクセス許可 profile のみです。

Office では、Azure AD アプリの登録で規定されているアクセス許可に同意することを、ユーザーに求めることができます。

Office では、ユーザーに OpenID のいずれかのアクセス許可に同意するように求めることができますが、Microsoft Graph のアクセス許可への同意は求めません。

作業を確認する前にすべての問題に回答する必要があります。

続行

演習 - シングル サインオンを実装するWord用の Office アドインを作成する