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 is interacting with Microsoft Cloud services, such as SharePoint, OneDrive, Dynamics etc, they will likely be using 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? 

To interact with the web API, an auth token is required. 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 in order to interact with Microsoft Teams from FME, using the MicrosoftTeamsConnector transformer.
 

Prerequisites 

Creating a web service requires a level of understanding, so it is recommended to review the Microsoft documentation prior to setting up a Microsoft Graph web service: Authentication and authorization basics for Microsoft Graph.
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 recommend to have both FME and Azure Portal open at the same time to copy information between the two.
 

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 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 will be on FME Server, 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, and enter in the Application (client) ID and redirect 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 common, or a tenant ID.
This will depend on the accounts you chose 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

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

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 user.read

In this example, the only scope requested is offline_access and user.read.

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

You can read about the offline_access scope, and others, in the Permissions and consent section of the Microsoft identity platform documentation. 

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


 

8. Confirm the Refresh Token parameters

At the bottom of the web service definition in FME there are Refresh Token Parameters.

This will be automatically configured. You will only need to change these if your application in Azure Portal is registered as a Desktop or Mobile Application.
If that is the case, you will need to mark the client 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 go on to create a Microsoft Teams web connection.

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