Office Add-in that supports Single Sign-on to Office, the Add-in, and Microsoft Graph
getAccessTokenAsync API in Office.js enables users who are signed into Office to get access to an AAD-protected add-in and to Microsoft Graph without needing to sign-in again. This sample is built on Node.js and express.
getAccessTokenAsyncAPI is in preview.
Table of Contents
- May 10, 2017: Initial version.
- September 15, 2017: Added handling for 2FA.
- December 8, 2017: Added extensive error handling.
- December 19, 2018: Updated to more recent versions of some dependencies.
- January 7, 2019: Added information about application security mitigations.
- An Office 365 account.
- During the preview phase, the SSO requires Office 365 (the subscription version of Office, also called “Click to Run”). You should use the latest monthly version and build from the Insiders channel. You need to be an Office Insider to get this version. For more information, see Be an Office Insider. Please note that when a build graduates to the production semi-annual channel, support for preview features, including SSO, is turned off for that build.
- Git Bash (Or another git client.)
- TypeScript version 2.2.2 or later.
Deviations from Best Practices
The samples in this repo are narrowly focused on demonstrating the use of the SSO APIs. To keep it simple, some best practices are not followed, including best practices in web application security. You should not use any of these samples as the starting point of a production add-in unless you are prepared to make substantial changes. We recommend that you begin a production add-in by using one of the Office Add-in projects in Visual Studio, or by generating a new project with the Yeoman Generator for Office Add-ins.
Some of the points to keep in mind about these samples:
- Do not ship reusable certs as these samples do. Produce your own certs for your server and make sure they are not web-accessible.
- The samples send a hardcoded query parameter on the URL for the Microsoft Graph REST API. If you modify this code in a production add-in and any part of query parameter comes from user input, be sure that it is sanitized so that it cannot be used in a Response header injection attack.
To use the project
This sample is meant to accompany the walkthrough at: Create a Node.js Office Add-in that uses Single Sign-on (preview).
There are three versions of the sample, in the folders Before, Completed, Completed Multitenant.
To use the Before version and manually add the crucial SSO-oriented code, follow all the procedures in the article linked to above.
To work with the Completed versions, follow all the procedures, except the sections "Code the client-side" and "Code the server-side" in the article linked to above.
Completed Multitenant version allows you to use SSO with any Microsoft account regardless of its domain.
IMPORTANT: Regardless of which version you use, you will need to trust a certificate for the localhost. Follow the instructions here, except that the
certsfolders for each of the versions in this repo is in the
/srcfolder, not the root folder.
Questions and comments
We'd love to get your feedback about this sample. You can send your feedback to us in the Issues section of this repository.
Copyright (c) 2017 Microsoft Corporation. All rights reserved.