Yeoman ジェネレーターを使用して、シングル サインオンを使用する Office アドインを作成する (プレビュー)Use the Yeoman generator to create an Office Add-in that uses single sign-on (preview)

この記事では、可能な場合シングル サインオン (SSO) を使用し、SSO がサポートされていない場合は別のユーザー認証方法を使用する Excel、Outlook、Word、または PowerPoint 用の Office アドインを作成するプロセスを説明します。In this article, you'll walk through the process of using the Yeoman generator to create an Office Add-in for Excel, Outlook, Word, or PowerPoint that uses single sign-on (SSO) when possible, and uses an alternate method of user authentication when SSO is not supported.

ヒント

このクイック スタートを完了する前に、「Office アドインのシングル サインオンを有効化する」を参照して、Office アドインの SSO に関する基本的な概念を確認してください。Before you attempt to complete this quick start, review Enable single sign-on for Office Add-ins to learn basic concepts about SSO in Office Add-ins.

Yeoman ジェネレーターは、Azure 内で SSO を構成するために必要な手順を自動化し、SSO を使用するために必要なコードを生成することで、SSO アドインの作成プロセスを簡素化します。The Yeoman generator simplifies the process of creating an SSO add-in, by automating the steps required to configure SSO within Azure and generating the code that's necessary for an add-in to use SSO. Yeoman ジェネレーターが自動化する手順を手動で完了する方法についての詳細は、「シングル サインオンを使用する Node.js Office アドインを作成する」チュートリアルを参照してください。For a detailed walkthrough that describes how to manually complete the steps that the Yeoman generator automates, see the Create a Node.js Office Add-in that uses single sign-on tutorial.

前提条件Prerequisites

  • Node.js (最新 LTS バージョン)。Node.js (the latest LTS version).

  • 最新バージョンの YeomanOffice アドイン用の Yeoman ジェネレーター。これらのツールをグローバルにインストールするには、コマンド プロンプトから次のコマンドを実行します。The latest version of Yeoman and the Yeoman generator for Office Add-ins. To install these tools globally, run the following command via the command prompt:

    npm install -g yo generator-office
    

    注意

    以前に一度使用したバージョンのジェネレーターをインストールしていた場合でも、パッケージを npm から最新バージョンに更新することをお勧めします。Even if you've previously installed the Yeoman generator, we recommend you update your package to the latest version from npm.

  • Office 365 (Office のサブスクリプション バージョン) アカウント。An Office 365 (the subscription version of Office) account. Office 365 アカウントをまだお持ちでない場合は、Office 365 開発者プログラムに参加することで 90 日間の更新可能な無料の Office 365 サブスクリプションを入手できます。If you don't already have an Office 365 account, you can get a free, 90-day renewable Office 365 subscription by joining the Office 365 Developer Program.

  • Insider の Office 365 のビルド。An Insider's build of Office 365. 最新の月次バージョンを使用し、Insider チャネルからビルドする必要がありますが、このバージョンを入手するには Office Insider である必要があります。You should use the latest monthly version and build from the Insiders channel but you need to be an Office Insider to get this version.

    注意

    ビルドが半期チャネルの運用に移行すると、そのビルドで SSO を含むプレビュー機能のサポートは無効になります。When a build graduates to the production semi-annual channel, support for preview features, including SSO, is disabled for that build.

  • Mac を使用していて Azure CLI がコンピューターにインストールされていない場合は、Homebrew をインストールする必要があります。If you're using a Mac and don't have the Azure CLI installed on your machine, you must install Homebrew. このクイック スタート中に実行する SSO 構成スクリプトは、Homebrew を使用して Azure CLI をインストールした後、Azure CLI を使用して Azure の SSO を構成します。The SSO configuration script that you'll run during this quick start will use Homebrew to install the Azure CLI, and will then use the Azure CLI to configure SSO within Azure.

アドイン プロジェクトの作成Create the add-in project

ヒント

Yeoman ジェネレーターは、Excel、Outlook、Word、または PowerPoint 用の SSO が有効な Office アドインを作成でき、JavaScript または TypeScript のスクリプト タイプで作成できます。The Yeoman generator can create an SSO-enabled Office Add-in for Excel, Outlook, Word, or PowerPoint, and can be created with script type of JavaScript or TypeScript. 次の手順では、JavaScriptExcel を指定しますが、使用しているシナリオに最適なスクリプト タイプと Office クライアント アプリケーションを選択する必要があります。The following instructions specify JavaScript and Excel, but you should choose the script type and Office client application that best suits your scenario.

次のコマンドを実行して、[ごみ箱] ジェネレーターを使用してアドインプロジェクトを作成します。Run the following command to create an add-in project using the Yeoman generator:

yo office

注意

yo officeコマンドを実行すると、Office アドインのデータ収集ポリシーに関するダイアログボックスが表示されることがあります。When you run the yo office command, you may receive prompts about the data collection policies of Yeoman and the Office Add-in CLI tools. 提供されている情報を使用して、表示に適したプロンプトに応答します。Use the information that's provided to respond to the prompts as you see fit.

メッセージが表示されたら、アドインプロジェクトを作成するための次の情報を入力します。When prompted, provide the following information to create your add-in project:

  • Choose a project type: (プロジェクトの種類を選択) Office Add-in Task Pane project supporting single sign-onChoose a project type: Office Add-in Task Pane project supporting single sign-on
  • Choose a script type: (スクリプトの種類を選択) JavascriptChoose a script type: Javascript
  • What would you want to name your add-in?: (アドインの名前を何にしますか)What do you want to name your add-in? My SSO Office Add-in
  • Which Office client application would you like to support?: (どの Office クライアント アプリケーションをサポートしますか)Which Office client application would you like to support? Excel

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

ウィザードを完了すると、ジェネレーターによってプロジェクトが作成されて、サポートしているノード コンポーネントがインストールされます。After you complete the wizard, the generator creates the project and installs supporting Node components.

ヒント

アドインプロジェクトを作成した後で、次の手順に従って、その後に実行することができます。You can ignore the next steps guidance that the Yeoman generator provides after the add-in project's been created. この記事で説明する手順では、このチュートリアルを完了するために必要なすべてのガイダンスについて説明します。The step-by-step instructions within this article provide all of the guidance you'll need to complete this tutorial.

プロジェクトを確認するExplore the project

Yeoman ジェネレーターで作成したアドイン プロジェクトには、SSO が有効な作業ウィンドウ アドインのコードが含まれています。The add-in project that you've created with the Yeoman generator contains code for an SSO-enabled task pane add-in.

構成Configuration

次のファイルは、アドインの構成設定を指定します。The following files specify configuration settings for the add-in.

  • プロジェクトのルートディレクトリにある ./ manifest.xmlファイルは、アドインの設定と機能性を定義します。The ./manifest.xml file in the root directory of the project defines the settings and capabilities of the add-in.

  • ./.ENVプロジェクトのルートディレクトリにあるファイルには、アドインプロジェクトで使用される定数が定義されています。The ./.ENV file in the root directory of the project defines constants that are used by the add-in project.

作業ウィンドウTask pane

次のファイルは、アドインの作業ウィンドウの UI と機能を定義します。The following files define the add-in's task pane UI and functionality.

  • ./src/taskpane/taskpane.htmlファイルには、作業ペイン用のHTMLマークアップが含まれています。The ./src/taskpane/taskpane.html file contains the HTML markup for the task pane.

  • ./src/taskpane/taskpane.cssファイルには、作業ウィンドウ内のコンテンツに適用される CSS が含まれています。The ./src/taskpane/taskpane.css file contains the CSS that's applied to content in the task pane.

  • JavaScript プロジェクトでは、 /src/taskpane/taskpane.jsファイルにアドインを初期化するコードが含まれています。In a JavaScript project, the ./src/taskpane/taskpane.js file contains code to initialize the add-in. TypeScript プロジェクトでは、/src/taskpane/taskpane.ts ファイルにアドインを初期化するコードと、Office JavaScript ライブラリを使用して Microsoft Graph から Office ドキュメントにデータを追加するコードも記述されていますIn a TypeScript project, the ./src/taskpane/taskpane.ts file contains code to initialize the add-in and also code that uses the Office JavaScript library to add the data from Microsoft Graph to the Office document.

認証Authentication

次のファイルにより、SSO プロセスが容易になり、Office ドキュメントにデータが書き込まれます。The following files facilitate the SSO process and write data to the Office document.

  • JavaScript プロジェクトの/Src/helpers/documentHelper.js ファイルには、Office JavaScript ライブラリを使用して Microsoft Graph のデータを Office ドキュメントに追加するコードが含まれていますIn a JavaScript project, the ./src/helpers/documentHelper.js file contains code that uses the Office JavaScript library to add the data from Microsoft Graph to the Office document. このようなファイルは TypeScript プロジェクトには含まれていません。Office JavaScript ライブラリを使用して Microsoft Graph から Office ドキュメントにデータを追加するコードは、代わりに /src/taskpane/taskpane.tsにあります。There is no such file in a TypeScript project; the code that uses the Office JavaScript library to add the data from Microsoft Graph to the Office document exists in ./src/taskpane/taskpane.ts instead.

  • ./Src/helpers/fallbackauthdialog.htmlファイルは、フォールバック認証戦略の JavaScript を読み込む UI レスページです。The ./src/helpers/fallbackauthdialog.html file is the UI-less page that loads the JavaScript for the fallback authentication strategy.

  • ./Src/helpers/fallbackauthdialog.jsファイルには、msal .js を使用してユーザーにサインするフォールバック認証戦略の JavaScript が含まれています。The ./src/helpers/fallbackauthdialog.js file contains the JavaScript for the fallback authentication strategy that signs in the user with msal.js.

  • /Src/helpers/fallbackauthhelper.jsファイルには、SSO 認証がサポートされていないシナリオでフォールバック認証戦略を呼び出す作業ウィンドウ JavaScript が含まれています。The ./src/helpers/fallbackauthhelper.js file contains the task pane JavaScript that invokes the fallback authentication strategy in scenarios when SSO authentication is not supported.

  • ./src/helpers/ssoauthhelper.js ファイルには、SSO API getAccessToken へのJavaScript 呼び出しが含まれ、ブートストラップ トークンの受信し、Microsoft Graph へのアクセス トークンのブートストラップ トークン交換の開始、データのための Microsoft Graph への呼び出しを行います。The ./src/helpers/ssoauthhelper.js file contains the JavaScript call to the SSO API, getAccessToken, receives the bootstrap token, initiates the swap of the bootstrap token for an access token to Microsoft Graph, and calls to Microsoft Graph for the data.

SSO を構成するConfigure SSO

この時点では、アドイン プロジェクトが作成され、SSO プロセスを容易するために必要なコードが含まれています。At this point, your add-in project has been created and contains the code that's necessary to facilitate the SSO process. 次の手順を完了して、アドインの SSO を構成します。Next, complete the following steps to configure SSO for your add-in.

  1. プロジェクトのルート フォルダーに移動します。Navigate to the root folder of the project.

    cd "My SSO Office Add-in"
    
  2. 次のコマンドを実行して、アドインの SSO を構成します。Run the following command to configure SSO for the add-in.

    npm run configure-sso
    

    警告

    このコマンドは、テナントが 2 要素認証を要求するように構成されている場合、失敗します。This command will fail if your tenant is configured to require two-factor authentication. このシナリオでは、「シングル サインオンを使用する Node.js Office アドインを作成する」チュートリアルで説明されているように、Azure アプリの登録および SSO の構成手順を手動で完了する必要があります。In this scenario, you'll need to manually complete the Azure app registration and SSO configuration steps, as described in the Create a Node.js Office Add-in that uses single sign-on tutorial.

  3. Web ブラウザー ウィンドウが開き、Azure にサインインするように指示されます。A web browser window will open and prompt you to sign in to Azure. Office 365 管理者の資格情報を使用して Azure にサインインします。Sign in to Azure using your Office 365 administrator credentials. これらの資格情報を使用して Azure に新しいアプリケーションが登録され、SSO に必要な設定が構成されます。These credentials will be used to register a new application in Azure and configure the settings required by SSO.

    注意

    この手順で、管理者以外の資格情報を使用して Azure にサインインした場合、configure-sso スクリプトは、組織内のユーザーにアドインの管理者の同意を提供しません。If you sign in to Azure using non-administrator credentials during this step, the configure-sso script won't be able to provide administrator consent for the add-in to users within your organization. そのため、SSO はアドインのユーザーは使用できず、サインインするように求められます。SSO will therefore not be available to users of the add-in and they'll be prompted to sign-in.

  4. 資格情報を入力したら、ブラウザー ウィンドウを閉じ、コマンド プロンプトに戻ります。After you enter your credentials, close the browser window and return to the command prompt. SSO の構成プロセスが続行されると、コンソールに書き込まれたステータス メッセージが表示されます。As the SSO configuration process continues, you'll see status messages being written to the console. コンソール メッセージで説明されているように、Yeoman ジェネレーターが作成したアドイン プロジェクト内のファイルは、SSO プロセスで必要なデータで自動的に更新されます。As described in the console messages, files within the add-in project that the Yeoman generator created are automatically updated with data that's required by the SSO process.

試してみるTry it out

Excel、Word、または PowerPoint アドインを作成した場合は、次のセクションの手順を実行して試してください。 Outlook のアドインを作成した場合は、代わりに Outlook セクションの手順を実行します。If you've created an Excel, Word, or PowerPoint add-in, complete the steps in the following section to try it out. If you've created an Outlook add-in, complete the steps in the Outlook section instead.

Excel、Word、および PowerPointExcel, Word, and PowerPoint

Excel、Word、または PowerPoint アドインを試すには、次の手順を実行します。Complete the following steps to try out an Excel, Word, or PowerPoint add-in.

  1. SSO の構成プロセスが完了したら、次のコマンドを実行してプロジェクトを構築し、ローカル Web サーバーを起動して以前に選択した Office クライアント アプリケーションにアドインをサイドロードします。When the SSO configuration process completes, run the following command to build the project, start the local web server, and sideload your add-in in the previously selected Office client application.

    注意

    開発の最中でも、OfficeアドインはHTTPではなくHTTPSを使用する必要があります。Office Add-ins should use HTTPS, not HTTP, even when you are developing. 次のコマンドを実行した後に証明書をインストールするように求められた場合は、Yeoman ジェネレーターによって提供される証明書をインストールするプロンプトを受け入れます。If you are prompted to install a certificate after you run the following command, accept the prompt to install the certificate that the Yeoman generator provides.

    npm start
    
  2. 前のコマンド (Excel、Word、PowerPoint など) を実行したときに開く Office クライアント アプリケーションで、前のセクションの手順 3 で SSO を構成している間に Azure の接続に使用した Office 365 管理者アカウントと同じ Office 365 組織のメンバーであるユーザーでサインインしていることを確認します。In the Office client application that opens when you run the previous command (i.e., Excel, Word or PowerPoint), make sure that you're signed in with a user that's a member of the same Office 365 organization as the Office 365 administrator account that you used to connect to Azure while configuring SSO in step 3 of the previous section. これにより、SSO を正常に実行するための適切な条件が確立されます。Doing so establishes the appropriate conditions for SSO to succeed.

  3. Office クライアント アプリケーションで、[ホーム] タブを選択し、リボンの [作業ウィンドウの表示] ボタンをクリックして、アドインの作業ウィンドウを開きます。In the Office client application, choose the Home tab, and then choose the Show Taskpane button in the ribbon to open the add-in task pane. 次の画像は、Excel のこのボタンを示しています。The following image shows this button in Excel.

    Excel アドイン ボタン

  4. 作業ウィンドウの下部にある [マイ ユーザー プロファイルの情報を取得する] ボタンを選択して、SSO プロセスを開始します。At the bottom of the task pane, choose the Get My User Profile Information button to initiate the SSO process.

  5. アドインの代わりにアクセス許可を要求するダイアログ ウィンドウが表示される場合は、SSO はシナリオでサポートされず、代わりにアドインが別のユーザー認証方法に戻っていることを意味します。If a dialog window appears to request permissions on behalf of the add-in, this means that SSO is not supported for your scenario and the add-in has instead fallen back to an alternate method of user authentication. これは、テナント管理者がアドインが Microsoft Graph にアクセスするための同意を与えていない場合、または有効な Microsoft アカウントまたは Office 365 (「職場または学校」) アカウントで Office にサインインしていない場合に発生することがあります。This may occur when the tenant administrator hasn't granted consent for the add-in to access Microsoft Graph, or when the user isn't signed into Office with a valid Microsoft Account or Office 365 ("Work or School") account. ダイアログ ウィンドウで [同意する] ボタンを選択して続行します。Choose the Accept button in the dialog window to continue.

    アクセス許可を要求するダイアログ

    注意

    ユーザーがこのアクセス許可の要求を受け入れると、今後再びプロンプトが表示されることはありません。After a user accepts this permissions request, they won't be prompted again in the future.

  6. アドインは、サインインしたユーザーのプロファイル情報を取得し、ドキュメントに書き込みます。The add-in retrieves profile information for the signed-in user and writes it to the document. 次の画像は、Excel ワークシートに書き込まれたプロファイル情報の例を示します。The following image shows an example of profile information written to an Excel worksheet.

    Excel ワークシートのユーザー プロファイル情報

OutlookOutlook

Outlook アドインを試すには、次の手順を実行します。Complete the following steps to try out an Outlook add-in.

  1. SSO 構成プロセスが完了したら、次のコマンドを実行してプロジェクトを構築し、ローカル Web サーバーを起動します。When the SSO configuration process completes, run the following command to build the project and start the local web server.

    注意

    開発の最中でも、OfficeアドインはHTTPではなくHTTPSを使用する必要があります。Office Add-ins should use HTTPS, not HTTP, even when you are developing. 次のコマンドを実行した後に証明書をインストールするように求められた場合は、Yeoman ジェネレーターによって提供される証明書をインストールするプロンプトを受け入れます。If you are prompted to install a certificate after you run the following command, accept the prompt to install the certificate that the Yeoman generator provides.

    npm start
    
  2. テスト用に Outlook アドインをサイドロードする」の手順に従って Outlook アドインをサイドロードします。Follow the instructions in Sideload Outlook add-ins for testing to sideload the add-in in Outlook. 前のセクションの手順 3 で SSO を構成している間に Azure の接続に使用した Office 365 管理者アカウントと同じ Office 365 組織のメンバーであるユーザーで Outlook にサインインしている必要があります。Make sure that you're signed in to Outlook with a user that's a member of the same Office 365 organization as the Office 365 administrator account that you used to connect to Azure while configuring SSO in step 3 of the previous section. これにより、SSO を正常に実行するための適切な条件が確立されます。Doing so establishes the appropriate conditions for SSO to succeed.

  3. Outlook で新しいメッセージを作成します。In Outlook, compose a new message.

  4. [メッセージ作成] ウィンドウで、リボンの [作業ウィンドウの表示] ボタンを選択して、アドインの作業ウィンドウを開きます。In the message compose window, choose the Show Taskpane button in the ribbon to open the add-in task pane.

    Outlook アドイン ボタン

  5. 作業ウィンドウの下部にある [マイ ユーザー プロファイルの情報を取得する] ボタンを選択して、SSO プロセスを開始します。At the bottom of the task pane, choose the Get My User Profile Information button to initiate the SSO process.

  6. アドインの代わりにアクセス許可を要求するダイアログ ウィンドウが表示される場合は、SSO はシナリオでサポートされず、代わりにアドインが別のユーザー認証方法に戻っていることを意味します。If a dialog window appears to request permissions on behalf of the add-in, this means that SSO is not supported for your scenario and the add-in has instead fallen back to an alternate method of user authentication. これは、テナント管理者がアドインが Microsoft Graph にアクセスするための同意を与えていない場合、または有効な Microsoft アカウントまたは Office 365 (「職場または学校」) アカウントで Office にサインインしていない場合に発生することがあります。This may occur when the tenant administrator hasn't granted consent for the add-in to access Microsoft Graph, or when the user isn't signed into Office with a valid Microsoft Account or Office 365 ("Work or School") account. ダイアログ ウィンドウで [同意する] ボタンを選択して続行します。Choose the Accept button in the dialog window to continue.

    アクセス許可を要求するダイアログ

    注意

    ユーザーがこのアクセス許可の要求を受け入れると、今後再びプロンプトが表示されることはありません。After a user accepts this permissions request, they won't be prompted again in the future.

  7. アドインは、サインインしたユーザーのプロファイル情報を取得し、メール メッセージの本文に書き込みます。The add-in retrieves profile information for the signed-in user and writes it to the body of the email message.

    Outlook メッセージのユーザー プロファイル情報

次の手順Next steps

おめでとうございます。可能な場合 SSO を使用し、SSO がサポートされていない場合は別のユーザー認証方法を使用する作業ウィンドウ アドインを正常に作成しました。Congratulations, you've successfully created a task pane add-in that uses SSO when possible, and uses an alternate method of user authentication when SSO is not supported. アドインをカスタマイズして異なる権限を必要とする新しい機能を追加する方法については、「Node.js SSO が有効なアドインのカスタマイズする」をご覧ください。To learn about customizing your add-in to add new functionality that requires different permissions, see Customize your Node.js SSO-enabled add-in.

関連項目See also