Connect the Microsoft Graph API to Tulip with Oauth2

Microsoft Graph API allows the users to interface with Microsoft apps like Teams, Outlook, and Office Suite.

Purpose

Use this document to integrate your Tulip Apps with Microsoft 365 products like Teams, Office Suite, and Outlook.

First-Time Setup

Outline

The following steps must be completed to generate the proper authentication information to use the MS Graph API:

1. Register a new Application in Microsoft Azure.
2. Create a new Client Secret for the Application and declare permissions.
3. Copy the Client Secret & related authentication information to the Tulip Oauth2 Connector Configuration.

In Detail: First-Time Setup

1. Registering a new Application in Microsoft Azure

1. Navigate to portal.azure.com in a web browser.
2. Log in with your organization's credentials.
3. Select Microsoft Entra ID.
   1. Note: formerly known as Azure Active Directory, you may need to select "More Services" to find this option.
4. In the menu on the left side of the page, select App Registrations.
5. Select New Registration and enter a Name.
6. Under Redirect URI, ensure Web is selected and enter the following URL: https://<your Tulip Instance>/oauth-redirect-handler
   for example, the redirect URI for sample.tulip.co would be https://sample.tulip.co/oauth-redirect-handler.
7. Select Register to create the Azure App.

2. Recording Required Information

After registering the App, you'll be forwarded to the new Azure App's configuration page. Copy the following information to a Notepad or text file for later use:

1. Select Overview from the left-side menu and record:
   1. the Application (client) ID, and
   2. the Directory (tenant) ID.
2. Select API Permissions from the left-side menu.
3. Select Application Permissions.
4. Select Microsoft Graph to view all possible permissions for Tulip to have over the Graph API.
5. Select any permissions you wish your Tulip Connector to have. A complete list of permissions can be found here.
   1. Note 1: as a recommendation, use ctrl/cmd + f and search for the Microsoft App you wish to use. For example, search for "Teams" to find permissions related to Channels and Chat.
   2. Note 2: If using this guide to integrate a Tulip Library Connector, a list of permissions the Connector needs to function can be found in the related Tulip Knowledge Base article.
6. Record the API/Permissions Name of all permissions selected, such as Files.Read.All or User.Read.

3. Generating Authentication Information

1. Select Certificates & secrets from the Manage menu on the left side of the App's Azure configuration page.
2. Select Client secrets (0).
3. Select New client secret and name the new secret.
4. Copy the Value shown.

4. Adding Authentication Information to Tulip Connector

Navigate to the Configuration settings of the Tulip Connector you wish to use with the MS Graph API. This can be done by clicking the box labeled OFFLINE - production & testing & develompent on the Connector's main page.

1. Select Edit Headers.
2. Under Authentication, select either:
   1. Oauth2 (Operator) if the app user should have to log into MS 365 whenever they run an integrated Tulip App.
   2. Oauth2 (Service Accounts) if Tulip should only authenticate to MS 365 when this configuration is set or changed, and use this login information for all apps on your Tulip Instance.
3. Enter the following information recorded previously for the rest of the options:
   1. Authorization Code URL: https://login.microsoftonline.com/the Directory (tenant) ID from Step 2.1.b/oauth2/v2.0/authorize
   2. Access Token URL: https://login.microsoftonline.com/the Directory (tenant) ID from Step 2.1.b/oauth2/v2.0/token
   3. Client ID: the Application (client) ID from Step 2.1.a
   4. Client Secret: the Value from Step 3.4
   5. Scope: a comma-separated list of the Permission Names added in Step 2.6, such as Files.Read.All,User.Read
4. Select Test to test the authentication method.
5. Select Back to return to the Connector Configuration.
6. Finally, on the Enter Connection Details screen enter the following information:
   1. Running On: Select Cloud Connector Host unless known otherwise.
   2. Host: graph.microsoft.com
   3. Port: 443 (or leave blank)TLS
   4. TLS : Yes
7. Select Test, and configuration is complete!

5. Example

Watch the video below to see an example of the written content above.
Video of setting up the connector for excel: