How to Create a MicrosoftTeamsConnector Multitenant Web Connection for FME Form

Introduction

This article will walk through configuring a MicrosoftTeamsConnector web connection in FME Form using a multitenant Azure app registration with delegated Graph API permissions. Delegated permissions applied to the Azure app registration require a user to authenticate the FME web connection with valid Microsoft credentials (user name and password). For instructions on configuring this web connection using a single tenant Azure app registration, please see How to Create a OneDriveConnector Single Tenant Web Connection for FME Form.

Please note that Microsoft Azure Portal is subject to change at any time; the instructions and screenshots provided in this article may be slightly different from what other users see in their Azure Portal menus, but the concepts for configuring the Azure app registration described herein remain the same.

Requirements

Access to Microsoft Azure Portal with permissions required to create and manage an Azure app registration.

Step-by-Step Instructions

Part 1: Create the Azure App Registration

Before creating a MicrosoftTeamsConnector web connection in FME Form, you must create an app registration in Microsoft Azure Portal.

1. Register an App in the Azure Portal

App Registration

Add a new registration.

New App Registration

Choose the option "Accounts in any organizational directory (Multitenant)’’. Leave the Redirect URI blank for now; we will update this later if necessary. Click Register.

2. Obtain the Client ID Value

Note the Application (client) ID value on the new app registration's Overview page. In a later step, this value will be used to configure the new FME web service.

You can confirm your app registration is multitenant by checking the value of 'Supported account types'. Multitenant app registrations will display a value of 'Multiple organizations' for this setting.

3. Add the 'Mobile and Desktop Applications' Platform

Click the Authentication option along the left-side menu, and then select 'Add a platform'. Choose the 'Mobile and Desktop applications' platform.

Ensure you see the following redirect URI included in the displayed list of URLs:

https://login.microsoftonline.com/common/oauth2/nativeclient

If you do not see the above URL included, please add it as a Custom redirect URI. Then, click Configure at the bottom left.

You should now see the Mobile and Desktop Applications platform enabled for your Azure app registration.

4. Add Delegated Graph API Permissions

Select the API Permissions option along the left-side menu, and then select 'Add a permission'.

Add API Permission

Choose Microsoft Graph from the Request API Permissions pane that opens at right.

Graph API Permissions

Click Delegated permissions, then search for and check off the following permissions:

Channel.ReadBasic.All
ChannelMessage.Send
Directory.Read.All
Group.Read.All
User.Read

Once you have selected the above-listed permissions in the Request API permissions pane, click Add Permissions.

Once added, you should see the above-listed Graph API delegated permissions appear in the list of configured permissions shown in the API Permissions view of your Azure app registration.

If you have the ability to do so, select 'Grant admin consent for <Tenant Name>', just above the table of API permissions, as shown in the API Permissions view of your Azure app registration. Granting admin consent to your Azure app registration from Azure Portal will remove the need to do so in FME Workbench.

Now your multitenant Azure app registration is complete, and you can proceed with Part 2, below.

Part 2: Configure the Web Service and Connection in FME Form

The Microsoft Teams (Graph) web service must be downloaded and installed to FME Form, and then correctly configured before the needed web connection can be created. Please follow these steps to configure the required web service.

1. Download and Install the Microsoft Teams (Graph) Web Service

In FME Workbench, navigate to Tools > FME Options > Web Connections > Manage Services. In the Manage Web Services dialog that opens, scroll down through the list of web services shown in the left-side pane to find the downloadable Microsoft Teams (Graph) web service. Highlight this web service, and then choose Download in the right-side pane to download and install it to FME Form.

Users who are not able to download the web service from within FME Workbench can download the needed Microsoft Teams (Graph) web service (.xml file) directly from FME Hub. Then, with the downloaded .xml file in hand, users can import the web service in FME Workbench via the Manage Web Services dialog by selecting the plus (+) button below the list of web services, and then choosing the Import option presented.

In the Web Service File to Import dialog that opens, use the ellipses to the right of the File To Import parameter to the downloaded .xml file, and choose Open, and then OK. The Microsoft Teams (Graph) web service will be added to the list of available web services in the Manage Web Services dialog.

2. Directly Edit the Downloaded Microsoft Teams (Graph) Web Service

Once the Microsoft Teams (Graph) web service has installed, select it from the list of web services shown in the Manage Web Services dialog. Its definition will appear in the right-side pane of the Manage Web Services dialog. Users must directly edit this definition; this web service will not show up as an option when selecting the plus (+) button > Create From menu (shown in the below image), unlike other Microsoft Graph-based web services.

Make sure you have the Application (client) ID value obtained from Part 1 - Step 2 above on hand. In the Microsoft Teams (Graph) web service definition that appears in the right-side pane of the Manage Web Services dialog, please make the following adjustments, ensuring no leading or trailing whitespace is included where values are copied:

Web Service Name: Leave as-is. Changing the default web service name will render the follow-up web connection undiscoverable by the MicrosoftTeamsConnector.
Client ID: enter the Application (client) ID value obtained from Part 1 - Step 2, above
Client Secret: leave this value completely blank, and marked as Optional / Not Required
Redirect URI: https://login.microsoftonline.com/common/oauth2/nativeclient
Authorization Parameters URL
- delete the value shown, and then copy-paste the following URL into the text box:

https://login.microsoftonline.com/common/oauth2/v2.0/authorize?response_type=code&scope=https://graph.microsoft.com/.default offline_access&prompt=select_account

Retrieve Token Parameters URL: ensure the value shown is as follows:

 https://login.microsoftonline.com/common/oauth2/v2.0/token

Retrieve Token Parameters Request Format: ensure the value shown is as follows:

code=[CODE]&client_id=[CLIENT_ID]&client_secret=[CLIENT_SECRET]&redirect_uri=[REDIRECT_URI]&grant_type=authorization_code

Refresh Token Parameters URL: ensure the value shown is as follows:

https://login.microsoftonline.com/common/oauth2/v2.0/token

Refresh Token Parameters Request Format: ensure the value shown is as follows:

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

If any values on the downloaded web service differ from those values displayed above, copy-paste the relevant value(s) into the appropriate web service text box(es), being sure to check for leading and trailing whitespace after pasting each value. Errors will occur if any leading or trailing whitespace is left behind in the various text boxes of the web service definition.

When all of the above adjustments are complete, the Microsoft Teams (Graph) web service definition should look like the following:

Click Apply at the bottom-right of the web service definition to save this configuration.

It's important to ensure that the web service's Redirect URI value exactly matches the redirect URI of the Mobile and Desktop applications platform of the Azure app registration, as displayed in Part 1 - Step 3 above. If these two values do not match, the web service will not function correctly.

If you have already granted admin consent to the Azure app registration in Azure Portal, or your Azure Admin has granted consent to the app registration, you can change the &prompt portion of the web service's Authorization URL to &prompt=select_account or &prompt=login to avoid being prompted to grant consent in FME.

3. Test the New Web Service

Select the Test option, just above Apply, at bottom right of the web service definition. When prompted, enter your Microsoft user credentials. If Microsoft prompts you to grant consent to the Azure app registration, click Accept.

If this web service test is successful, the following dialog will appear:

Once the web service has tested successfully, you can create the web connection. Close the Manage Web Services dialog to return to the Web Connections menu of FME Options.

The Microsoft user account used for authenticating the web service must have access to the target Teams resources you wish to work with in FME. If your Microsoft user account does not provide access to the target Teams resources, FME will not be able to access the resources.

4. Create the Web Connection

From the Web Connections menu, click the plus (+) button below the Connections table and choose to Add a new web connection.

Choose the Microsoft Teams (Graph) web service you just configured and tested above. Give the web connection a unique name. Click OK in the Edit Web Connection dialog. You will be prompted again to authenticate with Microsoft.