Introduction

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.

 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

2. Basic configuration

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