Enabling GMail Access in the BP3 Email Toolkit Example App



The BP3 Email Toolkit Example Process App requires access to an email server to work. The ubiquity of GMail accounts makes them a good candidate for testing external email servers using the example app. However, standard security settings of WebSphere and GMail accounts are likely to cause errors and prevent email from being sent through the example app. The following information covers how to configure access to allow a GMail account to be used.

Problem 1

A "failed to connect" or "Certificate chaining error" message is displayed by the process app. When examining the SystemOut.log you may also see an error related to certificates:

ERROR Mailer - Could not connect to SMTP host: smtp.gmail.com, port: 465
javax.mail.MessagingException: Could not connect to SMTP host: smtp.gmail.com, port: 465;
nested exception is:
javax.net.ssl.SSLHandshakeException: com.ibm.jsse2.util.j: PKIX path building failed: java.security.cert.CertPathBuilderException: PKIXCertPathBuilderImpl could not build a valid CertPath.; internal cause is:
java.security.cert.CertPathValidatorException: The certificate issued by OU=Equifax Secure Certificate Authority, O=Equifax, C=US is not trusted; internal cause is:
java.security.cert.CertPathValidatorException: Certificate chaining error

These errors are caused by WebSphere security settings related to signed certificates.


There are several Websphere-related security configurations that may need to be addressed to solve this issue.

Importing the Signer Certificate into the Trust Store:

  1. Login to BPM's WebSphere Administrative Console and navigate to "Security > SSL certificate and key management > Key stores and certificates > CellDefaultTrustStore > Signer certificates"
  2. Click 'Retrieve from port' button
  3. Specify Host, Port, and Alias of the SMTP server to be used in the example and click "Retrieve signer information." For GMail access you would use the following values:
    • Host: smtp.gmail.com or smtp-relay.gmail.com
    • Port: 465
    • Alias: This can be anything that will allow you to easily identify the certificate, such as "GMailSSL" or "smtp.gmail.com"
  4. Signer information will be retrieved and displayed to you for review.
  5. Click Apply, then Review changes. Check the "Synchronize changes with Nodes" option and click Save.
  6. Navigate to "System administration > Nodes" and verify that all nodes are synchronized (click Synchronize, if unsure)

Extended problem and solutions

Intermittent certificate chaining errors when using SSL authentication (but not with TLS authentication) may be due to several factors.

  • There is a known issue with certain versions of BPM whereby the utilized certificate trust store gets switched to the java CACerts trust store. There are fix packs available from IBM. See the following reference article regarding JR46822 and to determine which fix pack is appropriate for your environment:


  • As an alternative to the fix for JR46822, you may also manually import the missing certificates from the chain into the java certificate authority store (CACerts). Download the missing certificates and import them using the "keytool" command:

<WAS java home directory>/bin/keytool -v -import -trustcacerts -keystore <WAS java home directory>/lib/security/cacerts -file <path to missing cert file>/Missing_Cert_Filename -alias Certificate_Alias

  • Quality of protection settings may require updating.
    1. Login to BPM's WebSphere Administrative Console and navigate to "Security > SSL certificate and key management > SSL configurations > CellDefualtSSLSettings > Quality of Protection (Qop) settings"
    2. Under "Protocol" set to "SSL_TLSv2"
    3. Click Apply, then Review changes. Check the "Synchronize changes with Nodes" option and click Save
    4. Repeat the above steps for the NodeDefaultSSLSettings

Problem 2

The example app may fail send mail despite using the correct password and having the signer certificate in place. Default GMail security settings may be preventing the example app from connecting. Older version of BPM may simply generate a "failed to connect" error while newer version may give a more detailed response similar to "Please log in via your web browser and then try again. Learn more at https://support.google.com/mail/answer/78754"


Allowing less secure apps to access your GMail account will allow mail to be sent through the example process app.

  1. Sign into your GMail account.
  2. Navigate to My Account > Sign in & Security > Connected apps & sites.
  3. Turn "Allow less secure apps" from Off to On. (Note: This setting is hidden if your administrator has locked less secure app account access.)

This option can be activated temporarily for testing purposes. We recommend turning it off again after you are finished testing the example app to maintain higher security for your account.

Note: From our tests, this particular security setting is finicky and may not always engage. After changing this setting you should step out and back into the "Allow less secure apps" settings page to verify that it is configured as desired.

Reference link: https://support.google.com/accounts/answer/6010255

Problem 3

Use of two-factor authentication will prevent the simple password-only authentication used in the example application from working.


It is not recommended that you turn off two factor authentication. Instead, generate an application-specific password. See the following Google support article for how to generate an application-specific password: https://support.google.com/accounts/answer/185833


Have more questions? Submit a request


Powered by Zendesk