Interact Marketplace integration for Microsoft 365, allows for connectivity with the following services:

• Exchange Online
• Teams
• SharePoint Online
• OneDrive
• Calendar
• Tasks

Interact utilizes the Microsoft Graph API, and Sharepoint Search REST API to interface with the Microsoft 365 ecosystem.

Overview

You will need to do the following activities:

• Setup a new App Registration
• Gather the following information: Application (client) ID, Directory (tenant) ID, and Client Secret value.
• Give necessary API permissions based on your intended usage of Marketplace functionality

Creating an Azure App Registration

1. Go to Azure Portal -> Azure Active Directory -> App Registrations https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps

2. Create a New registration.

• Provide a name for your registration
• Scroll down to the Redirect URI section and add your Redirect URI. The Redirect URI needs to be in the following format:
  Redirect: https://{intranet-domain}/marketplace/microsoft/account/sign-in/oauth2
  eg.
  Redirect: https://intranet.acme.com/marketplace/microsoft/account/sign-in/oauth2

3. Copy the Application (client) ID, and Directory (tenant) ID values from the application screen.

You will need the Application (client) ID value for a 2nd Redirect URI that will take the following format:
Redirect: https://intranet.acme.com/microsoftGraph/signin-oidc-{application-id}
eg.
Redirect: https://intranet.acme.com/microsoftGraph/signin-oidc-07a36512-ec60-495f-948a-829b0db4e340

4. Click on Redirect URIs.

5. Enter the 2nd Redirect URI, which as mentioned above should appear in the following format:

Redirect: https://intranet.acme.com/microsoftGraph/signin-oidc-{application-id}
eg.
Redirect: https://intranet.acme.com/microsoftGraph/signin-oidc-07a36512-ec60-495f-948a-829b0db4e340

• Make sure ID Tokens checkbox is checked for implicit and hybrid flows;
• Click 'Save'

6. Create a Client Secret.

• Navigate to 'Certificates and Secrets';
• Add a New Client Secret, including a brief description of your choice;
• Click 'Add';
• Make a note of the client value for later.

7. You should now have the following information:

• Application (client) ID
• Directory (tenant) ID
• Client secret value

The setup is now complete - we will return here to add the necessary scopes, once we have configured the Interact Marketplace settings.

🚧

Redirect URLs are Case Sensitive and Whitespace Sensitive

Please make sure the casing matches precisely what is documented here, and remove any trailing and leading whitespace.

Configuring Interact Marketplace

1. From Application Settings > Control Panel > Marketplace, select Microsoft 365
2. Specify the Client ID, Client Secret, and Authority from the Azure App Registration.
   2.1. Client ID <- Application (client) ID
   2.2. Client Secret <- Client secret value
   2.3. SharePoint Instance (optional) <- If you want to utilize SharePoint Search REST API, you will need to supply the SharePoint Instance value that looks like this: https://acme.sharepoint.com/
   2.4. Authority <- The the Directory (tenant) ID and paste it into the following format: https://login.microsoftonline.com/{directory-tenant-id}/
   eg. https://login.microsoftonline.com/38dad1b5-6969-4cd2-8f94-24f8c4c9baca/
3. Under Integration Options select the features you want to use.
   3.1. Necessary API scopes will be listed - take a copy of this list as the scopes need adding back to the Azure App Registration (bad configuration of scopes, will result in an AADSTS65001 error.)
4. If planning to use the Sharepoint One Search Connector or Exchange Online , you must enable Sharepoint and Outlook in Application Settings > Control Panel > Manage Application Variables > Integrations.
5. Click Save.

❗️

Editing Marketplace Configuration

The editing of existing Marketplace Configuration options (including Integration Options for Microsoft 365), will forcibly purge authentication tokens of all users who have used the integration. Therefore requiring them to re-authenticate before being able to use the integration again, any scope changes will be immediately applied to the new access tokens (existing service provider access tokens won't automatically pick up changes until re-authentication.)

App Registration Permission Scopes

The list of usable scopes is shown below. Depending on your selected *Integration Options on the Marketplace Configuration page, the required scopes will differ to only request what is needed (the least privilege principle.)

Application Settings > Control Panel > Marketplace, select Microsoft 365, you can see which scopes are required for each M365 integration.

Microsoft Graph API Permission Scopes

Sharepoint API Permission Scopes

Admin Consent

Interact Marketplace supports admin consented permissions instead of user authorization. It is therefore important to grant admin consent to the added permission scopes.

(NOTE: This screenshot shows scopes for a fully configured Microsoft 365 Integration for Interact Marketplace - your scopes will vary based on your selected *Integration Options.)

1. Click Grant admin consent

2. If successful, you will now be able to use the Microsoft 365 widgets, and search integrations in your Interact intranet.

SharePoint Search REST API

When you query in the context of a SharePoint Online user, you get results from:

• Content in SharePoint Online site collections
• Content in Microsoft 365 groups
• Shared OneDrive for Business content (content that's accessible for others than the owner of the OneDrive for Business)
• Content from SharePoint Server that's been indexed via a cloud search Service application (Cloud Hybrid Search)

https://docs.microsoft.com/en-us/sharepoint/dev/general-development/sharepoint-search-rest-api-overview

Guidance

• Interact Marketplace Configuration page will allow for in-depth configuration of the desired functionality and will provide a list of the required API Permissions for the App Registration. This allows for the least-privilege principle to be applied during the configuration.
• Microsoft Graph API may enforce Rate Limits to their APIs. These are outside the control of Interact and we do not currently apply API monitoring or capping in connection with third-party services. More information can be found here https://docs.microsoft.com/en-us/graph/throttling#service-specific-limits
• Errors from Microsoft Graph API will be displayed in the widgets to aid with troubleshooting and will be recorded in the Marketplace Logs.
• Errors in the following format AADSTS65001, are errors returned directly from the Microsoft Graph API. Please refer to the Microsoft documentation to troubleshoot - https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-aadsts-error-codes
• Teams channel widget will poll the Graph APIs every 20 seconds to retrieve updates for the specific channel. If a browser tab becomes inactive it will continue to poll.
• Microsoft 365 Marketplace integrations do not support user authorization - all permission scopes must receive admin consent.
• Seamless Graph API login can be achieved when using Azure AD SAML SSO, combined with Microsoft 365 Marketplace Integration. Please follow this guide for more information Interact Software Auto Login to Microsoft Graph API for Microsoft 365.
• App Registration Scopes listed on the Marketplace Configuration page, will be requested for authorization at the time of user login - any scopes granted in the App Registration Portal after the user is authentication, will not be applied until the user re-authenticates. We strongly recommend resaving your Marketplace Configuration to purge all sessions if you are changing the App Registration scopes.
• You may experience delays when removing/revoking permissions in App Registration API Permissions panel. These delays are outside of Interact's control. Active access tokens and refresh tokens may continue to work, for a period of time, even after permissions are revoked, or even after the Azure Application is deleted. To immediately remove access, Clear the Microsoft 365 configuration on the Marketplace Configuration page.
• Microsoft may implicitly grant other permissions which are added to the App Registration and have received admin consent. eg. If Marketplace is requesting openid, profile and Calendars.Read, but the App Registration also has Sites.Read.All and Directory.ReadWrite, then the user will implicitly receive access to all 5 scopes, not just the 3 requested.
• Some scopes like Calendar.Read are not automatically granted by the virtue of having a greater permission scope granted such as Calendar.ReadWrite or Group.ReadWrite.All in the App Registration. If Calendar.Read or Group.Read.All is the Marketplace Configuration list, it must be in the App Registration scopes exactly as listed on the Marketplace Configuration list.
• Cross-geolocation usage on M365 tenant geolocation may add a measurable impact on the response times of API usage-heavy widgets, like the Teams widget.
  • eg. an M365 tenant located in Europe, being used on an Interact site hosted out of North America, will have the added latency of traversing this geographical distance, for every API call. Most integrations are light and rely on a handful of API calls, but a rich widget like Teams, requires 100s of graph traversals (API calls) to occur to stitch the conversation context together and will experience this latency overhead very clearly, as each API call, needs to travel this geographical distance and back, before the next can take place. It is therefore important to keep the M365 tenant geolocation and Interact site geolocation in mind.
  • The impact of this may be reduced by adjusting the Teams widget settings to shorten the date range, adjust the refresh rate, etc.

Common Graph API Errors