How to Setup OAuth 2.0 with Office365

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

Hint: Check each item as you go so none are skipped
1. If you have an Office365 account, you also have a Microsoft Entra ID account. Login to Azure at https://portal.azure.com/. If you don't go directly to your Entra account, you might need to select it at the top:

   Once you are in Entra ID, click on App Registrations in the menu on the left. It might be under the Manage category.

   
2. 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".

3. The default Supported Account Type (single tenant) is the correct value for most situations.
4. For the Redirect URI, choose Web, and specify the URL found at the bottom of your Email Action

Application Values

5. Now copy the Azure Application (Client) ID to the Client ID field in the Email Action.
6. 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.

Application Scope

7. 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)

8. 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.


9. Once you press the Add button, the Client Secret's value is displayed.
   
   Copy the Value (not the Secret ID) 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)

10. 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.
11. Click "Add a permission", and then on the right the APIs my organization uses. Enter "office" in the search box and then select "Office 365 Exchange Online".
12. Select Applications Permissions on the right side.

    For the Email Action to send alerts, scroll down to the SMTP section and choose "SMTP.SendAsApp"

    For the Mail Monitor, scroll down and select "IMAP.AccessAsApp" and/or "POP.AccessAsApp" and then click "Add Permissions" at the bottom.

    
13. If this is a new mailbox that is being setup, make sure it has a license assigned to it.

Authenticating with OAuth 2.0

14. 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).
    
15. 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 target account (the account that will send emails, or the account whose mailbox will be checked).

    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.

16. 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.