Working with OpenFin integrations and Microsoft authorization

Your OpenFin integration with Microsoft 365 depends on authorizing your app to make requests to the Microsoft Graph API. Microsoft Azure Active Directory implements the OAuth 2.0 specification for authorization. This page explains how it works, how OpenFin secures the authorization flow for your app, and what your app must provide to support authorization.

OpenFin's Microsoft 365 integration implements the PKCE flow (Proof Key for Code Exchange, pronounced "pixy"). This flow provides secure authorization without needing to expose a sensitive client secret to insecure clients. To guard against potential XSS vulnerabilities, OpenFin's integration includes a web worker that handles authorization tokens and remote requests that involve tokens.

📘

About web workers

Web workers are essentially background threads — that is, they run in a context that is different from the parent app’s thread. This means the code running in the parent app cannot access code running in the web worker and vice versa. The only way a web worker and the parent app communicate is by exchanging messages, and if the web worker never leaks tokens through messages, we can consider the tokens secure from XSS.

For more information, see the Microsoft documentation on Microsoft identity platform and OAuth 2.0 authorization code flow and the IETF standard for PKCE.

How it works with your app

Whenever the connect function is called from the Microsoft 365 integration API, a child window is created that navigates to the Microsoft authorization endpoint that starts the OAuth flow. This window might be displayed if any of the following is true:

  • The user is not authenticated against your app's Azure Active Directory tenant

  • Your app is not already authorized to use any of the permissions it is requesting, by the user or by a tenant admin

  • An invalid parameter was passed to the authorization flow, or some other authorization error occurred

Assuming appropriate authentication and permissions authorization, Microsoft sends an authorization code, which is exchanged for an access token and a refresh token. Finally, the promise returned by the connect function resolves with a Microsoft365Connection object.

Token lifetimes

Access tokens are typically valid for only 60-90 minutes, while refresh tokens are valid for 24 hours for single page apps. See the Microsoft documentation on token lifetimes for more information.

Handle token expiration

If the current access token expires when making a Graph REST API request, the API automatically requests a new access token using the refresh token stored in memory. If this fails (for example, if the refresh token has expired), then a AuthTokenExpiredError is thrown and the connect function must be called again to re-start the authorization flow.

You should always catch errors thrown by executeApiRequest and check to see whether the error is an AuthTokenExpiredError. That way you can handle re-connection in the most ideal way for your users and particular environment configuration:

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

try {
  const response = await ms365Connection.executeApiRequest<Graph.Chat[]>('/v1.0/me/chats');
} catch (err) {
  if (err instanceof AuthTokenExpiredError) {
    // Need to reconnect...
  }
}