Home search with Microsoft 365

In Workspace v13.1 or later, if your environment includes a Microsoft 365 subscription you can add a workflow integration that lets your users search Microsoft 365 tools and start appropriate actions directly from the Workspace Home component. Search results appear in a Home card. Users can filter by Microsoft product or by some card attributes. Which actions are available depends on which Microsoft tool appears in the card. For example, if the result is a contact, your user could start a Teams chat or call, or send an Outlook email. If it's a drive or a document, your user can open the web version of Office in Workspace Browser.

This article describes integrating Microsoft 365 with the Home component of Workspace, so that Microsoft items appear in Home search results.
If you want to integrate Microsoft 365 within your own application, see Microsoft 365 integration.

How it works

You register your Workspace Platform as an app with Microsoft Entra ID (formerly Azure Active Directory). When you register, you provide a redirect URI and Microsoft provides authorization config values you pass to the required properties of a Microsoft365ConnectionConfig object. These properties set up the OAuth connection with the Microsoft Graph API the integration calls under the hood. The connection object is a property of a Microsoft365IntegrationConfig object you create an instance of and pass to WorkspacePlatform.init. This is the minimal required setup.

The integration automatically calls Home.register and specifies the appropriate values for the onUserInput and onResultDispatch properties. When you create your Microsoft365IntegrationConfig instance you can optionally provide values for the other Home Provider properties. See the API reference for HomeProvider.

By default, all Microsoft 365 products are included in the integration, but you can exclude any of them. For details, see the API reference for the MicrosoftEntityTypeConfig object.

How to do it

Setting up the Home/Microsoft365 integration requires involvement of both an Entra ID administrator and an integration developer. In many organizations, these are not the same individual.

Prerequisites

• A Microsoft 365 subscription
• Microsoft Entra ID account with at least the Application Administrator role is needed to register your app with Microsoft

To support Microsoft Teams, one of the following:

• Install the Microsoft Teams application on all target desktops. Requires the openUrlWithBrowser permission enabled in your application manifest, with the msteams protocol specified. For more information, see API security.

• Have your users work in the browser-based version of Teams. Requires that you set the useTeamsDeepLink property of the MicrosoftSearchWorkflowConfig object to false. See the code example in this article for context for this setting.

You should also make sure correct email addresses are defined for your users in Entra ID. If an email address can't be resolved to an Entra ID user, the Microsoft Graph API does not throw an error.

Register your app with Microsoft (Entra ID admin)

1. Go to the Microsoft Entra ID admin center (formerly, Azure Active Directory portal), select the Entra ID tenant for your app.

2. Go to Identity > Applications > App registrations and create a new registration for your app.

3. Specify the following:

   • Single-page application (SPA) as the platform
   • For the Redirect URI value:
     • Specify HTTPS as the protocol, or for localhost values see the Microsoft documentation on localhost exceptions.
     • The origin must resolve to an existing server.
     • Include a path that resolves to an actual page, to avoid server redirects. The page can be blank because the required redirect happens rapidly after authorization.
     • Redirect URIs are case-sensitive.
     • We recommend a redirect URI such as APP_ORIGIN/oauth-redirect.html. Example: https://myapp.mydomain.com/oauth-redirect.html.

4. Make a note of the following values. The integration developer uses them to configure the Workspace Platform.

   • Application (client) ID
   • Directory (tenant) ID
   • Redirect URI

5. Go to App permissions > Add a permission > Microsoft Graph > Delegated permissions, and select the following permissions:

   • offline_access
   • Calendars.Read OR Calendars.ReadWrite
   • Channel.ReadBasic.All
   • ChannelMessage.Read.All
   • ChannelMessage.Send
   • Chat.Create
   • Chat.Read OR Chat.ReadWrite
   • ChatMessage.Send
   • Contacts.Read.Shared
   • Mail.ReadWrite.Shared
   • Presence.Read.All
   • Sites.Read.All OR Sites.ReadWrite.All
   • Team.ReadBasic.All
   • User.Read.All

Configure integration details and initialize your platform (integration developer)

When you configure your platform, you must specify the required values to pass to the connect method of the Microsoft365ConnectionConfig object. By default, all Microsoft 365 products are enabled, but you can also specify which products to disable if your environment requires it.

import { Home, Integrations } from `@openfin/workspace`;
import * as WorkspacePlatform from '@openfin/workspace-platform';

const config: Microsoft365IntegrationConfig = {

  // required. configures your app connection with the Microsoft Graph API
  connect: {
    // these values are taken from your app registration with Azure AD
    clientId: 'REGISTERED_APP_CLIENT_ID',
    tenantId: 'REGISTERED_APP_TENANT_ID',
    redirectUri: 'REGISTERED_APP_REDIRECT_URI'
  },

  // optional, to override default values
  workflows: {
   
   search: {
      // optional. Lets you configure your Home Provider as part of the integration
      // and specify any custom values you might need.
      homeProvider: {
        // for example, to specify your own icon instead of the default Microsoft icon:
        icon: 'ICON_URL',
        // to provide your own title that appears in the Home UI for this provider
        title: 'CUSTOM_TITLE_IN_HOME'
      },
      
      // optional. All Microsoft 365 products are enabled by default. 
      microsoftEntityTypeConfig: {
        // exclude OneDrive Files from search results in Home
        drive: false,
        // exclude Sharepoint Lists
        list: false
      }

      // if your users do not have the Microsoft Teams app installed on their desktops
      // but are allowed to run Teams in the browser
      useTeamsDeepLink: false
    }
  }
};

const microsoft365WorkflowIntegration = new Microsoft365WorkflowIntegration(config);

// initialize platform and include Microsoft 365 integration
await WorkspacePlatform.init({
  browser: {},
  integrations: [microsoft365WorkflowIntegration],
});

// Home is hidden by default, so explicitly show it
await Home.show();

Make sure to provide your own values for the following:

• REGISTERED_APP_CLIENT_ID: replace with the Application (client) ID that was provided when you registered your app in the Entra ID admin center.
• REGISTERED_APP_TENANT_ID: replace with the Directory (tenant) ID that was provided when you registered your app in the Entra ID admin center.
• REGISTERED_APP_REDIRECT_URI: replace with the Redirect URI that you provided when you registered your app with in the Entra ID admin center.

See also Working with Microsoft authorization, which describes how OpenFin handles these values.