Third-Party Integrations: Microsoft

The Microsoft integration can be used to allow using OAuth authentication for IMAP (department email accounts) and SMTP (outgoing emails).

Prerequisites

To set up Microsoft, you must have a Microsoft Azure account. It is free to sign up, and if you are using Microsoft 365, then it should automatically exist.

Activate or Deactivate Integration

The Microsoft integration is disabled by default and needs to be activated before use.

1. Visit Settings -> General -> Third-Party Integrations.
2. Find the Microsoft integration and click the "Activate" link located on the left of the table.
3. The page will reload confirming the integration has been activated.

The integration can be deactivated by following the above process, but using the "Deactivate" link instead.

Integration Settings

To set up Microsoft, follow the steps below.

1. Visit the Azure Active Directory admin center - https://aad.portal.azure.com - and sign in to your Microsoft account.
2. Click on the "Azure Active Directory" in the sidebar. If it's not there, you can find it under "All services".
   
3. Under "Manage", click on "App registrations".
   
4. Click on "New registration".
   
5. In SupportPal, click on "Settings" under Microsoft on the third-party integrations page. This page will show you the required redirect URI needed.
   
   
6. Enter a name for your application, select "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)" for supported account types and fill in the redirect URI with what is shown in SupportPal. Click "Register".
   
7. Your app will now be registered, the application (client) ID is what you'll need to enter in to SupportPal later.
   
8. Next, under "Manage", click on "Certificates & secrets".
   
9. Click on "New client secret". In the popup that shows, enter a name and select "24 months" for the expiry, then click "Add".
   
   
10. The client secret value (not client secret ID) will show that need to be entered on the SupportPal screen, along with the client ID as mentioned above, and click "Save".
    
    

Microsoft OAuth for Department Email Accounts (IMAP) and SMTP

To use Microsoft as an OAuth authentication provider, follow the below steps.

1. Ensure the Microsoft integration is set up as listed in Integration Settings.

2. Department Email Accounts

   Go to Settings -> Tickets -> Departments, click an existing department or create new department. Scroll down to Email Accounts.
   OAuth authentication only works on IMAP.

   SMTP

   Go to Settings and click on the Email tab. If configuring for a brand, go to Settings -> General -> Brands, click on your brand and then the Email tab.
3. Change the Authentication dropdown to "OAuth".
4. Select Microsoft from the provider dropdown. If it isn't visible, you may have a problem in your integration settings.
5. Ensure the rest of the relevant details are filled in Click on "Get Access Token".
   
6. A pop up will show, click "Yes" to continue.
   
7. The token will now have saved to SupportPal, you can confirm by seeing that the button is now red and labelled "Reset Access Token".
   
8. Finally, click "Validate Authentication" to confirm it it is working, and save on seeing a success message.

Troubleshooting

The provided value for the input parameter 'redirect_uri' is not valid

The redirect URL entered in the Microsoft app is not correct. Under "Manage", click on "Authentication" and ensure the Redirect URI matches the one shown in the integration settings. Click "Save" after changing the URI.

User is authenticated but not connected

There are a plethora of reasons why you may see this error, below are some possibilities:

• You're connecting via an alias rather than the primary account.
• Your connection has been throttled and you need to wait a few minutes.
• Bug in Microsofts' IMAP implementation which incorrectly says successful authentication when it should have failed.