Microsoft Exchange Connections- Graph API

Who does this article benefit?

This article benefits IT and Cirrus Insight Admins for Office 365 organizations. It is primarily intended for organizations that currently use Exchange connections, whether they be User or Service Account connections. It is also beneficial to organizations using Office 365 connections as they can switch to Microsoft’s latest API for interacting with Office 365 data along with many new APIs that are available with Graph API.

What has Changed?

Microsoft has begun the process of disabling Basic Authentication (username/password) for Exchange Web Service connections. This change does not affect any on-premise Exchange organization. The exception would be organizations with a Hybrid Exchange setup. Based on information from Microsoft, the original date to disable Basic Authentication of October 2020 has been pushed to the second half of 2021. According to the articles, Office 365 tenants that are actively using Basic Authentication will be able to continue doing so until that 2021 deadline. More information can be found in the articles linked below.

 

Impacted Organizations and Users

Any Organization or User that currently uses an EWS (Exchange Web Services) connection for Sync or Calendar Scheduling. This includes both Service Account and User connections.

Switching to Graph API also provides more granular control over the permissions allowed for both a Service Account or User connection. It is no longer all or nothing as previously with EWS.

Switching to Graph API

By default, Microsoft or Office 365 connections use the Office 365 API. Graph API support must be enabled by Cirrus Insight support. Once it is enabled, simply follow the steps below to switch to Graph API.

User Connections

Step 1 is to disconnect their Exchange connection by clicking the red ‘Disconnect’ button.

Manage mailbox and salesforce connections

Step 2 is to create a new Office 365 connection by clicking the ‘Connect your Office 365’ button.

Email connections

Step 3 is to complete the login process and grant Cirrus Insight permissions to access your data.

Pick an account

Service Account Connections

Azure Service Account Setup

Log into the Azure Portal

Select the ‘Azure Active Directory’ option from the dropdown menu

Azure Active Directory

or from the Azure Services list on the start page

Azure Active Directory

Select the ‘App registrations’ option under the ‘Manage’ section

Mange App Registrations

Click the ‘New registration’ option

New Registration

The ‘Register an application’ form will display.

Enter a value for the Name field, ex: Cirrus Insight Service Account

For ‘Supported account types’ select the ‘Accounts in this organizational directory only (Single tenant) option

You can leave the ‘Redirect URI’ value blank.

Register the application

Click the ‘Register’ button.

This will take you to the management screen for the newly created App Registration.

In the ‘Essentials’ header at the top, you will see a value for ‘Application (client) ID’. This value will be used to configure the Service Account in the Cirrus Insight Dashboard. The value created for your App Registration will be different than the one shown in the example below.

Essentials

Select the ‘Certificates & secrets’ option in the ‘Manage’ section

Certificates and Secrets

manage Branding

In the ‘Client secrets’ section click the ‘New client secret’ option

New Client secret

Client secrets

In the ‘Add a client secret’ dialog enter a value for Description and select an option for the Expires value.

Add a client secret

The newly created Client Secret should now display in the list. Copy this value and save it in a secure manner as you would any other password. You will not be able to retrieve it later. The secret value will be used to configure the Service Account in the Cirrus Insight Dashboard. The value is randomly generated and will be different from the example shown below.

Client Secret

Select the ‘API permission’ option in the ‘Manage’ section

API Permissions

On the ‘Configure permissions’ page, select the ‘Add a permission’ option.

Configure Permissions

Click the ‘Microsoft Graph’ option

Request APi permissions

Click the ‘Application permissions’ option

Application Permissions

Select the Calendars.Read and Calendars.ReadWrite permissions under the Calendars section.

Calendar Sync

Select the Mail.Read and Mail.ReadWrite permissions under the Mail section.

 Permissions required by feature:
Calendar Scheduling requires all 4 of the permissions above. Calendar Sync requires just the Calendars permissions, and Email Sync requires just the Mail permissions. Task Sync is not currently supported via Service Account as there are no Graph API permissions for Tasks (Outlook Tasks).

Click the ‘Add permissions’ button at the bottom of the dialog.

The newly added permissions will be shown in the list. The Status will show as ‘Not granted for <your tenant>’

To grant permissions click the ‘Grant admin consent for <your tenant>’ option.

Grant Access

The permission status column should now be updated and the Cirrus Insight Service Account will be able to access the user data.

Cirrus Insight Service Account

Configuring the Cirrus Insight Service Account

Log into the Cirrus Insight Dashboard

Switch to the ‘Admin’ profile

Under the ‘My Organization’ => ‘Authentication’ section click the ‘Service Accounts’ option.

The Service Accounts list will be displayed. Click the ‘Add’ option at the bottom.

In the Service Accounts side panel select the ‘Connect using Office 365’ option.

In the Service Accounts side panel complete the Service Account configuration using the Client Id and Client Secret configured previously.

The ‘Test Account’ value is used to verify the Service Account has the appropriate permissions configured. Click the ‘Run Test’ option to verify. Click ‘Save’ to save the Service Account configuration.

The Office 365 Service Account will now be displayed in the Service Accounts list as shown below.

Limiting Service Account Access

The users a Service Account has access to can be limited using an Application Access Policy and a Mail Enabled Security Group.