Edit

Single sign-on (SSO) quick start

  • Article

In this article, you'll use the Yeoman generator for Office Add-ins to create an Office Add-in for Excel, Outlook, Word, or PowerPoint that uses single sign-on (SSO).

Note

The SSO template provided by the Yeoman generator for Office Add-ins only runs on localhost and cannot be deployed. If you're building a new Office Add-in with SSO for production purposes, follow the instructions in Create a Node.js Office Add-in that uses single sign-on.

Prerequisites

  • Node.js (the latest LTS version).

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

  • If you're using a Mac and don't have the Azure CLI installed on your machine, you must install Homebrew. 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

Tip

The Yeoman generator can create an SSO-enabled Office Add-in for Excel, Outlook, Word, or PowerPoint 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. A folder that contains the project will be added to the current directory.

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 (localhost)
  • Choose a script type: JavaScript
  • What do you want to name your add-in? My Office Add-in
  • Which Office client application would you like to support? Choose Excel, Outlook, Word, or Powerpoint.

Prompts and answers for the Yeoman generator in a command line interface.

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

Note

If you're using Node.js version 20.0.0 or later, you may see a warning when the generator runs the installation that you have an unsupported engine. We're working on a fix for this. In the meantime, the warning doesn't affect the generator or the project you generate, so it can be ignored.

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.

Configuration

The following files specify configuration settings for the add-in.

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

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

Task pane

The following files define the add-in's task pane UI and functionality.

  • 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 code to initialize the add-in and also code that uses the Office JavaScript API library to add the data from Microsoft Graph to the Office document.

Authentication

The following files facilitate the SSO process and write data to the Office document.

  • In a JavaScript project, the ./src/helpers/documentHelper.js file contains code that encapsulates the user's profile information for insertion into the current Office document. There's no such file in a TypeScript project. Instead, the code that gathers the profile information is inline in the ./src/taskpane/taskpane.ts file.

  • The ./src/helpers/fallbackauthdialog.html file is the UI-less page that loads the JavaScript for the fallback authentication strategy. The <script> tag to load the JavaScript is inserted into the file when Webpack.config.js runs.

  • The ./src/helpers/fallbackauthdialog.js file contains the JavaScript for the fallback authentication strategy that signs in the user with msal.js.

  • The ./src/helpers/message-helper.js file contains JavaScript that shows or hides error messages to the user.

  • The ./src/helpers/middle-tier-calls.js file contains the JavaScript that calls your web API for fetching data.

  • The ./src/helpers/sso-helper.js file contains the JavaScript call to the SSO API, getAccessToken, receives the access token, and includes it in a call to Microsoft Graph for the data. In the event of an error or in scenarios when SSO authentication isn't supported, it invokes the fallback strategy.

Configure SSO

Now that your add-in project is created and contains the code that's necessary to facilitate the SSO process, complete the following steps to configure SSO for your add-in.

  1. Go to the root folder of the project.

    cd "My 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 by following all the steps 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 Microsoft 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.

Test your add-in

If you've created an Excel, Word, or PowerPoint add-in, complete the steps in the following section to try it. If you've created an Outlook add-in, complete the steps in the Outlook section instead.

Excel, Word, and PowerPoint

Complete the following steps to test an Excel, Word, or PowerPoint add-in.

  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 while you're developing. If you're prompted to install a certificate after you run one of the following commands, accept the prompt to install the certificate that the Yeoman generator provides. You may also have to run your command prompt or terminal as an administrator for the changes to be made.

    npm start

  2. When Excel, Word, or PowerPoint opens when you run the previous command, make sure you're signed in with a user account that's a member of the same Microsoft 365 organization as the Microsoft 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 Show Taskpane to open the add-in task pane.

    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.

  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 in to Office with a valid Microsoft account or Microsoft 365 Education or Work account. Choose Accept to continue.

    The permissions requested dialog with Accept button highlighted.

    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.

    The user profile information in Excel worksheet.

Outlook

Complete the following steps to try out an Outlook add-in.

  1. When the SSO configuration process completes, run the following command to build the project and start the local web server.

    Note

    Office Add-ins should use HTTPS, not HTTP, even while you're developing. If you're prompted to install a certificate after you run one of the following commands, accept the prompt to install the certificate that the Yeoman generator provides. You may also have to run your command prompt or terminal as an administrator for the changes to be made.

    npm start

  2. Follow the instructions in Sideload Outlook add-ins for testing to sideload the add-in in Outlook. Make sure that you're signed in to Outlook with a user that's a member of the same Microsoft 365 organization as the Microsoft 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 Outlook, compose a new message.

  4. In the message compose window, choose the Show Taskpane button to open the add-in task pane.

    The highlighted add-in ribbon button in Outlook compose message window.

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

  6. 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 in to Office with a valid Microsoft account or Microsoft 365 Education or Work account. Choose Accept to continue.

    The permissions requested dialog with Accept button highlighted.

    Note

    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.

    The user profile information in Outlook compose message window.

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 about customizing your add-in to add new functionality that requires different permissions, see Customize your Node.js SSO-enabled add-in.

Troubleshooting

See also