How to Setup OAuth 2.0 with Office365

Starting in October 2022, Microsoft is expected to disable legacy (username/password) logins for Office365 and only allow "modern" authentication mechanisms, specifically OAuth 2.0.

Although POP and IMAP access will require OAuth, Microsoft is allowing SMTP to continue using 'legacy' authentication (username/password). The legacy option is easier to use and less of a security risk for SMTP than with POP and IMAP (since it is send-only).

OAuth 2.0 requires an application to be registered in an authentication directory, and for Office365 that is Azure Active Directory. This document will walk you through the required steps so you can use Office365 in your PA Server Monitor installation for sending email alerts.

Note: The below steps are supported in PA Server Monitor version 8.5 or newer.

Register PA Server Monitor in Azure Active Directory

If you have multiple installations of PA Server Monitor, these steps (application registration) must be done for each installation. Installations can NOT share the IDs and secrets that will be granted through this process. If the IDs and secrets are shared among multiple applications or installations, they will log each other out every time the credentials are used (every time an email is sent).

However, you CAN have multiple applications all send through the same Office365 account/email address.

If you have an Office365 account, you also have an Azure Active Directory account. Login to Azure at https://portal.azure.com/. If you don't go directly to your Active Directory, you might need to select it at the top:

Once you are in Azure Active Directory, click on App Registrations found on the left side.

Click New Registrations near the top.

Give your application registration a name. We recommend including the application name and the server it is installed and what access is being granted. Something like "PA Server Monitor on SERVER01 for emailing via Office365".

The default Supported Account Type (single tenant) is the correct value for most situations.

For the Redirect URI, choose Web, and specify the URL found at the bottom of your Email Action

Azure Application Registration Redirect URL

Application Values

Now copy the Azure Application (Client) ID to the Client ID field in the Email Action.

Azure Application Registration - Client ID

To get the Email Action's Authorization URL and Token URL values, click the Endpoints button in the Azure Application Registration, and copy the URLs on the right.

Azure Application Registration - Authorization and Token URLs

Application Scope

The Authorization Scope requests specific access to Office365 resources. Depending on what type of connection you're setting up, use one of these Scope strings. For the Email Action use the SMTP setting. Other scenarios, such as the Email Acknowledgement feature, might use POP3 or IMAP.

For SMTP:

https://outlook.office.com/SMTP.Send offline_access

For POP3:

https://outlook.office.com/POP.AccessAsUser.All offline_access

For IMAP:

https://outlook.office.com/IMAP.AccessAsUser.All offline_access

Mail Server

The Email Action's SMTP Server Name, Port, and Username for SMTP Server will be the same whether you use OAuth 2.0 or not, and will be available from your Office365 account. Typically these are values such as smtp.outlook.com, port 587, and Explicit SSL/TLS respectively.

Client Secret (instead of Password)

The Password field is NOT the email account password, but rather a Client Secret for this specific Application Registration. Click the Add a Certificate or Secret link.

Azure Application Registration - Go to Client Secret

Click the +New Client Secret button and give the secret a name. We recommend making the expiration as long as possible so you will not need to revisit this soon. Currently 24 months is the maximum allowed.

Azure Application Registration - Client Secret Expiration

Once you press the Add button, the Client Secret's value is displayed. Copy the value immediately. Once you leave this page, the value will never be displayed again. This Client Secret is used in the Email Action's Password field.

API Permissions (for POP3 or IMAP)

API permissions may need to be granted, for example if using IMAP or POP access for example. To do that, select the API permissions link on the left.

Click "Add a permission", and then on the left the "APIs my organization uses". Enter "office" in the search box and then select "Office 365 Exchange Online".

Select Applications Permissions on the left side.

Scroll down and select "IMAP.AccessAsApp" and/or "POP.AccessAsApp" as required, and then click "Add Permissions" at the bottom.

Authenticating with OAuth 2.0

Now that all of the pieces are in place, you can click the Email Action's Test Server button (or the Test button in the other area in the application where you are working). This will probably display the dialog below. This dialog can also potentially be shown at other times if tokens expire and Office365 requires a new authentication (more on this below).

The shown authentication URL needs to be visited and logged into in a brower. You can either copy the URL and open a browser yourself, or press the Open Browser button. Be sure to login with the requested account (the account that will send emails).

CAVEAT: Office365/Azure uses cookies to keep track of logged in sessions. If you go to this URL and it immediately forwards you to the OAuth Authentication Complete page, you will have authenticated using whatever account the cookies are tied to, and not necessarily the account that the Email Action will use. If this happens, copy the URL to a private/incognito browser and login there. This will ensure you authenticate the proper account.

Once you have authenticated, press the Test Server button again to do a final and complete email send test.

Periodic Reauthentication

Office365 (Azure) now controls how long the authentication is valid. Every time an email is sent the authentication is checked and refreshed. According to Microsoft documentation, if the internal authentication tokens aren't used for 90 days (i.e. no emails are sent for 90 days) the authentication will timeout. If the Office365 user account's password is changed this can also cancel the current authentication. In addition, we saw above that the Client Secret is only valid for up to 24 months.

If/when the authentication becomes invalid, that is considered a System Error and the new required authentication URL will be shown at the top of reports, and sent out via other notification Actions. This would be a good reason to have a Backup SMTP server configured. Until the newest authentication URL is used to login, email will fail to send.

	PA Server Monitor Help Map