Clarity Email configuration issue with STARTTLS
search cancel

Clarity Email configuration issue with STARTTLS

book

Article ID: 404658

calendar_today

Updated On:

Products

Clarity PPM On Premise Clarity FedRAMP

Issue/Introduction

We are experiencing issues subsequent to the configuration of the email server. StartTLS was enabled as required, by setting the 'Enable StartTLS' flag to 'True' within the NSA/CSA interfaces.

Further details regarding the encountered issues are faced.

  • Process  fails with the following error message, when <email:email> tag is used:
    BPM-0704: An error occurred while executing custom script:
org.apache.commons.jelly.JellyTagException: null:7:153:
<email:email> 530 #5.7.0 Must issue a STARTTLS command first
at org.apache.commons.jelly.tags.email.EmailTag.doTag(EmailTag.java:302)
  • Using the <gel:email> tag does not work either
  • Emails from Jobs, Processes etc. do not work as well

Environment

Clarity 16.3.0,16.3.1,16.3.2,16.3.3 

Cause

  1. Wrong Port used in the NSA / CSA configuration
  2. Email Server certificate not imported into Clarity application server's Java's cacerts keystore.

Resolution

Configuring StartTLS for email in Clarity involves two main parts: the email server itself and the Clarity application's ability to connect to it.

Here are the prerequisites, broken down into these two categories:

Prerequisites for the Email Server (Mail Transfer Agent )

  • SMTP Server Configured with StartTLS Support: Your chosen email server software (e.g., Microsoft Exchange, Postfix, Sendmail, Exim, Gmail/Microsoft 365 SMTP Relay, etc.) must be installed and configured to support SMTP with StartTLS.This typically means it listens on port **587 (Submission)** or **25 (Standard SMTP)** and offers the `STARTTLS` command after the initial connection. Port 587 with authentication is generally preferred for application-to-MTA communication.

 

  • Valid SSL/TLS Certificate: The email server must have a valid SSL/TLS certificate installed.

    • Certificate Type: Ideally, this should be issued by a trusted Public Certificate Authority (CA) (e.g., DigiCert, Sectigo, Let's Encrypt). If it's an internal CA or self-signed certificate, you'll need to manually trust it on the Clarity application server.

    • Hostname Match: The certificate's Common Name (CN) or Subject Alternative Name (SAN) must match the hostname (FQDN) that Clarity will use to connect to the email server.

    • Chain of Trust:** Ensure the full certificate chain (server certificate, any intermediate CA certificates, and the root CA certificate) is correctly installed on the email server.

 

  • Authentication Credentials: If your email server requires authentication for sending (which is highly recommended and often mandatory for StartTLS on port 587), you'll need a valid username and password for an account that Clarity can use to send emails.

  • Network Connectivity & Firewall Rules: The email server must be reachable from the Clarity application server over the network. Firewall rules on both the email server and any network devices in between (e.g., corporate firewalls) must allow outgoing connections from the Clarity application server's IP address to the email server's SMTP port (typically **587** or **25**).

  • Relay Permissions: The email server must be configured to allow relaying from the Clarity application server's IP address, or allow relaying for the authenticated user account that Clarity will use.

 

Prerequisites & Configuration for Clarity PPM

  • Clarity Version Compatibility: Ensure your Clarity PPM version supports StartTLS. Most modern versions (16.1.x) do. Check the official Broadcom Clarity documentation for your specific version if you are on a very old release.

  • Java Runtime Environment (JRE) Truststore Configuration: Clarity runs on Java, and the JRE needs to trust the email server's SSL/TLS certificate.

    • Public CA: If your email server's certificate is issued by a widely trusted Public CA, the JRE's default `cacerts` truststore usually already contains the necessary root certificates, so no extra steps might be needed.

    • Internal CA / Self-Signed: If your email server uses a certificate from an internal Corporate CA or a self-signed certificate, you must import the email server's certificate (or its issuing CA's certificate) into the Java 'cacerts' truststore on each Clarity application server (where the app/bg services run).

    • The 'cacerts' file is typically located at '<JAVA_HOME>/lib/security/cacerts'.

    • You'll use the `keytool` utility to import the certificate. Example command:

       keytool -import -trustcacerts -alias <your_email_server_alias> -file <path_to_email_server_cert.cer> -keystore <JAVA_HOME>/lib/security/cacerts

keytool -import -alias mailserver-cert -file mailserver.crt -keystore cacerts
  • Network Connectivity: The Clarity application server must be able to establish a network connection to the email server on the specified SMTP port. Verify this using telnet <email_server_hostname_or_ip> <port> from the Clarity server.

  • Clarity Services Restart: After configuring the JRE trust store or making significant changes in Clarity's mail server settings, you must restart the Clarity Application (app) and Background (bg) services for the changes to take effect.

Additional Information

  • Once the configuration are done and if still there is problem please enable debug using com.niku.union.notification class to get additional details for troubleshooting 
Powered by Wolken Software