Integrating with Microsoft 365 using OAuth

Owned by Ryan Clifton
Last updated: Sept 12, 2024 by Mike Harrison
5 min read

A simple and secure way to authenticate JEMHC’s use of your Microsoft 365 mailboxes is via OAuth.

Prerequisite setup in Azure Portal

As an Azure admin, ensure that users of JEMHC can request permissions via Microsoft Azure > Enterprise Applications > User settings. You will also need identify Users/Groups/Roles who will authorize admin consent requests from users configuring JEMHC.

Registration of JEMHC in your domain

Automatic registration through JEMHC authentication

Registration is automatic when a domain admin account is used in JEMHC incoming/outgoing mail connections through the “Sign in with Microsoft Button”:

On successful authentication, the JEMHC app registration will be made, here you can see 08b9fc2c-f6b8-4da0-8d4d-c065edfa949b is the ID of the application

 

It is now possible to delete the Message Source / Message Outbound in JEMHC using the Domain Admin account, and supply instead the mailbox user account, using the ‘play’ icon to validate the connection:

Manual registration before JEMHC authentication

JEMHC registration must strictly follow the specified method outlined above. This application is not intended for end-users and is consequently excluded from the 'app gallery'.

Managing permission consents

In order for JEMHC to access your mail accounts, it needs specific permissions. These permissions are delegated type permissions, meaning that JEMHC is delegated with the permission to act as a signed-in user when it interacts with mail accounts.

Consent can be granted to the app either by a single user (user consent) or for all users by an administrator (admin consent). See Managing app consent in Microsoft 365 for more information.

Creating a connection

The following can be done via the Message Sources or Message Outbounds page under the Messaging tab, depending on whether you want to process or send emails respectively.

  1. From the top right of the screen, select Create

  2. Click Sign in with Microsoft

  3. Select any optional permission scopes you want to grant to JEMH Cloud and click OK. If you are planning on using a shared mailbox, you’ll want to consent to the optional permission shown. See Using an Inbound shared mailbox for more information.

  4. At this point, you may be asked to grant consent to JEMHC acting on behalf of the signed in user. See the previous section on granting consent for more information.

  5. After granting consent to the request, a screen confirming successful authorization is shown:

  6. Returning to JEMHC, you should now see the new connection:

     

  7. Clicking the green ping icon will then test the connection. A successful test will look similar to this:

     

  8.  The mail connection is now ready for use. These steps are identical for setting up both Message Sources and Message Outbounds.

Connection types

There are currently 2 types of connection JEMHC can make with Microsoft 365. Graph API connections make use of the Microsoft Graph API in order to access resources. These are recommended, and the default when the “Sign in with Microsoft” button is used inside the JEMHC UI.

Before addition of Graph API connections, EWS API connections were used, but these are being phased out.

Common Problems

Our support does not cover third-party mail host configuration. We apologize for being unable to assist with in-depth analysis. The following aims to provide some guidance and steer you towards a resolution:

The provided grant has expired due to it being revoked, a fresh authentication token is needed

You may be notified of a Message Source being offline:

SimpleHttpClientException: EWS. invalid_grant - AADSTS50173: The provided grant has expired due to it being revoked, a fresh auth token is needed. The user might have changed or reset their password. The grant was issued on '2022-07-19T15:24:40.8668421Z' and the TokensValidFrom date (before which tokens are not valid) for this user is '2023-03-13T20:21:32.0000000Z'…

This typically means that the Authentication of the inbound Source has not been used for period of time, and has been revoked by the mail-host. A re-authentication step is required in the Incoming Mail Source to get a auth token.

Device object was not found in the tenant

SimpleHttpClientException: EWS. invalid_grant - AADSTS700003: Device object was not found in the tenant ….

The reason that the tokens are rejected is because the presence of the deviceId claim indicates a binding to that device and when this device is not found in the directory it indicates a revocation action where the device was deleted or disabled and tokens for that device will no longer be valid.

HttpErrorException: The remote server returned an error: (401)

Typically this means that the mail server is disallowing the use of the mailbox. As observed EWS Connection to Office365 fails - 401 Unauthorized it may be the case you need to request through your mail-host admin that the related mailbox to be specifically accessible for this app

Duplicate notifications

This issue stems from the communication flow between the Outbound Mail client requesting to send a mail using Microsoft Graph.

After sending the notification, we expect to receive either:

  • A 202 Accepted response, indicating the request was successful

  • A 429 Status Code, along with a Retry-After header indicating when the next request should be attempted.

We have (at the time of writing) an open ticket with Microsoft regarding the problem, that the request is returning a 202 Accepted response and a Retry-After header value. Due to this external bug, our solution has been to currently inhibit the retry attempts, as the initial request to send the mail is successful.