OAuth 2.0 Microsoft Exchange Email Connection
Until now, Provar had been using basic authentication for Microsoft Exchange Web Service (EWS). Provar users can now access Microsoft Emails using OAuth 2.0 using Microsoft (EWS) by creating a new connection or updating an existing connection. And, they can use Send, Subscribe and Receive Message Test APIs with Microsoft Exchange for emails.
Note: Microsoft has announced that effective October 1, 2022, they will begin disabling Basic authentication for Outlook, EWS, RPS, POP, IMAP, and EAS protocols in Exchange Online.
They will begin to disable Basic Auth in all tenants, regardless of usage (with the exception of SMTP Auth, which can still be re-enabled after that) Deprecation of Basic Authentication – Office 365 Basic Authentication Report.
For more information, please see Deprecation of basic authentication exchange online.
Prerequisite
A prerequisite to authenticating a user to use Microsoft Exchange Web Service (EWS) API is to register Provar as an App on the ActiveDirectory App Registration to generate the connection properties and grant the necessary access to retrieve the requisite data. Microsoft provides the following options to set up a Microsoft Exchange:
- Get an Office 365 Developer Site (recommended). This is the quickest way for you to get an Exchange mailbox.
- Download Exchange Server.
Steps to create an OAuth 2.0 Connection in Provar
To integrate with Microsoft Exchange, a connection must be created to authenticate the user.
In the Test Settings, navigate to the Connections tab and click the plus (+) sign icon. The Add New Connection screen is displayed. Give a Connection Name.
In this example, we have given the Connection Name as MSOAuth Host. And, the Connection Type as Microsoft and MS Exchange.
The Type field is now displayed as a drop-down and with default value Online Exchange Account (Deprecated) option. The Type field is an authorisation assertion type and it displays three options in the drop-down:
- Online Exchange Account(Deprecated)
- Exchange 2007 or later (via EWS)
- Older version of Exchange (via IMAP)
Select the Exchange 2007 or later (via EWS) option, we’ll first see the Host field.
In the Host field, we can see two options:
a) Auto Discover
We have selected Host as Auto Discover.
In the Authenticate field, select OAuth 2.0.
Enter the values for the required fields, the Tenant ID, Client ID, Client Secret; and Redirect URL information will be available for the Provar App configured on the Microsoft ActiveDirectory App Registry.
Note: The Authorise button is enabled only after you have filled these five mandatory fields.
We have created a connection and filled all the mandatory fields and clicked Authorise.
The MS Exchange Authorisation screen is displayed for the user to authenticate with their Microsoft account.
Enter the user password and click Sign in.
We have authenticated our OAuth 2.0 connection; the Access Token and Refresh Token are fetched from Microsoft.
There is some validity for these tokens in the Microsoft account. If for some reason these Access Token and Refresh Token are invalidated; let’s say that validity has been breached and the Refresh Token has expired. So, the Refresh token will stop working and an error is displayed to the user.
Note: Since we had Revoked this token for example; so the error message is Revoked; if it would have expired, then the error message would have displayed for Expired.
If some fields are filled incorrectly or if some fields are invalidated then also the corresponding error messages will be displayed. For example, let’s say there is some change in the Client ID field; then the Access Token and Refresh Token are invalidated. And, you will have to authorise the connection again.
b) Supplied Host Name
We have selected Host as Supplied Host Name.
In this case, we have to supply a Host Name.
Note: Provar currently supports the Microsoft 365 for host name for outlook email and this name will be the host name always (outlook.office365.com). Users can specify whatever hostname they want to provide.
As we have supplied the Host Name so you can see there is no User Name field. In this case. Since we have provided the host name, we know where the server is deployed.
Enter the values for the required fields, the TenantID, Client ID, Client Secret; and Redirect URL information will be available for the Provar App configured on the Microsoft ActiveDirectory App Registry.
When we click on Authorise, we will have to provide a username and a password.
Note: The Authorise button is enabled only after you have filled these five mandatory fields.
We have created a connection and filled all the mandatory fields and clicked Authorise.
The MS Exchange Authorisation screen is displayed for the user to authenticate with their Microsoft account.
Enter password and click Sign in.
We have authenticated our OAuth 2.0 connection; and the Access Token and Refresh Token are fetched from Microsoft.
Note: The OAuth functionality is only applicable to the “Exchange 2007 or later (via EWS). Users will not be able to create this type of Online Exchange Account (Deprecated) connection and if anyone has created they will have to manually update their connections for Online Exchange Account. Earlier it was just displayed as an Online Exchange Account. And, now it is displayed as an Online Exchange Account(Deprecated) as displayed in the screenshot given below. And, it will be removed in the future Provar releases from the type of connections.
Microsoft mail server connection via HTTP Proxy settings
Provar has now updated the mail server connection to enable connection via proxy connection. Earlier, if the user created a Microsoft connection, it wasn’t supported for proxy type of connections i.e. if the user created a Microsoft connection, they had to use it without using any proxy. Let’s say if a user had enabled proxy on their machine, then they wouldn’t be able to use this Microsoft connection.
Provar now supports the Microsoft connection using proxy. You can enable proxy settings from Help > Network Settings. Click New to enable proxy like any HTTP Proxy or OAuth proxy or non-OAuth proxy. Now, Microsoft connections will work, if the user has enabled HTTP Proxy settings.