Microsoft 365 integration

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

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.

This article shows how to:

  • Configure authorization for your OpenFin app in the Microsoft Azure portal

  • Connect your OpenFin app to your Microsoft 365 instance

  • Make requests to the Microsoft Graph API

📘

Getting started

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

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 desktop application installed

Install

Add the @openfin/microsoft365 NPM package:

With npm:

npm -i @openfin/microsoft365

With yarn:

yarn add @openfin/microsoft365

Register your app in the Azure portal

  1. Go to the Microsoft Azure portal > (if applicable, the Azure AD tenant for your app) > 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 when you register, so that users do not have to accept them during authorization. In your completed registration, go to App permissions > Add a permission > Microsoft Graph > Delegated permissions, and select the following permissions:

    • User.ReadBasic.All

    • Team.ReadBasic.All

    • Channel.ReadBasic.All

    • ChannelMessage.Send

    • Chat.Create

    • ChatMessage.Send

    • offline_access

  4. Add any other permissions that your app requires.

  5. If you specify app permissions, select Grant admin consent for ... at the top of the list of permissions, and confirm.

  6. Make note of the following values to provide as parameters when you connect your app to Microsoft 365:

    • 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

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.

For more information and recommendations for handling authorization errors, see Working with OpenFin integrations and 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

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 GraphResult 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 executeApiRequest is unsuccessful, either because an HTTP status code indicated an error or because the request failed to be sent, an ApiRequestError error will be thrown that contains the following properties:

  • message: A detailed description of the error

  • status: The HTTP status code, if the request was received

Microsoft resources

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.

Microsoft also 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: 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));

Another example: 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();