SOA Suite 12c: Configuring GMail as the inbound email provider for UMS (IMAP, SSL)

In a recent article, I discussed how to configure the SOA Suite 12c for sending emails using GMail: https://technology.amis.nl/2014/08/05/setup-gmail-as-mail-provider-for-soa-suite-12c-configure-smtp-certificate-in-trust-store/. An interesting aspect of that configuration is the loading of the GMail SSL certificate into the Keystore used by WebLogic, in order for the SSL based interaction with GMail to successfully be performed. The configuration of GMail for inbound interactions requires a similar procedure for the certificate for the imap.gmail.com server.

This article quickly presents the steps required for getting this inbound interaction going, from the expected error:

<Aug 17, 2014 3:50:22 PM CEST> <Error> <oracle.sdpinternal.messaging.driver.email.inbound.ImapEmailStore> <SDP-26123>
ould not initialize Email Store for: user saibot.airport@gmail.com, server imap.gmail.com, folder INBOX, sslEnabled tr
javax.mail.MessagingException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.prov
er.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target;
  nested exception is:
        javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun
ecurity.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
        at com.sun.mail.imap.IMAPStore.protocolConnect(IMAPStore.java:665)
        at javax.mail.Service.connect(Service.java:295)
        at javax.mail.Service.connect(Service.java:176)
        at oracle.sdpinternal.messaging.driver.email.inbound.ImapEmailStore.initStore(ImapEmailStore.java:159)
        at oracle.sdpinternal.messaging.driver.email.inbound.ImapEmailStore.initStore(ImapEmailStore.java:106)

to the final successful reception of an email:

 

Load Certificate into Keystore

The interaction between the UMS server and GMail’s IMAP API takes place over SSL. That means that the WebLogic managed server on which the UMS service runs has to have the SSL certificate for the IMAP server loaded in its local keystore – in the exact same way that we needed to load the SMTP server’s certificate in order to be able send emails via GMail (https://technology.amis.nl/2014/08/05/setup-gmail-as-mail-provider-for-soa-suite-12c-configure-smtp-certificate-in-trust-store/).

The steps are a little familiar by now,  at least to me.

Download the certificate from Google and store it in a file. Depending on your operating system, this can be done in various ways. On Linux, here is a possible command:

openssl s_client -connect imap.gmail.com:993 > gmail-imap-cert.pem

The file gmail-imap-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.

Open the file you retrieved with OpenSSL – gmail-imap-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-imp-certificate.txt (but you can pick any name you like).

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, in my environment at least:

/usr/java/latest/jre/bin/./keytool -import -alias imap.gmail.com -keystore /opt/oracle/middleware12c/wlserver/server/lib/DemoTrust.jks -file /var/log/weblogic/gmail-imap-certificate.txt

The default password for the 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:

When done, we can check the contents of the keystore using this command:

/usr/java/latest/jre/bin/./keytool -list -keystore  /opt/oracle/middleware12c/wlserver/server/lib/DemoTrust.jks

Next, you have to restart the WebLogic Managed Server – and perhaps the AdminServer as well (I am not entirely sure about that, but I did it anyway)

 

Email Driver Properties

In EM FMW Control, open the User Messaging Service node in the navigator and select the usermessagingdriver-email for the relevant managed server. From the context menu, select Email Driver Properties. When there no configuration yet, you will create a new one. If you already configured the SOA Suite for outbound mail traffic, you can edit that configuration for the inbound direction.

 

In the property overview, there are some properties to set:

The Email Receiving protocol for GMail is IMAP. The Incoming Mail Server is imap.gmail.com. The port should be set to 993 and GMail wants to communicate over SSL, so the checkbox should be checked. The Incoming MailIDs are the email addresses that correspond to the lust names under Incoming User IDs. For GMail these can both be the full GMail email-addresses, such as saibot.airport@gmail.com, an account created for the Oracle SOA Suite 12c Handbook that I am currently writing. There are several ways to configure the password. The least safe one is by selecting Use Cleartext Pasword and simply typing the password for the GMail account in the password field. The password is then stored somewhere on the WebLogic server in readable form.

Press the OK button at the top of the page to apply all configuration changes.

 

SOA composite application with Inbound UMS Adapter binding

I have created a very simple composite. The (really the only) interesting aspect is the Inbound UMS Adapter on the left. This adapter binding when deployed negotiates with the UMS services on the WebLogic platform to have the configured mailbox polled and to have an instance of this composite created for every mail that was received. Note that we could have configured message filters to only trigger this composite for specific senders or subjects.

The inbound UMS adapter is configured largely with default settings – apart from the name (ReceiveEmail), the steps through the wizard are these:

Specify which of the accounts that are configured on the UMS email-driver is associated with this particular adapter binding (note: this means that the value provided here for the end-point has to be included in the Incoming MailIDs property set on the email driver)

Let’s process the mail content as a string – no attempt to natively transform. Note that many associated properties are available inside the SOA composite from the jca header properties.

Do not need Message Filters for this simple test:

Nor any custom Java to determine whether to process it. See for example this article for details on this custom Java callout: https://technology.amis.nl/2013/04/07/soa-suite-definitive-guide-to-the-ums-adapter-11-1-1-7/ 

Press Finish to complete the adapter configuration.

Deploy the SOA composite to the SOA Suite run time. Send an email to the address that is being polled by the inbound UMS adapter:

Wait for a little while (about 15 seconds on average, with our current settings). Then check the EM FMW Control for new instances of our composite:

And check the contents of the message processed by the Mediator:

and scroll:

Yes! We did it.