Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/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.
https://github.com/microsoftgraph/msgraph-sample-office-addin

devxsample microsoft-graph office-addin

Last synced: 7 months ago
JSON representation

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

Awesome Lists containing this project

README 

          
---

page_type: sample

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

products:

- ms-graph

- office-exchange-online

languages:

- typescript

- javascript

---



# Microsoft Graph sample Office Add-in



[![Node.js build](https://github.com/microsoftgraph/msgraph-training-office-addin/actions/workflows/node.js.yml/badge.svg)](https://github.com/microsoftgraph/msgraph-training-office-addin/actions/workflows/node.js.yml) ![License.](https://img.shields.io/badge/license-MIT-green.svg)



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](https://nodejs.org) and [Yarn](https://yarnpkg.com/) installed on your development machine. (**Note:** This sample 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](https://signup.live.com/signup?wa=wsignin1.0&rpsnv=12&ct=1454618383&rver=6.4.6456.0&wp=MBI_SSL_SHARED&wreply=https://mail.live.com/default.aspx&id=64855&cbcxt=mai&bk=1454618383&uiflavor=web&uaid=b213a65b4fdc484382b6622b3ecaa547&mkt=E-US&lc=1033&lic=1).

- You can [sign up for the Microsoft 365 Developer Program](https://developer.microsoft.com/microsoft-365/dev-program) to get a free Microsoft 365 subscription.



## Register a web application with the Microsoft Entra admin center



1. Open a browser and navigate to the [Microsoft Entra admin center](https://entra.microsoft.com). Login using a **Work or School Account**.



1. Select **Applications** in the left-hand navigation bar, then select **App registrations**.



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



    - Set **Name** to `Office Add-in Graph Sample`.

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



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



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



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



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



1. Select **Microsoft Graph**, then **Delegated permissions**.



1. 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)](https://learn.microsoft.com/office/dev/add-ins/develop/sso-in-office-add-ins).



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



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



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



    ```Shell

    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.



    ```Shell

    You now have trusted access to https://localhost.

    Certificate: \localhost.crt

    Key: \localhost.key

    ```



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

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

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

    1. Replace `YOUR_CLIENT_SECRET_HERE` with the client secret you got from the App Registration Portal.

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

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



1. Rename the `config.example.js` file to `config.js`.

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

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



    ```Shell

    yarn install

    ```



## Run the sample



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



    ```Shell

    yarn start

    ```



1. In your browser, go to [Office.com](https://www.office.com/) and sign in. Select **Create** in the left-hand toolbar, then select **Workbook**.



1. Select the **Home** tab, then select **Add-ins**.



1. Select **More Add-ins**, then select **My Add-ins**.



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



1. 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](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) 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.**