Introduction

Octopus gives access to a tool which enables user to view and edit their MailIntegration configuration file (XML file).

Availability:
This tool will available within the client setup kit (starting with version 6.0.400).

Usage

By using this tool, you agree that you know what your are doing. Octopus can't be hold responsible for a MailIntegration outage following usage of this tool. It is your responsability to test the configuration before and after deploying it into production.

The application is designed to keep the XML elements and attributes not supported by the actual version of the tool. Again, it is your responsability to validate the changes made to the XML file prior to deploy the file in production.

Outlook 365 and Basic authentication

Basic authentication mode is being deprecated by Microsoft. By October 2022, it will be completly removed for ALL tenants (basic authentication may already been disabled for your tenant). To ensure MailIntegration keeps running, upgrade your configuration to use Azure authentication as soon as possible.

WARNING:
Prior to deploy Azure Authentication (MSAL), make sure you have available resources and expertise to implement and support Enterprise Application in your tenant.

Octopus does not have acces to your Azure tenant configuration required in the following steps. Contact your Azure and Microsoft 365 adminstrators for more assistance.

Before you begin

ensure to read and understand how to deploy Enterpise Applications in your Azure Tenant
- Please refer to the main MailIntegration wiki for more details
obtain the identifiers of your Enterprise Application (that you created previously) and of your Azure tenant
have access to the Windows Server where the MailIntegration scheduled task is running
know the physical locations of the MailIntegration XML configuration file

Upgrading a XML file

Launch the ESI.Octopus.MailIntegration.ConfigurationEditor application. You can find this application within the same folder as ESI.Octopus.MailIntegrationApp
Open the XML configuration file of MailIntegration that you wish to upgrade.
If not already done, in the Gatway section, select New Gateway (MailKit)
In the Authentication method section, select Authentification Azure (MSAL)
- Enter your Enterpise Application ID in the Client ID field
- Enter your Tenant ID in the Tenant ID field
Press the Test button
Once the test is succesfully completed, you can save the actual configuration by clicking on the Save button, located in the top right corner of the application.

Application overview

1. MailIntegration configuration file

You can select an existing file. The content of the file will then be validated and shown in the graphical interface.

Once the modification made to the configuration are working, you will be able to save those changes into an XML file.

Important:
Each time you save the configuration, a backup of the file you are saving to will be made.

2. Basic configuration

Those settings indicates to MailIntegration how to establish a communication with your incoming mail server, using the POP3 protocol

Server
- POP3 server name to contact. For example, if you are using Microsoft Office 365, the value of this field will be outlook.office365.com
Port
- There are two popular values :
  - 995
    - to establish secure connection through SSL
  - 110
    - to establish a non secure connection
SSL
- SslOnConnect
  - Value to use to establish a secure connection to a server
- None
  - Value to use when establishing a non secure connection to a server
- Auto, StartTls et StartTlsWhenAvailable
  - Are available for advanced user only. Those values shall not be used
Delay
- 60 (Default value)
  - Maximum time before the application stops waiting for a connexion to a POP3 server

3. Gateway

New gateway (MailKit)
- Deployed several months ago, this gateway meets new security requirements for Azure authentication (MSAL). This gateay is more secure and stable than the previous one. You MUST use this new gateay. This gateway is compatible with all POP3 servers.
Old gateway (Sidepop)
- This gateway is depcreated and will be removed in a future release. It does not meets new security requirements.

4. Authentication

Username
- Username to connect to your mailbox
Password
- Password to connect to your mailbox

5. Authentication method

Basic
- Establish the connection by sending username / password to the server
Authentification Azure (MSAL)
- New authenication method required to use an Azure mailbox
  - For more information, please read the Microsoft documentation about this subject: https://docs.microsoft.com/en-ca/azure/active-directory/develop/msal-overview
- For this method to work, you will need your two Azure identifiers:
  - Application ID : This ID enables MailIIntegartion to securly establish a communication and be correctly authentified into your Azure tenant. To view your Enterpise Applications in your tenant: https://aad.portal.azure.com/#blade/Microsoft_AAD_IAM/StartboardApplicationsMenuBlade/AppAppsPreview
  - Visual explanation
  - Tenant ID : This ID is your Tenant ID. To find your Tenant ID: https://aad.portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview
  - Visual explanation
- Client ID and Tenant ID are unique identifier values. Their format is something like 00000000-0000-0000-0000-000000000000.

6. Test

This button will trigger a connection test to the configured POP3 server. Prior to launch the test, the tool will validate the values of all fields.

7. Results

Test results will be shown in this zone.

Help us improve our articles

MailIntegration configuration tool

Table of contents