microsoftgraph/msgraph-sample-office-addin

This sample demonstrates how to use the Microsoft Graph JavaScript SDK to access data in Office 365 from Office Add-ins.

page_type	description	products	languages
sample	This sample demonstrates how to use the Microsoft Graph JavaScript SDK to access data in Office 365 from Office Add-ins.	ms-graph office-exchange-online	typescript javascript

Microsoft Graph sample Office Add-in

This sample demonstrates how to use the Microsoft Graph JavaScript SDK to access data in Office 365 from Office Add-ins.

Prerequisites

To run the completed project in this folder, you need the following:

• Node.js and Yarn installed on your development machine. (Note: This tutorial was written with Node version 16.14.2 and Yarn version 1.22.19. The steps in this guide may work with other versions, but that has not been tested.)
• Either a personal Microsoft account with a mailbox on Outlook.com, or a Microsoft work or school account.

If you don't have a Microsoft account, there are a couple of options to get a free account:

• You can sign up for a new personal Microsoft account.
• You can sign up for the Microsoft 365 Developer Program to get a free Microsoft 365 subscription.

Register a web application with the Azure Active Directory admin center

1. Open a browser and navigate to the Azure Active Directory admin center. Login using a personal account (aka: Microsoft Account) or Work or School Account.

2. Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.

3. Select New registration. On the Register an application page, set the values as follows.

   • Set Name to Office Add-in Graph Tutorial.
   • Set Supported account types to Accounts in any organizational directory and personal Microsoft accounts.
   • Under Redirect URI, set the first drop-down to Single-page application (SPA) and set the value to https://localhost:3000/consent.html.

4. Select Register. On the Office Add-in Graph Tutorial page, copy the value of the Application (client) ID and save it, you will need it in the next step.

5. Select Certificates & secrets under Manage. Select the New client secret button. Enter a value in Description and select one of the options for Expires and select Add.

6. Copy the client secret value before you leave this page. You will need it in the next step.

   [!IMPORTANT] This client secret is never shown again, so make sure you copy it now.

7. Select API permissions under Manage, then select Add a permission.

8. Select Microsoft Graph, then Delegated permissions.

9. Select the following permissions, then select Add permissions.

   • Calendars.ReadWrite - this will allow the app to read and write to the user's calendar.
   • MailboxSettings.Read - this will allow the app to get the user's time zone from their mailbox settings.

Configure Office Add-in single sign-on

Update the app registration to support Office Add-in single sign-on (SSO).

1. Select Expose an API. In the Scopes defined by this API section, select Add a scope. When prompted to set an Application ID URI, set the value to api://localhost:3000/YOUR_APP_ID_HERE, replacing YOUR_APP_ID_HERE with the application ID. Choose Save and continue.

2. Fill in the fields as follows and select Add scope.

   • Scope name: access_as_user
   • Who can consent?: Admins and users
   • Admin consent display name: Access the app as the user
   • Admin consent description: Allows Office Add-ins to call the app's web APIs as the current user.
   • User consent display name: Access the app as you
   • User consent description: Allows Office Add-ins to call the app's web APIs as you.
   • State: Enabled

3. In the Authorized client applications section, select Add a client application. Enter a client ID from the following list, enable the scope under Authorized scopes, and select Add application. Repeat this process for each of the client IDs in the list.

   • d3590ed6-52b3-4102-aeff-aad2292ab01c (Microsoft Office)
   • ea5a67f6-b6f3-4338-b240-c655ddc3cc8e (Microsoft Office)
   • 57fb890c-0dab-4253-a5e0-7188c88b2bb4 (Office on the web)
   • 08e18876-6177-487e-b8b5-cf950c1e598c (Office on the web)

Install development certificates

1. Run the following command to generate and install development certificates for your add-in.

   npx office-addin-dev-certs install

   If prompted for confirmation, confirm the actions. Once the command completes, you will see output similar to the following.

   You now have trusted access to https://localhost.
   Certificate: <path>\localhost.crt
   Key: <path>\localhost.key

2. Copy the paths to localhost.crt and localhost.key, you'll need them in the next step.

Update the manifest

1. Open the manifest.xml file and make the following changes.
   1. Replace NEW_GUID_HERE with a new GUID, like b4fa03b8-1eb6-4e8b-a380-e0476be9e019.
   2. Replace all instances of YOUR_CLIENT_ID_HERE with the application ID from your app registration.

Configure the sample

1. Rename the example.env file to .env.

2. Edit the .env file and make the following changes.

   1. Replace YOUR_APP_ID_HERE with the Application Id you got from the App Registration Portal.
   2. Replace YOUR_CLIENT_SECRET_HERE with the client secret you got from the App Registration Portal.
   3. Replace PATH_TO_LOCALHOST.CRT with the path to your localhost.crt file from the output of the npx office-addin-dev-certs install command.
   4. Replace PATH_TO_LOCALHOST.KEY with the path to your localhost.key file from the output of the npx office-addin-dev-certs install command.

3. Rename the config.example.js file to config.js.

4. Edit the config.js file and make the following changes.

   1. Replace YOUR_APP_ID_HERE with the Application Id you got from the App Registration Portal.

5. In your command-line interface (CLI), navigate to this directory and run the following command to install requirements.

   yarn install

Run the sample

1. Run the following command in your CLI to start the application.

   yarn start

2. In your browser, go to Office.com and sign in. Select Create in the left-hand toolbar, then select Workbook.

3. Select the Insert tab, then select Office Add-ins.

4. Select Upload My Add-in, then select Browse. Upload your manifest.xml file.

5. Select the Import Calendar button on the Home tab to open the task pane.

Code of conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Disclaimer

THIS CODE IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING ANY IMPLIED WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR NON-INFRINGEMENT.

msgraph-sample-office-addin's Issues

Project deployment

Hello everyone!

Sorry if it is not a place to ask this kind of questions (if it is not, could you please tell me where to ask it?).
Would you consider adding a deployment instruction to this toutorial? I look for tips on how to deploy the Excel Web Addin in Corporate environment. Is this tutorial suitable for this example https://learn.microsoft.com/en-us/office/dev/add-ins/publish/host-an-office-add-in-on-microsoft-azure?

This repo is missing important files

There are important files that Microsoft projects should all have that are not present in this repository. A pull request has been opened to add the missing file(s). When the pr is merged this issue will be closed automatically.

Microsoft teams can learn more about this effort and share feedback within the open source guidance available internally.

Merge this pull request

Adapting this add-in for Outlook

I was trying to use this tutorial as a basis to create a similar add-in but for Outlook.
I think I all the required changes to make the addin compatible with Outlook, as I am able to install the add-on on Outlook via the manifesto. But the Office.OnReady() function doesn't seem to fire off and the message in the taskpane is just "Checking authorization...". What could be the issue here?

I used npx office-addin-manifest validate manifest.xml to see if the manifesto is valid and got an error: Error: Cannot find module 'fs-extra', although only fs is used, since I did not change any of the server/api files from the tutorial, only the manifesto and the taspane.ts to have Outlook instead of Excel.

Anny help is much appreciated!

JWT verification problem occuring

When loading the addin in excel the CLI displays

and i am guessing is there something i am missing , as authentication is working perfectly but the only problem i am encountering is that it is not fetching at all just showing the progress as working only , any solutions ?

Thank you for taking an interest in Microsoft Graph development! Please feel free to ask a question here, but keep in mind the following:

• This is not an official Microsoft support channel, and our ability to respond to questions here is limited. Questions about Graph, or questions about adding a new feature to the sample, will be answered on a best-effort basis.
• Questions should be asked on Stack Overflow.
• Issues with Microsoft Graph itself should be handled through support.

ACTION REQUIRED: Microsoft needs this repository to complete compliance info

There are open compliance tasks that need to be reviewed for your msgraph-training-office-addin repo.

Action required: 3 compliance tasks

To bring this repository to the standard required for 2021, we require Microsoft administrators of this GitHub repository to complete a small set of tasks within the next 60 days. This is critical work to ensure the compliance and security of your GitHub repo.

Microsoft repo admins: Please take a few minutes to complete the tasks at: https://repos.opensource.microsoft.com/orgs/microsoftgraph/repos/msgraph-training-office-addin/compliance

You can close this work item once you have completed the compliance tasks, or it will automatically close within a day of taking action.

If you no longer need this repository, it might be quickest to delete the repo, too.

Confusing about the graph API token

I want to point out that there might be a confusing part in the documentation.

According to the documentation, in order to get the graph API, we need to provide the so-called "bootstrap token" to exchange, this is correct if the OfficeRuntime.auth.getAccessToken works well.

But if the OfficeRuntime.auth.getAccessToken failed and fall back to the user consent, the Token generated from the user consent pop up could be provided directly to the Graph API, and no need to do the exchange again.

The above points confusing me for a long time, and keep getting the JWT error saying: invalid signature since I thought even the token from the consent pop up should do the exchange process.

I'm not sure if anything I missed from the documentation or the code, but I think this point needs to point out to avoid confusion.

Correct me if I was wrong.