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

  • 18 分

この演習では、Microsoft Graph を使用して現在ログインしているユーザーが最近受信したメール リストをワークシートに追加する Excel アドインを作成します。 このプロセスでは、シングル サインオン (SSO) 認証スキームを使用します。

前提条件

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

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

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

重要

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

これらの前提条件の最小バージョンがワークステーションにインストールされている必要があります。

重要

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

重要

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

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

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

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

yo office

注:

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

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

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

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

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

Microsoft Entra アプリを登録する

次に、Microsoft Entra アプリケーションを登録し、Microsoft Entra アプリケーションを使用するようにプロジェクトを更新します。

ヒント

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

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

npm run configure-sso

コマンドを実行すると、ブラウザーが起動し、Microsoft Entra ID にサインインするように求められます。 グローバル管理者ロールに割り当てられたユーザーなど、Microsoft Entra アプリケーションを登録するアクセス許可を持つユーザーとしてサインインしていることを確認します。

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

  1. Microsoft Entra アプリケーションを登録する
  2. アプリケーションのアクセス許可と権限の設定を構成する
  3. 新しいクライアント シークレットを作成し、開発者ワーク ステーションのシークレット ストアに保存する
  4. Microsoft Entra アプリケーションのクライアント ID を使用してプロジェクトを更新する

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

警告

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

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

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

npm start

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

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

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

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

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

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

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

最近のメールを表示するようにアプリを更新する

それでは、作業ウィンドウ アプリを更新して、現在 Microsoft Graph でログインしているユーザーが最近受信したメールのリストを追加しましょう。

Microsoft Entra アプリのアクセス許可を更新する

登録済みのMicrosoft Entra アプリには、まずアプリへのアクセス許可を付与する必要があります。

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

左端のナビゲーションで、[管理]>[API 権限] を選択します。

[権限の追加] を選択して、新しい権限を追加します。

[APIの選択] 画面で、[Microsoft Graph] を選択し、[委任されたアクセス許可] を選択します。 アクセス許可 [Mail.Read] を検索して選択し、[アクセス許可の追加] を選択します。

Mail.Read アクセス許可を追加する方法を示すスクリーンショット。

次に、[Contoso に対して管理者の同意を与える]を選択し、[はい] を選択して確認プロンプトを受け入れます。

Excel 作業ウィンドウ アドインを更新する

次の手順として、アドインのコードを更新します。

作業ウィンドウを更新する

./src/taskpane/taskpane.html を検索して開きます。

作業ウィンドウで次の HTML 要素を見つけます。

<div class="ms-firstrun-instructionstep__welcome-body">

HTML の最初の箇条書きを見つけて、span 要素の内容を次のように変更します。

<span class="ms-ListItem-primaryText">Click the <b>Get my last 10 emails</b> button.</span>

HTML の最後の箇条書きを見つけて、span 要素の内容を次のように変更します。

<span class="ms-ListItem-primaryText">Your last 10 emails will be displayed in the document.</span>

ボタンを見つけて、テキストを Get last 10 emails に変更します。

作業ウィンドウのコードを更新する

次に、ユーザーの最後の 10 通のメールを取得するコードを更新します。

./src/helpers/ssoauthhelper.js ファイルを検索して開きます。

getGraphData() メソッドで次の行を見つけます。

const response = await sso.makeGraphApiCall(exchangeResponse.access_token);

この行を削除して、次のコードに置き換えます。 このコードは、SSO ヘルパーの別の方法を使用して、特定の要求を Microsoft Graph に送信します。

const endpoint = "/me/messages";
const urlParams = "?$select=receivedDateTime,subject,isRead&$orderby=receivedDateTime&$top=10";
const response = await sso.getGraphData(exchangeResponse.access_token, endpoint, urlParams);

次に、/src/helpers/documentHelper.js ファイルを検索して開きます。

メソッド writeDataToExcel() を検索します。 このメソッドのほとんどのコードを置き換えますが、基本的な構造を維持する必要があります。 メソッドの内容を削除し、以下のコードに置き換えます。

return Excel.run(function(context) {
  const sheet = context.workbook.worksheets.getActiveWorksheet();

  // TODO

  return context.sync();
});

まず、// TODO を以下のコードに置き換えて、シートにいくつかの列見出しを作成します。

const rangeHeading = sheet.getRange("A1:D1");
rangeHeading.values = [["Received Date/Time", "Subject", "Read?", "ID"]];

次に、追加した前のコードの後に次のコードを追加します。 これにより、Microsoft Graph リクエストの結果が取得され、それらが多次元配列に変換されてワークシートに書き込まれます。

次に、結果をワークシートに書き込み、すべてのデータが表示されるように列をフォーマットします。

// convert data to a list
const mailResults = result.value;
for (let i = 0; i < mailResults.length; i++) {
  if (mailResults[i] !== null) {
    let innerArray = [];
    innerArray.push(mailResults[i].receivedDateTime);
    innerArray.push(mailResults[i].subject);
    innerArray.push(mailResults[i].isRead);
    innerArray.push(mailResults[i].id);

    let data = [];
    data.push(innerArray);
    let rangeData = sheet.getRange(`A${i+2}:D${i+2}`);
    rangeData.values = data;
  }
}

rangeHeading.format.autofitColumns();

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

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

npm start

Excel でアドインをテストする

しばらくすると、Excel がリボンにあるアドインのボタンを読み込み、作業ウィンドウで読み込まれます。 これを Excel Web クライアントでテストしてみましょう。

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

[新規] ボタンを選択して新しい Excel ブックを追加し、[Excel ブック] を選択します。

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

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

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

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

[作業ウィンドウの表示] ボタンを選択してから、[最後の10 通のメールを取得] ボタンを選択します。

すでにサインインしているため、しばらくすると、サインインしなくても最近のメールがワーク シートに表示されます。

Excel での最終的なアドインのスクリーンショット。

自分の知識をテストする

1.

getAccessToken() メソッドにおける forMSGraphAccess 認可オプションの目的は何ですか?

2.

Office アドインの manifest.xml ファイルの <WebApplicationInfo> 要素には、どのような詳細情報が表示されますか?

3.

getAccessToken() メソッドにおける allowSignInPrompt 認可オプションの目的は何ですか?