TaskSuite OAuth Microsoft Set-Up - Inbound Email

Owned by Lourenzo Hammond
Last updated: Sept 01, 2022
7 min read

Introduction

TaskSuite has integrated with Microsoft to allow for OAuth2.0 authentication to take place on inbound mail servers. The set up requires some configuration by the client on their Azure Portal: https://portal.azure.com/#home

Azure Portal Set Up

The set up consist of a number of steps to grant TaskSuite exclusive access to the target mail box. Follow the steps below to obtain the required information to allow TaskSuite to authenticate with your desired mailbox.

Step 1: Register an application

Navigate to your Azure portal by clicking on the link provided above and logging in to your portal. Once you have successfully logged in you can navigate to the Azure Active Directory. You can then register a new application on Azure Active Directory by clicking on “App Registrations” as seen in the screenshot below:

Click on the “New Registration” option located towards the top left of the screen as seen in the screenshot below:

The following fields should be populated:

  • Name: The unique name used to identify the TaskSuite application. (Suggestion: TaskSuite-Mail)

  • Supported Account Types: Select the “multi tenant” option

  • Ensure that you tick both checkboxes below to allow TaskSuite to retrieve the access tokens

  • Redirect URI: can be omitted for now and will be set up at a later stage (Step 4)

Click the “Save” option and take note of the information displayed on the screen once the record has been saved. The important fields are “Application (client) ID” and “Directory (tenant) ID” as this will be required to set up the account in TaskSuite.

Step 2: Set up a secret

The next step is to set up a secret for your newly registered application. To do this you will need to click on the newly registered application and navigate to the “Certificates & Secrets” menu as seen in the screenshot below:

Click on the “New Client Secret” button located towards the top left of the list view to create a new secret. The following information will need to be populated:

  • Description: A unique name to identify your secret

  • Expires: How long the secret should last before you would need to update it. TaskSuite suggests 12 to 24 months as this password would need to be changed manually by your manager.

Once you click “Add” you will be presented with a list of secrets that have been created on your Azure Active Directory. Make sure you copy the “Value” section of your newly created secret to be used with the TaskSuite inbound account set up as seen in the screenshot below:

Step 3: API Permissions

The next step is to provide the newly registered application with certain API Permissions. TaskSuite will need permission to maintain access to data you have given it access to as well as read and write access to mailboxes via IMAP. This can be done by navigating to the “API Permissions” tab as seen in the screenshot below:

The main access rights you would need to grant are delegated access rights and are listed below:

  • Mail.ReadWrite

  • offline_access

  • openid

If you have correctly set up your permissions you should see a list as seen in the screenshot below:

You can also click on the “Grant Admin consent for …” option to immediately grant the TaskSuite application access to the permissions listed above.

This temporarily concludes the Azure Portal part of the set up. The last step will be to enter the redirect URI once you have created the inbound mail server on TaskSuite.

Step 4: Set up a redirect URI (return to this step after setting up TaskSuite Inbound Mail Server)

The redirect URI is used by Microsoft to communicate information such as the access token back to the TaskSuite system.

Navigate to the “Authentication” tab in the Azure portal as seen in the screenshot below:

Click on the “Add a Platform” button (highlighted by the red box in the screenshot below) and select the “Web” option (highlighted by the green box in the screenshot below). You will need to enter the Redirect URL which will be used by Microsoft to communcate with the TaskSuite instance when performing OAuth2.0 authentication. If your TaskSuite instance is https://demo.tasksuite.com then your Redirect URL will be https://demo.tasksuite.com/microsoft_outlook/confirm. Once you are happy with the set up you can click “Save” and return to Step 4 of the TaskSuite Inbound Mail Server Set-up.

 

TaskSuite Inbound Mail Server Set-up

The setup process of the TaskSuite mail server involves entering the data obtained from the Azure portal and validating the information. If the information is valid, TaskSuite will automatically handle tokenisation from there on out. The only other manual process would be to change the password once it has expired on the Azure portal. The expiration date is however configured by you and is to be used at your own discretion.

Step 1: Navigate to the General Settings on TaskSuite

Navigate to the general settings by click on Settings->General Settings as seen below:

Step 2: Enable the External Mail Servers and enter the client ID and client secret

Enable the External Mail servers by clicking the boolean feild and enter your client ID and client secret from the Azure portal as seen below:

Step 3: Create an Incoming Email Server and enter the relevant information

Click on “Incoming Email Servers” button and create a new incoming email server as seen below:

 

You will need to enter the following information:

  • Name: Any reference you would like to use

  • Server Type: IMAP Server

  • Outlook: This checkbox should be checked

  • Username: This should be the email address of the mailbox that you would like to link to TaskSuite

Ensure your Inbound Email server looks like the one below and click “Save”.

Step 4: Connect your Outlook Account

Click on the “Connect your Outlook Account” button and allow access to your Outlook account by selecting the Outlook account in the Microsoft Authentication portal as seen below:

Once you are returned to the Inbound Mail Server set up you should see a green pane that states that the Outlook Token is Valid as seen below:

 

Step 5: Test & Confirm the email server

Click on the “Test & Confirm” button to enable the Inbound Mail server as seen below, if everything is set up correctly the server will move into a Confirmed state:

 

Important Notes:

  • Please ensure that the email address being used has a valid Office 365 license and has access to an Outlook inbox.

For any queries regarding the set up, please contact support@taskflow.co.za or support@tasksuite.com