Use the Yeoman generator to create an Office Add-in that uses single sign-on (preview)

In this article, you'll walk through the process of using the Yeoman generator to create an Office Add-in for Excel, Word, or PowerPoint that uses single sign-on (SSO) when possible, and uses an alternate method of user authentication when SSO is not supported.

Tip

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.

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. 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 (version 10.15.0 or later)

  • 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
    

    Note

    Even if you've previously installed the Yeoman generator, we recommend you update your package to the latest version from npm.

  • An Office 365 (the subscription version of Office) account. 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.

  • An Insider's build of Office 365. 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.

    Note

    When a build graduates to the production semi-annual channel, support for preview features, including SSO, is disabled for that build.

Create the add-in project

Tip

The Yeoman generator can create an SSO-enabled Office Add-in for Excel, Word, or PowerPoint, and can be created with script type of JavaScript or TypeScript. 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

Note

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-on
  • Choose a script type: Javascript
  • What do you want to name your add-in? My SSO Office Add-in
  • Which Office client application would you like to support? Excel

A screenshot of the prompts and answers for the Yeoman generator

After you complete the wizard, the generator creates the project and installs supporting Node components.

Tip

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

The add-in project that you've created with the Yeoman generator contains code for an SSO-enabled task pane add-in.

  • The ./manifest.xml file in the root directory of the project defines the settings and capabilities of the add-in.

  • The ./src/taskpane/taskpane.html file contains the HTML markup for the task pane.

  • The ./src/taskpane/taskpane.css file contains the CSS that's applied to content in the task pane.

  • The ./src/taskpane/taskpane.js file contains the Office JavaScript API code that facilitates interaction between the task pane and the Office host application.

  • The ./src/helpers/documentHelper.js file uses the Office JavaScript library to add the data from Microsoft Graph to the Office document.

  • The ./src/helpers/fallbackauthdialog.html file is the UI-less page that loads the fallback authentication method's JavaScript.

  • The ./src/helpers/fallbackauthdialog.js file contains the fallback authentication method's JavaScript that signs on the user with msal.js.

  • The ./src/helpers/fallbackauthhelper.js file contains the task pane JavaScript that invokes the fallback authentication method in scenarios when SSO authentication is not supported.

  • 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.

  • The ./ENV file in the root directory of the project defines constants that are used by the add-in project.

    Note

    Some of the constants defined in this file are used to facilitate the SSO process. You may want to update values in this file to match your specific scenario. For example, you can update this file to specify a different scope, if your add-in requires something other than User.Read.

Configure SSO

At this point, your add-in project has been created and contains the code that's necessary to facilitate the SSO process. 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. Run the following command to configure SSO for the add-in.

    npm run configure-sso
    

    Warning

    This command will fail if your tenant is configured to require two-factor authentication. 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. A web browser window will open and prompt you to sign in to Azure. Sign in to Azure using your Office 365 administrator credentials. These credentials will be used to register a new application in Azure and configure the settings required by SSO.

    Note

    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 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. As the SSO configuration process continues, you'll see status messages being written to the console. 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

  1. 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.

    Note

    Office Add-ins should use HTTPS, not HTTP, even when you are developing. 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. 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. Doing so establishes the appropriate conditions for SSO to succeed.

  3. 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. The following image shows this button in Excel.

    Excel add-in button

  4. At the bottom of the task pane, choose the Get My User Profile Information button to initiate the SSO process.

    Note

    If you're not already signed in to Office at this point, you'll be prompted to sign in. As described previously, you should sign 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, if you want SSO to succeed.

  5. 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. 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.

    Permissions request dialog

    Note

    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. The following image shows an example of profile information written to an Excel worksheet.

    User profile information in Excel worksheet

Next steps

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. To learn more about SSO configuration steps that the Yeoman generator completed automatically, and the code that facilitates the SSO process, see the Create a Node.js Office Add-in that uses single sign-on tutorial.

See also