Setup GMail as mail provider for SOA Suite 12c – configure SMTP certificate in trust store

On this subject, there are already many fine articles. I have borrowed from at least a dozen to understand what should happen and to make it work. You will find them listed under resources.

It all started with me trying to have the UMS Adapter send an email. The setup of the email driver was done in EM FMW Control (see below) and I expected my email to be sent successfully. After a considerable and increasingly anxious wait at my mail client, I decided to check the log file for my WebLogic domain. There it was, in the soa_server1.out for my SOA Suite managed server:

javax.mail.MessagingException: Could not connect to SMTP host: smtp.gmail.com, port: 465;
nested exception is:
javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.s
ecurity.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
at com.sun.mail.smtp.SMTPTransport.openServer(SMTPTransport.java:1934)
at com.sun.mail.smtp.SMTPTransport.protocolConnect(SMTPTransport.java:638)

And I knew I had seen something like that before. And tried to work around it. Use an email provider that did not use SSL based communication for example. However, this time I decided to bite the bullet. And get this settled, once and for all. Now that I have it running, it does not feel like such a big deal anymore. But I do remember my frustrations of yesterday. So here are the steps, for your convenience and my own future pleasure alike.

The background by the way is that when I set up GMail as the Outgoing Mail Server, I configured an SMTP server (smtp.gmail.com) that uses SSL for its (trusted) communications. The JVM is perfectly willing to conduct such communications for us – as long as it knows that we actually trust the party we are doing SSL with. We have to tell the JVM that it is okay to have such communications. And we do that by loading the public key of a SSL certificate in the JVM’s trust store. Note that the exact same thing is required for SSL interactions with other providers, such as Twitter and Dropbox – all using SSL as well. When we want to interact from our SOA Suite domain with these parties we too have to follow the steps in this article.

The steps are these:

• Retrieve certificate for smtp.gmail.com using OpenSSL
• Create a text file with only the certificate
• Load the certificate into the keystore
• Restart WebLogic Domain

Note: the steps are described for Linux but should be almost identical on Windows and other operating systems.

Retrieve certificate for smtp.gmail.com using OpenSSL

Using the OpenSSL tool, we can retrieve the certificate from the server that we want to have our JVM interact with later on. For GMail – and more specifically GMail’s SMTP server for outbound email, we use this command to save its SSL certificate to the file called gmail-smtp-cert.pem. You can choose any name for the local file – as long as you remember it until the next step. The extension .pem is typically used because openssl creates the file in the PEM format.

openssl s_client -connect smtp.gmail.com:465 > gmail-smtp-cert.pem

The file gmail-smtp-cert.pem should be created now. Note: this openssl action can take a long time or not even finish at all. You can end it after a few seconds (CTRL+C for example) because the important part is done very quickly and right at the beginning.

Create a text file with only the certificate

This step can easily go wrong if you do not read carefully. Took me considerable time – not going to tell you how long exactly.

Open the file you retrieved with OpenSSL – gmail-smtp-cert.pem in my case – in an editor (such as vi).

Remove all the lines before the line that says —–BEGIN CERTIFICATE—– – but leave this line itself! Also remove all lines after the line with —–END CERTIFICATE—– but again, leave this line itself. Save the resulting file, for example as gmail-smtp-certificate.txt (but you can pick any name you like).

Load the certificate into the keystore

WebLogic (on which SOA Suite is running) out of the default installation uses a special keystore. It does not use the cacerts store that is installed with the JDK or JRE but instead uses a file called DemoTrust.jks and typically located at %WL_HOME/server/lib/DemoTrust.jks. This trust store is “injected” into the JVM when the WebLogic domain is started: “-Djavax.net.ssl.trustStore=/opt/oracle/middleware12c/wlserver/server/lib/DemoTrust.jks”. We have the option of removing this start up parameter: remove “-Djavax.net.ssl.trustStore=%WL_HOME%\server\lib\DemoTrust.jks” in setDomainEnv.cmd  and then add the certificates to the default Java keystore (cacerts) or, the easier option, we can add the certificate to the DemoTrust keystore that WebLogic uses.

The command for doing this, looks as follows:

%JAVAHOME%/jre/bin/./keytool -import -alias -keystore /opt/oracle/middleware12c/wlserver/server/lib/DemoTrust.jks -file 

in my case that is:

/usr/java/latest/jre/bin/./keytool -import -alias smtp.gmail.com -keystore %WL_HOME%/server/lib/DemoTrust.jks -file /var/log/weblogic/gmail-smtp-certificate.txt

Because the DemoTrust keystore is owned by OS user oracle, I can/have to execute this command as that user.

You will be prompted for the password for this keystore. The default password of the DemoTrust keystore is: DemoTrustKeyStorePassPhrase.

 

You will be asked explicitly whether you trust this certificate [and are certain about adding it to the keystore]. Obviously you will have to type y in order to confirm the addition to the keystore:

Restart WebLogic Domain

The change in the keystore is (probably?) only picked up by the JVM after it is restarted. So if your WLS domain is running, bring it down and start it up again. Now send that email again. It should work.

Configure UMS Email Driver for sending emails with GMail

The UMS Email Driver on the SOA Suite managed server has to be informed about our intention to use GMail for sending email. More to the point: we have to configure smtp.gmail.com as the outbound mail server. We do so in the UMS email driver, in the Enterprise Manager Fusion Middleware Control. Open the node User Messaging Service and select the usermessaingdriver-email node for the managed server that runs the SOA Suite (SCA composite engine). From the dropdown menu, open option Email Driver Properties:

Click on the green plus icon to create a new configuration for the Email Driver:

In the next page with Email Driver properties, you should specify the default sender address – the mail account from which to send emails (when a message being sent has no explicit sender address):

 

Scroll down a little to set the properties for the SMTP server. Set the outgoing mail server to smtp.gmail.com. The outgoing mail server port is 465, the mail server security should be set to SSL. The outgoing username – used by UMS to connect to GMail – should be set to your full email address at GMail. Either set your Google password as a cleartext password or use indirect password to have the password stored in the credential store mapped, see for example here).

Click the OK button to save the email driver configuration’s properties and be returned to the overview page.

Send test email from Enterprise Manager FMW Control

Open the Enterprise Manager FMW Control. Select the SOA | soa-infra node and from the dropdown menu select the option Service Engines | Human Workflow:

The Human Workflow Engine page appears. Open the tab Notification Management. Click on the button Send Test Notification.

A popup appears, allowing me to enter the details for a test mail I would like to send:

Enter the relevant details and press the Send button:

A minor set back appears: “exception.code:31018 exception.type: ERROR exception.severity: 2 exception.name: Incorrect Notification Configuration. exception.description: Incorrect Configuration : NotificationMode : NONE; Channel : email. exception.fix: NotificationMode in workflow-notification-config.xml should be either EMAIL or ALL to send Email notifications; It should be ALL to send any other type of notifications.”

That sounds a little familiar. This means that we still have to configure the workflow notification properties. Once again, with the soa-infra node selected, open the dropdown menu and select SOA Administration | Workflow Properties:

In the page that appears next, set the Notification Mode to All or at least to Email. Press Apply to make the change last.

Confirm the changed properties once again:

After making this change, I return to the page to send my test notification again. Unfortunately, the minor setback is still there. Perhaps a restart of the managed server for SOA Suite is required? I sincerely would hope not, but let’s try it anyways.

… after several minutes and one server restart …

Return to the page for sending a test notification:

and now it subtly informs me that the message was indeed sent:

Which I can confirm in my Outlook mail client:

Resources

Instructions on Using Gmail as a JIRA Mail Server (download certificate)

Probably the best resource – should have started there – Using GMail as Mail Server for Oracle SOA Suite 11g Notifications by Rommel Pino

Also very good: http://marcotello.com/oracle-soa-suite/configuring-oracle-soa-suite-ums-adapter-with-a-gmail-account/ by Marco Tello

Gmail Notification Service – Oracle Fusion Middleware School – http://www.orafmwschool.com/gmail-notification-service/

What Are the Gmail SMTP Settings? – http://email.about.com/od/accessinggmail/f/Gmail_SMTP_Settings.htm

How do I retrieve remote certificate with openSSL – http://www.madboa.com/geek/openssl/#cert-retrieve

Email Notification with SOA Suite 11g by Craig Barr of Rubicon Red – http://www.rubiconred.com/email-notification-soa-suite-11g/

How to register SSL certificates in your JVM? by Alexandre de Pellegrin – http://javacolors.blogspot.nl/2012/05/how-to-register-ssl-certificates-in.html