Graph Notification Broker¶

Exec Summary¶

MS Graph provides an easy way to access the data in Microsoft 365, including information about users, documents, meetings, and more. When data changes, applications need timely notifications. For example, a chat application needs to know when someone is available or out of the office. This asset simplifies the development complexity through immediate notice of Graph changes.

Graph Notification Broker (GNB) enables apps to receive change notifications from MS Graph in real time without the application having to poll. To ensure timely delivery of notifications, GNB offers a pub-sub service that reduces the load on Graph API. It further provides for automatic renewal of the subscription to notifications. GNB works even when the apps are behind a private network.

Business Use Case¶

Collaborative applications require notifications on changes in Microsoft 365 entities. Examples include:

• The arrival of an email,
• A reply on a chat,
• A change in "presence" of a user
• A change to a document.
• The change of a calendar item.

A full list of resources that support notifications is provided here.

Notifications enable applications to react to remote state changes. Following are some important considerations in design.

1. Change notifications sent by Graph via webhooks. Many large enterprises block the inbound traffic for security reasons, which limits the ability for the webhook to reach its endpoint.
2. Change notifications have limited lifetime and need to be renewed before they expire. Many background business processes that need to subscribe to changes typically run longer than the lifetime of a subscription.
3. Many applications used polling to detect changes, so the Graph API throttles clients to protect itself from a torrent of requests. Using notifications instead of polling and sharing notifications between clients reduces the number of calls to Graph API and reduces the risk of throttling.

Traverse Restricted inbound http traffic¶

The Microsoft Graph allows third-party applications to subscribe to Office 365 activity through change notifications. When first introduced, change notifications relied on a webhook reachable by the Microsoft Graph. Webhooks require ingress to an organization's network, however, so they were often not usable. An approach is required where incoming webhooks can traverse inbound network policies that prevent inbound http traffic.

Subscription lifetime management¶

A subscription has a limited lifetime and the client that creates is responsible for renewing it before it expires. Renewal is a complex task where limited solution patterns exist. A reusable solution or pattern is required that manages and renews subscriptions on behalf of the client.

Reduce load on Graph and enable real-time notifications¶

Due to the complexity in managing subscriptions, applications that use graph change notifications often use a polling strategy. Frequent polling can increase load on Graph API substantially. A pub-sub solution will reduce this load and allow multiple applications to use the same notification real time.

Related Industry Patterns¶

This pattern is not limited to any particular industry but has proven useful in sectors like Financial Services, Healthcare, and the public sector, where strict information security policies are essential.

Description¶

The sample code manages notification subscriptions and processing. It uses Azure Functions, Azure Tables, Event Hub, Event Grid and SignalR.

Repository Location¶

Code available in repository. You can find samples in the Graph Notification Samples repo. This repo contains components and sample applications.

1. One Single Page Application (SPA) based on JavaScript that contains a component that can easily be re-used in other applications.
2. A Power Apps Component Framework (PCF) solution that contains a PowerApps component allows easy integration of the Graph Notification Broker in PowerApp Applications.
3. Sample Power App Applications that use the Power App PCF component to show integration with Chat, Calendar, and Presence Notifications.

Related Technologies¶

• Microsoft Graph
• Azure Event Hubs
• Azure Functions
• Azure Cache for Redis
• Azure KeyVault

Architecture¶

Below is a schema of a proposed architecture of the Graph Notification Broker.

• The solution can be used by any type of application that can send out HTTP request and use SignalR. A Client application is typically a Single Page Application (SPA) or WebApplication. The client uses a SignalR hub to receive notifications to update the interface.
• A Client will request a subscription to a Microsoft 365 entity with a call to the Subscription function. That function will create the subscription with Graph API and administer the request into the Subscription Ledger and returns subscription ID via SignalR.
• Clients check their internal subscription ledger for subscriptions that are almost expiring. For each of them, it will call the Subscription Function to renew the subscription. When the subscription is renewed, it will return the result to all clients that are subscribed to that resource. Each client can reset its UI and timer based on the response.
• When an event happens in Microsoft 365, it sends change notifications to Azure Event Hub. EventHub allows crossing network policies that prevent inbound http traffic as described in the Get Change Notification documentation.
• An Azure Function is triggered when notifications arrive in Event Hub. The function processes the event and forwards it to the correct clients via SignalR.

Security Architecture¶

1. The Clients communicate with Azure Functions and the SignalR Service. This communication is secured by use of a Bearer token that the client needs to obtain from Azure AD.
2. The secrets to obtain an access-token will be stored in Azure Key Vault.
3. The Functions communicate with the Microsoft Graph API, and will secure this using an Azure AD Bearer token with application permissions. The required secrets to obtain an access token will be stored in an Azure Key Vault.
4. The Graph API sends change notifications to Azure Event Hub. The required connection string is stored in Azure Key Vault, and the Graph API that runs as "Microsoft Graph Change Tracking" reads the secret. For more information, see: Configuring the Azure Key Vault.
5. The Event Function needs to have a trigger to Event Hub. The function will run under a managed identity that has read access on the Event Hub. For more information, see Identity-based connections.
6. A certificate is created and stored in Key Vault. Notification data is decrypted using the certificate.
7. The Subscription and Decrypt functions need access to the certificate's private key, so the notification function requires read access to the Key Vault instance.

Deployment architecture¶

The application will be deployed as multiple components.

1. Azure Functions
2. Azure AD App Registrations
3. Azure Event Hub
4. Azure KeyVault
5. Azure SignalR Service
6. Azure Cache for Redis

The deployment is automated using a script designed to deploy into an Azure Tenant of a customer. The script will create all the services required.