How to configure SMTP on Jira Align self-hosted requiring SSL/TLS and Authentication

Summary

This article describes on how to setup SMTP on Jira Align self-hosted instance where the mailbox server needs mailbox authentication and secure connectivity on TLS/SSL ports.

Environment

Jira Align self-hosted

Solution

1. Please inform the mail server administrator to configure the below:

   1. A dedicated mailbox for Jira Align

   2. The password of the mailbox/AD user should never expire.

   3. The mailbox storage should be unlimited or archiving enabled in case the SMTP saves email on the mailbox

2. Gather the below details from the mailbox administrator:

   1. What is the SMTP server hostname?

   2. What is the mailbox address configured for Jira Align?

   3. Is there a corresponding Active Directory account for the mailbox?

   4. Does SMTP use secure port such on TLS/SSL? (by default, port 25 is non-secure, secure ports = 465 or 587)

   5. What is the port number for SMTP?

   6. Does the SMTP connection need authentication?

   7. What is the domain name of the user account associated with the mailbox?

   8. What is the user name of the account associated with the mailbox?

3. Testing SMTP connectivity from Jira Align server

   1. Install Telnet Client

   2. Open CMD prompt as admin

   3. Telnet to mail server on the port provided by mail server admin - telnet <mailserver_hostname> <port> (e.g. telnet mail.contoso.com 587)

   4. pass the command "EHLO <mailserver_hostname>

   5. pass the command "AUTH LOGIN"

   6. pass the user name as base64 encoded string. Use a trusted public base64 encoder such as https://www.base64encode.org/. Note, is using "domain\username", encode the "domain\username" as the base64 username.

   7. pass the password as base64 encoded string when prompted

   8. "235 Authentication succeeded" message is expected.

4. configuring Jira Align with SMTP details:

   1. Open [ROOT_DIRECTORY]\BackofficeService\ServiceTasks.BackOffice.dll.config.

   2. replace “smtp_from_email_address” with the mailbox address gathered in step-2

      1. Configure the network element using the below details:

         <network

         clientDomain="string" ---→ domain name gathered in Step-2

         enableSsl="true|false" ---→ based on step-2 (25 - false, 465/587 - true)

         host="string" ---→ SMTP server hostname

         password="string" ---→ SMTP user password

         port="integer" ---→ SMTP port

         userName="string" ---→ SMTP username

         />

   3. Start the BackOffice_Service from Services.msc

   4. Check for any error on the BackOffice_Service logs.