How to create a web service for Microsoft Graph (Microsoft Teams)

Introduction

Microsoft Graph is a RESTful web API that enables you to access Microsoft Cloud service resources. If an FME user interacts with Microsoft Cloud services such as SharePoint, OneDrive, Dynamics, etc., they will likely use Microsoft Graph. If you wish to integrate with another Microsoft cloud service, you can still follow these steps, but you will need to alter the permissions granted to your application.

Microsoft Graph exposes REST APIs for these services: What’s in Microsoft Graph?

An auth token is required to interact with the web API. Instead of repeatedly (manually) obtaining that auth token or cluttering up a workspace with a string of HTTPCallers to do the auth flow, an FME web service and web connection can be used.

For more information, please read this article: Web Connections and FME

This example will create a Microsoft Teams web service. The purpose of the Microsoft Teams web service and web connection is to allow users to authenticate with the Microsoft Graph API and interact with Microsoft Teams from FME using the MicrosoftTeamsConnector transformer.

Prerequisites 

Creating a web service requires some understanding, so it is recommended that you review the Microsoft documentation: Authentication and authorization basics for Microsoft Graph prior to setting up a Microsoft Graph web service. Many of the steps in this tutorial will refer to Microsoft documentation.

Please note that setting up web services, web connections, and custom ‘connector’ transformers relies heavily on external (to FME) documentation and services. Any content linked or screenshots are subject to change.

It is recommended that both FME and Azure Portal be open at the same time to copy information between them.

Step-by-Step Instructions

1. Identify Which API you Need to Use and How it Authenticates

The Microsoft Graph API is a single endpoint that allows users to access data and insights from the Microsoft cloud. Microsoft Teams is one of the services that is supported.

The MicrosoftTeamsConnector transformer makes several API calls, so it is useful to have the API reference documentation available when creating the web service. 

Microsoft Graph uses OAuth 2.0, which means that your application (FME) must acquire an access token from Microsoft identity platform before making any API calls. Creating a web service definition in FME, and then a web connection, means that FME will acquire that token on a user’s behalf when that web connection is used in a workspace.

Recommended reading: Authentication and Authorization Basics for Microsoft Graph 

2. Register Your Application With the Microsoft Identity Platform

In order to get a token, the application must first be registered with the Microsoft identity platform, which is done through the Azure Portal.

Registering your application integrates it with the identity platform and will provide the information needed to get tokens, such as:

• Application (Client) ID
• Redirect URI
• Application (Client) Secret

All of these are requirements in FME to set up a web service:

Follow these instructions to register your application: Register an application with the Microsoft Identity platform

For the platform and redirect uri configuration, leave it set to Web, and you can use http://localhost. 

If your web connection is on FME Flow, you may need to add an additional redirect URI of http(s)://<YourFMEServerHostname>/fmeoauth

The Application (client) ID can be found on the Overview page of the App Registration:


 

3. Create a new OAuth 2.0 Web Service in FME

In FME, you will need to create a new web service. To access the below dialog window, open FME Options > Web Connections > Manage Web Services > + > OAuth 2.0 Service

You will need to name your web service, enter the Application (client) ID, and redirect the URI obtained in step 2.

4. Configure Application Permissions

In Azure Portal, you will need to configure the permissions that the application will need.

If you’re unsure what permissions to give, you can use the Microsoft permissions reference or the Microsoft Graph REST API v1.0 reference.

For the MicrosoftTeamsConnector, you will need the below permissions:

Microsoft Graph:
Channel.ReadBasic.All
ChannelMessage.Send
Directory.Read.All
Group.Read.All
User.Read

These are obtained from the following API calls in the MicrosoftTeamsConnector:

List joinedTeams 
List channels 
Create chatMessage in a channel  
Get filesFolder
List children of a driveItem
Access a group team site

You will need to grant admin consent for your organization.

5. Obtain Client Secret

Within your app registration in Azure Portal, select Certificates & secrets. Under Client Secrets. Click New client secret to create a new secret. You can configure a description and expiration interval. You must copy the value of the new secret at this point, as the full value of the client secret is only displayed to you once. Ensure that you’re copying the secret value and not the ID.

Copy and enter this client secret to your new web service definition in FME.

For Microsoft's examples of how to do this, see here or here.

6. Configure the Authorization and Token Endpoints

FME will request permission by making an authorization request.

FME needs to know what the authorization endpoint is and provide some different parameters (step 7).

To find your authorization endpoint, read this page: Microsoft Identity Platform Endpoints 

Typically, we see users replace the tenant value with either a common or a tenant ID.
This will depend on the accounts you choose to support in step 2. If your application is single-tenant, your tenant value will be your tenant ID. If your application is multi-tenant, your tenant value will be common.

If you’re unsure, you can check in the Azure Portal, either on the Authentication blade:



or by clicking on Endpoints on the overview page:

Copy these endpoints into your web service definition in FME:

7. Configure the Authorization and Token URL Parameters

View the Get access on behalf of a user documentation to see what FME needs to send to the Microsoft identity platform endpoint.

As some of those parameters are already specified in FME (client ID, for example), we only need to add a few. 

Edit the Authorization URL, Token Refresh URL, and append 

?response_type=code&response_mode=query&state=13278&scope=offline_access%20user.read

In this example, the only scope requested is offline_access and user.read. "%20" is the URL-encoded representation of a space character.

Offline access gives you a token with a longer lifetime, so you don’t have to re-authenticate regularly.
User reading allows Microsoft to verify identity by authenticating the user's profile.

The Permissions and Consent section of the Microsoft identity platform documentation describes the offline_access scope and others. 

We could also include the permissions from step 4 in the scope, but as they have already been consented to, they don’t need to be. You can read about the consent experience here.

8. Confirm the Refresh Token Parameters

At the bottom of the FME web service definition, there are Refresh Token parameters.

This will be automatically configured. You will only need to change these if your Azure Portal application is registered as a Desktop or Mobile Application.
If that is the case, you will need to mark the client's secret optional and remove this part of the Request Format:

&client_secret=[CLIENT_SECRET]

This is because Microsoft doesn’t trust desktop applications to safely store a client secret and will reject any authorization requests that contain one.

The Microsoft documentation also specifies that the refresh token also includes a grant_type parameter. FME, by default, adds a response_type parameter, so this needs to be corrected.
The final Request Format may look like this:

client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&refresh_token=[REFRESH_TOKEN]&grant_type=refresh_token

9. Test the Web Service

Now that the web service is configured in FME click Apply and then Test.
You should be prompted to sign into your Microsoft account.
If it is successful, you can create a Microsoft Teams web connection.

If it fails, the error message should provide insight into why.