Integrating with the Microsoft Graph API

Microsoft offers a RESTful web service named Microsoft Graph API. This tutorial shows you how to integrate with the Microsoft Graph API and Linx, a low-code development tool. By doing so, you can easily extend the functionality of MS Graph with other 3rd party applications such as Xero, Google Drive, QuickBooks, and other system APIs.

Microsoft Graph Integration

The scope of the Microsoft Graph API is pretty large and allows all your entities on Office365 to connect to one another. The following will be covered in this guide:

1. Setup of an Azure OAuth 2.0 App
2. Authenticating and connecting to the Microsoft API
3. Example requests

1. Register an application With Azure

In order for you to interact with the Microsoft Graph API, you must first register an app and configure the permissions, this will then provide you with the necessary authorization details which you can then use to generate your Access and Refresh tokens.

1. Log in to the Microsoft Azure Portal.
2. Open the App Registrations tab (Left Menu bar > Manage > App registrations).
3. Click on the + New Registration button at the top of the screen.
4. Give the connected application a name such as “LinxDemoApp” and the appropriate account type.
5. For the Redirect URI set the type to Web and add the following:

http://localhost:8080/microsoft/oauth/token

1. Click Register at the bottom of the screen. Your connected application has now been registered and the client identifiers are displayed on the screen.
2. Copy and store the Application ID (Client ID) and Directory ID (Tenant ID) for later

2. Generate Client Secret

Now that we’ve registered an App on Azure, we now have to generate a client secret, which is a set of characters that identifies your App when requesting tokens. This will be used in conjunction with the client identifiers generated earlier.

1. On the new App’s overview page, navigate to Certificates and secrets.
2. Next, under the ‘Client secrets’ section, click on +New Client Secret.
3. Give your secret description as well as an expiry period and click Add.
4. Once generated, your client secret will be displayed. Copy the Value and save it in a secure location for the next section.

3. Configure Linx Application Settings

Open the provided sample application in the Linx Designer and update the $.Settings of the Linx application with the client identifiers like below:

• linx_database_conn_string: Connection string used for storing and retrieving the authentication token from a database. Read more about creating connection strings here.
• microsoft_app_client_id: Your connected app’s Client ID.
• microsoft_app_client_secret: Your connected app’s Client Secret.
• microsoft_app_scopes: Access scopes of the app.
• microsoft_app_tenantID: Tenant identifier – referred to as the Directory ID or the Tenant ID on the App’s overview page.

Your Linx Solution’s $.Settings should look like below:

4. Generate the Access Token

1. In the Linx Designer, start debugging the REST service
2. Once started, in your browser, navigate to this URL.
3. Log into Microsoft and grant access to your registered app.
4. Once you’ve granted access, the Microsoft Graph authorization server will redirect your browser to the Redirect URI with the code and state parameters. This will trigger the access token generation, if successful, the resulting message should be displayed in your browser like below:

{
  "date":"2021-01-06T13:15:48.1323123+02:00",
  "summary":"Linx application successfully authorized.",
  "platform":"MICROSOFT",
  "authorized_entity":"LinxDemoApp"
}

This indicates that Linx successfully generates and stores the access token in the database. This token information will be retrieved from the database once a request is made.

5. Making requests to the Microsoft Graph API

Requests are made using a Call REST Service following the below structure:

https://graph.microsoft.com/v1.0/{path}

To authenticate the request, including the Authorization header containing the access token generated in the previous step like below:

Authorization: "Bearer " + {access token}

In the provided sample Solution, the access token is retrieved from the database before each request is made. The retrieved access token is then submitted in the Authorization header:

= "Bearer " +   RetrieveToken_database.token.access_token

Take a look at the custom function getApplication in the provided sample to get an understanding of interacting with the Microsoft Graph API.