Skip to content

Latest commit

 

History

History
149 lines (97 loc) · 7.77 KB

README.md

File metadata and controls

149 lines (97 loc) · 7.77 KB
Raw
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

Node.js build License.

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 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:

Register a web application with the Microsoft Entra admin center

  1. Open a browser and navigate to the Microsoft Entra admin center. Login using a Work or School Account.

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

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

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

  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 Home tab, then select Add-ins.

  4. Select More Add-ins, then select My Add-ins.

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

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