This help page is for version 9.2. The latest available help is for version 9.3.
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 File Sight installation for sending email alerts.
Note: The below steps are supported in PA File Sight version 8.5 or newer.
Register PA File Sight in Azure Active Directory
If you have multiple installations of PA File Sight, 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 File Sight 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
Now copy the Azure Application (Client) ID to the Client ID field in the Email Action.
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.
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.
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.
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.
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).
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.
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.