oAuth support for Office 365, Outlook.com, Exchange Cloud

Please note: Provisioning and configuring the App Registration in Azure AD falls outside the purview & expertise of Square 9 Software Support. This should be directed to your Local IT and/or a Windows Technician.

Problem

As of October 2022, Microsoft will completely deprecate basic authentication for mailbox access. Customers using one of these services MUST upgrade their version of GlobalCapture if any workflows import email from one of these sources. Customers will need to be on GlobalCapture 2.4.113 or greater to continue use of these services in conjunction with GlobalCapture.

Solution

Customers will need to upgrade to gain access to the supporting technology required to properly authenticate to Microsoft’s services. Once upgraded:

1. Your Azure / Office 365 admin will need to provision a new App Registration for GlobalCapture to authenticate to.

   1. Note that the GlobalCapture App Registration does not need a redirect URI
      

      

      
      

2. Your Azure / Office 365 admin will need to set API permissions appropriately for your organization. The App will need to be configured with privileges to read and edit mail messages from any mailbox that participates in a GlobalCapture. API access to all mailboxes would include:
   
   EWS.AccessAsUser.All
   full_access_as_app
   

3. Your Azure / Office 365 admin will need to provide values for the Client ID (Application ID) and Tenant ID (Directory ID).
   

4. Your Azure / Office 365 admin will need to create a client secret and provide the value.

If you are unable to provision these permissions, please contact your Azure / Office 365 admin or Microsoft support.

With the 3 data points provided by your Admin in hand, you will need to configure your workflows to authenticate.

To reiterate, you will need:

• Client ID

• Tenant ID

• Client Secret

Note, you can only access the Client Secret value at the time of creation. You will not be able to access the value in the future without previously documenting it yourself.

Import Node Configuration

Customers implementing oAuth2 will need to ensure they are using the option for Exchange email import. The server address will resemble:

https://outlook.office365.com/ews/exchange.asmx

Provide an email address in the User Account field, then ensure the option for oAuth2 is checked. Provide the Tenant, Client ID, and Client Secret. Account passwords are not applicable to this authentication method.

Click Test to ensure the configuration is correct.

If the test is not successful, please verify the 3 datapoints are correct and the email address provided is valid.

Your Admin will want to review authentication and / or access logs to help identify authentication errors at this stage.

Please note that the Client Secret is not a GUID like Client ID and Tenant ID (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) instead it will be a random alphanumeric sequence that often contains ~ symbols.

Note for existing customers, each workflow performing email import from exchange mailboxes will need to be updated.

Customers who can not or choose not to upgrade GlobalCapture to 2.4.113 or greater can setup mailbox forwarding rules to send messages to a mailbox source that the version of GlobalCapture you are using can authenticate to.

Reverted as of 2.4.121 to previous move to deleted folder behavior.

The mail engine has changed in 2.4.113 to allow for oAuth2, which has also changed inbox import behavior. Now, Office365 emails that would have been moved to the deleted folder will instead be permanently deleted from your email inbox. To keep a record of these emails, it is recommended to create a second email address for GlobalCapture to import from and copy forward the emails to that address. The 1st email account should contain the originals, while the 2nd email account should contain copies which the workflow will delete.

Microsoft Resources

If you are looking to control access to specific mailboxes, speak to your admin about application specific policies. This article can also provide some context on access control.

The mailbox-level permission needed is Mail.ReadWrite, it needs to be set for each mailbox that GlobalCapture is going to import from. This is separate from the API level access mentioned above. If you want to limit the permissions to a subset of mailboxes, you follow the directions in the Microsoft article to create a new ApplicationAccessPolicy, with only Mail.ReadWrite permissions to the desired mailboxes. These specific steps cannot be performed by Square 9 support. If you run into issues please contact Microsoft support or your Azure / Office 365 admin.

Related articles