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 describes the API for integrating Microsoft 365 within a custom application.
If you want to integrate Microsoft 365 with the Home component of OpenFin Workspace, see Home search with Microsoft 365.
Prerequisites
-
OpenFin
- Minimum recommended runtime version 20.91.64.3
-
A Microsoft 365 subscription
- Account with at least the Application Administrator role is needed to register your application in the Entra ID admin center
-
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 Microsoft Entra ID admin center
-
Go to the Microsoft Entra admin center (previously, Azure Active Directory portal); if applicable, select the Microsoft Entra tenant for your app; then select Identity > Applications > App registrations and create a new registration for your app. For details, see the Microsoft documentation on registering an application.
-
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
.
-
-
-
(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
-
-
If you have specified app permissions, select Grant admin consent for at the top of the list of permissions, and confirm.
-
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 Microsoft Entra admin center. -
REGISTERED_APP_TENANT_ID
: replace with the Directory (tenant) ID that was provided when you registered your app in the Microsoft Entra admin center. -
REGISTERED_APP_REDIRECT_URI
: replace with the Redirect URI that you provided when you registered your app with in the Microsoft Entra admin center. -
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 toexecuteApiRequest
. -
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 toexecuteApiRequest
, 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 3 months ago