OAuth Authentication for Microsoft Office 365 Email

When connecting EQuIS Enterprise to Microsoft Office 365 for incoming and outgoing email, EarthSoft recommends using OAuth instead of basic authentication. (See this Microsoft blog post for more information about OAuth versus basic authentication in Office 365.)

Before configuring EQuIS Enterprise with OAuth authentication for email, please note the following:

•Using OAuth authentication for email currently only works for Microsoft Office 365; it is not yet supported for other email providers.

•For POP and SSL Port should be 995.

•For IMAP and SSL Port should be 993.

•Port settings should be configured to your email provider. For additional information, see the following document:
https://support.microsoft.com/en-us/office/pop-imap-and-stmp-settings-8361e398-8af4-4e97-b147-6c6c4ac95353

•While not required, consider using an email account that is not associated with any EQuIS users (i.e., you do not need to be logged into EQuIS to obtain an OAuth token as described below). For example, request that your Office 365 Exchange administrator create an email account for EQuIS@mycompany.com and grant IMAP or POP and SMTP permissions to that account.

•The OAuth token obtained by following the instructions below is associated with the given email address, but may be re-used for both IMAP or POP (incoming email) and SMTP (outgoing email); no need to repeat the process and get separate tokens for IMAP or POP and SMTP.

To obtain an OAuth token from Microsoft Office 365, follow these steps:

•In a web browser, navigate to https://aad.equisonline.com/microsoft365_oauth.html.
(Consider using an InPrivate/Incognito browser window to authenticate as a separate Office 365 account to avoid conflicts with your primary Office 365 account).

•Enter the URL of your EQuIS Enterprise site (e.g., https://mysite.equisonline.com).

•Enter the full email address of the email account you plan to use in EQuIS for incoming and outgoing email (e.g., EQuIS@mycompany.com).

•Click the Sign in with Microsoft button to begin the Office 365 authentication process for that user.

•Complete the Office 365 authentication process for that user (enter the password, acknowledge MFA requests, etc.).

•After authentication, you may be prompted to allow “EarthSoft EQuIS” to access the mailbox for the authenticated account; if so, accept the request.

•After successful authentication, you will be redirected back to https://aad.equisonline.com/microsoft365_oauth.html; the site URL and email address should automatically populate with the values previously entered.

•After a few moments, a text box will appear with an OAuth token identifier that looks something like this:
ExternalOAuthToken:12345:equis@mycompany.com

•At this point, the OAuth token has been securely stored in your EQuIS database; copy the value shown in the text box and use it as the password when configuring EQuIS to use this email account for IMAP or POP (incoming email) and SMTP (outgoing email) – See mailSettings and Workflow Widget topics.