AboutSupport

Microsoft 365 integration

Integrate your OpenFin solution with the apps, services, and data that form the Microsoft 365 platform.

Suggest Edits

OpenFin provides an API to help simplify connecting your OpenFin app with Microsoft 365. The API integrates with the Microsoft Graph API via OAuth 2.0 to provide secure interoperability between an OpenFin app and the apps, services and data that form the Microsoft 365 platform.

Prerequisites

  • OpenFin

    • Minimum recommended runtime version 20.91.64.3

  • A Microsoft 365 subscription

  • To support Teams-specific features of the API, the Microsoft Teams application must be installed on all target desktops

Installation

Add the @openfin/microsoft365 NPM package as a dependency for your app:

npm install @openfin/microsoft365

Configuration

Register your app in the Azure portal

  1. Go to the Microsoft Azure portal; if applicable, select the Azure AD tenant for your app; then select Azure Active Directory > App registrations and create a new registration for your app. For details, see the Microsoft documentation on registering an application.

  2. 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 so 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.

  3. (Optional) We recommend that you specify the required app permissions in the app registration so that each user does not have to authorize them themselves during authorization. Go to App permissions > Add a permission > Microsoft Graph > Delegated permissions, and select the following permissions as a minimum, adding any other permissions that your app requires:

    • User.ReadBasic.All

    • Team.ReadBasic.All

    • Channel.ReadBasic.All

    • ChannelMessage.Send

    • Chat.Create

    • ChatMessage.Send

    • offline_access

  4. If you have specified app permissions, select Grant admin consent for at the top of the list of permissions, and confirm.

  5. Make a note of the following values to use with the Microsoft 365 integration API:

    • Application (client) ID

    • Directory (tenant) ID

    • Redirect URI

    • Any permissions unique to your app -- that is, in addition to the required app permissions listed above

Usage

📘

Note

Take a look at the basic and advanced starter projects for help getting started with OpenFin’s Microsoft 365 integration.",

Connect your OpenFin app to Microsoft 365

Call the connect function to begin the authorization flow needed to connect your app to Microsoft 365:

import { connect } from '@openfin/microsoft365';

const clientId = 'REGISTERED_APP_CLIENT_ID';
const tenantId = 'REGISTERED_APP_TENANT_ID';
const redirectUri = 'REGISTERED_APP_REDIRECT_URI';
const additionalPermissions = []; // Optional, e.g. ['Mail.ReadBasic', ...]

const ms365Connection = await connect(clientId, tenantId, redirectUri, additionalPermissions);
console.log('I am connected as ', ms365Connection.currentUser.displayName);

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 Azure portal.

  • REGISTERED_APP_TENANT_ID: replace with the Directory (tenant) ID that was provided when you registered your app in the Azure portal.

  • REGISTERED_APP_REDIRECT_URI: replace with the Redirect URI that you provided when you registered your app with in the Azure portal.

  • If your app requires additional permissions beyond what the OpenFin integration includes, specify them as values in the additionalPermissions array.

📘

Note

For more information and recommendations for handling authorization errors, see Working with Microsoft authorization.

The function returns a Promise that is resolved with a Microsoft365Connection object when authorization succeeds. You work with this object to make requests to the Graph API.

Making requests to the Graph API

📘

Note

Familiarize yourself with the Microsoft Graph API.

The Microsoft Graph API is large and complex, and can be difficult to navigate.
We recommend Microsoft's Graph Explorer tool to help find the right endpoints and understand response data.

You can make requests to Microsoft Graph with the executeApiRequest function of the Microsoft365Connection object:

import * as Graph from '@microsoft/microsoft-graph-types';

const response = await ms365Connection.executeApiRequest<Graph.User>('/v1.0/me');
const { data: currentUser } = response;
console.log(`My name is ${currentUser?.displayName}`);

Note that you need to provide only the relative path for the Graph API endpoint you are requesting, starting with the appropriate API version. The function accepts an optional type variable describing the requested data, ensuring static typing for the response data.

The function returns a Promise that resolves to a GraphResponse object that includes the following properties:

  • data: The data that was requested for the specified API resource, if relevant. The type is determined by the optional generic type variable passed to executeApiRequest.

  • status: The HTTP status code for the response.

  • type: The content type of the response data, if relevant.

If the request is unsuccessful, either because the HTTP response status code indicated an error or because the request failed to be sent, the Promise rejects with an ApiRequestError that contains the following properties:

  • data: The original error object returned from the Graph API (if the request was received)

  • message: A detailed description of the error

  • status: The HTTP response status code (if the request was received)

📘

Note

Microsoft provides an NPM package, @microsoft/microsoft-graph-types that contains most response types returned by Graph API endpoints. We recommend using this package to provide the correct type variables to executeApiRequest, to ensure proper static typing for response data when making Graph API requests.

Example Graph API requests

Retrieve a user's Teams chat conversations

This example shows how you can retrieve all chats for the current logged-in user.

import * as Graph from '@microsoft/microsoft-graph-types';

const chatsResponse = await ms365Connection.executeApiRequest<Graph.Chat[]>('/v1.0/me/chats');
const { data: chats } = chatsResponse;
chats?.forEach((chat) => console.log(chat.id, chat.topic));

Retrieve a user photo

This example shows how to retrieve and process binary data from the Graph API, in this case the current user's profile photo.

const photoResponse = await ms365Connection.executeApiRequest<ArrayBuffer>('/v1.0/me/photo/$value');
const { data: photo, type } = photoResponse;
const photoBlob = new Blob([photo!], { type });
const reader = new FileReader();
reader.onloadend = () => console.log(reader.result as string);
reader.readAsDataURL(photoBlob);

Disconnect from Microsoft 365

Call disconnect to terminate the connection to Microsoft 365 and clean up utilized resources:

await ms365Connection.disconnect();

Updated 5 months ago