Sunday, June 10, 2012

MQ Adapter and SSL - Part 1

Oracle MQ Series Adapter enables applications to connect to MQ Series queue managers and enqueue/dequeue messages to/from the Queues. MQ Series supports secure communication through the use of SSL. SSL stands for Secure Socket Layer. Oracle MQ Series Adapter can be easily configured to support SSL to secure the data-communication between Adapter and Server.

The article further explains some general concepts of SSL on MQ Adapter and points how you can enable SSL on Oracle MQ Adapter.

There are 2 types of SSL that can be configured on MQ Adapter:

One-Way SSL: 
In this SSL pattern, only the server gets authenticated. This ensures that the server to which MQ adapter is connecting is valid and correct. When MQ Adapter connects to MQ server, it requests the MQ server-certificate. On providing the certificate by MQ server, MQ Adapter verifies and matches it against the list of certificates available with it in its store. If the certificate match is found, the certificate is considered valid and the SSL connection is established.

Two-Way SSL:
In two-way SSL, both Client and Server are authenticated. The connection process is very similar to One-way SSL except that client is also authenticated in two-way SSL. When MQ Adapter connects to MQ server, it requests the server-certificate. MQ server provides the appropriate certificate. This certificate is verified by the MQ Adapter against the list of certificates available with it. After this certficate is validated by MQ Adapter (client), MQ server (server) then requests the client certificate to ensure that the requesting client is also valid. MQ Adapter, then, presents its certificate to MQ server which is verified by the server against the list of certificates available with it. If both the client and server certificates are found valid, SSL connection is established.

Two-way SSL is always enforced by the server. Hence, to enable two-way SSL on MQ Series, MQ Server needs to enforce Two-way SSL on incoming channel. On the server side, set the property Authentication of Parties initiating connection to Required as shown in the screenshot. This will enforce the clients connecting to it to present their certificates for validation before an SSL connection can be established.

Also ensure that this channel must be of Server-connection type. Contact your MQ Server Administrator to confirm this.


Further, to configure One-way or Two-way SSL on MQ Adapter and simultaneously keeping this post short and sweet, follow another post Enabling SSL on MQ Series Adapter - Part 2.

Enabling SSL on MQ Series Adapter - Part 2

I've already explained the basic concepts in MQ Adapter and SSL - Part 1. This post explains how you can configure your MQ Adapter to use One-way or Two-way SSL.  To enable One-way or Two-way SSL on MQ Adapter, following steps need to be followed. I'm outlining the simplest possible steps. Once understood, they can be modified based on your security needs.
  • Get the Public certificate (.DER, .CER) of the MQ Server Queue Manager. Ask your MQ server Admin to give this to you.
  • Import this certificate into default Weblogic Trust store or you custom keystore if any (all Public certs are stored here because Weblogic trusts the certs imported here) at <WL_HOME>/server/lib/DemoTrust.jks using the following command. You need the keytool utility to execute following commands.
keytool -import -alias <choose_name_for_this_entry> -file <public_cert_received> -keystore DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase
  • Verify the imported certificate by running following command. Your entry should be present here. 
keytool -list -v -keystore DemoTrust.jks -storepass DemoTrustKeyStorePassPhrase
Note: Below 3 steps are required only for configuring Two-way SSL on MQ Adapter. For One-way SSL, you must skip these steps.

For Two-way SSL, you need to provide Weblogic Public certificate to MQ server Admin team so that they can import it in MQ Server's Trust store. Follow the additional 2 steps for Two-way SSL.
1. Extract the PUBLIC certificate of your Weblogic from its identity and give this certficate to MQ Server team.
keytool -export -alias demoidentity -file WLS_PUBLIC_CERT.der -keystore <WL_HOME>\server\lib\DemoIdentity.jks -storepass DemoIdentityKeyStorePassPhrase
2. Ask MQ server Admin to import the given certificate into the Server Trust store being used by the Queue Manager that you connect to.
 3. Ensure that the Private key and Identity Keystore passwords of your Keystore are same. Hence, change the keystore password to the Private key password by executing the following command.
keytool -storepasswd -new DemoIdentityPassPhrase -keystore <WL_HOME>\server\lib\DemoIdentity.jks
  • Next step is to create a simple BPEL process with MQ Adapter that connects to MQ using a JNDI configured on Weblogic Server. The key to configure SSL on MQ Adapter lies in this JNDI only.  To create a JNDI for MQ Adapter,  Follow How to create MQ Adapter JNDI . 
  • Once the JNDI is configured successfully and tested with a dummy BPEL process, edit the following JNDI properties. Remember to hit Enter after updating each property.
S. No
Property Name
Property Value
Description
1
channelName
<Channel Name>
The name of the channel which is of server-conection type. Ask your MQ Server Admin to provide with this detail. Your process will connect to this channel.
2
CipherSuite
SSL_RSA_EXPORT_WITH_ RC4_40_MD5
Cipher suite that will be used for Message Encryption. Ensure that this is same as CipherSpec set on the above channel. e.g. for CipherSpec to be set on Server Connection Channel for the mentioned CipherSuite is RC4_MD5_EXPORT
3
hostName 
<Host Name>
The host name of the MQ server
4
KeyStoreLocation
<Keystore Location>
For One-way SSL, specify this to the location of the keystore in which you imported the Public certificate of the MQ Server (in our example DemoTrust.jks). This property will be same as TrustStoreLocation in One-way SSL.

However, for Two-way SSL, specify the location of Identity keystore (in our example DemoIdentity,jks)
5
KeyStorePassword
<Keystore Password>
Specify the password to access the above keystore
6
KeyStoreType
jks
By default this is Java Keystore (jks). Ensure you create the Keystore of the .jks type.
7
password
<Password to access MQ>
Specify the password to access the MQ Server
8
portNumber
<MQ Server Port>
Network port to connect to MQ server
9
Protocol
TLS
The algorigthm used to manage the Keys. Default Value is TLS. Keep it as it is.
10
queueManagerName
<Queue Manager name on MQ Server>
Queue Manager provides access to the queues and also transfers messages to other queue managers through message channels.
11
SSLEnable
true
Set this value to true to tell MQ Adapter to use SSL
12
TrustStoreLocation
<Keystore Location>
Provide the Trust keystore location (e.g. /dir/DemoTrust.jks) in which you imported the PUBLIC cert of the MQ Queue Manager.
13
TrustStorePassword
<Keystore Password>
Provide the password for Trust Store
14
userID
<username to connect MQ>
User Id to access MQ server
15
XATransaction
false
By default this is False
  • Save the properties and Update the Adapter as given in create JNDI post.
And it's done. This will enable One-way SSL (or Two-way SSL) for your MQ Adapter communication.

Troubleshooting:
  • In case you encounter any errors, set the following EXTRA_JAVA_PROPERTIES in setDomainEnv.sh (or setDomainEnv.cmd) file and restart the servers.
set EXTRA_JAVA_PROPERTIES=%EXTRA_JAVA_PROPERTIES% -Dssl.debug=true -Dweblogic.StdoutDebugEnabled=true -Dweblogic.security.SSL.verbose=true
  • This will generate verbose logs for SSL to help you diagnose the errors. See the below logs for diagnosis.
<DOMAIN_HOME>/servers/soa_server1/logs/soa_server1.log
Still if you encounter any problems, I'm happy to help!

How to create a JNDI for MQ Adapter on Weblogic

This post explains how to create a simple JNDI for MQ Adapter in Weblogic 10.3.x. This JNDI properties can be further changed to configure One-way or Two-way SSL on MQ Adapter as explained in post Enabling SSL on MQ Series Adapter - Part 2.
  • Login to Weblogic Server Administration Console and navigate to Deployments > MQSeriesAdapter > Configuration Tab > Outbound Connection Pool.


  • Click on New button and select javax.resource.cci.ConnectionFactory and click Next.
  • Give an appropriate JNDI name and press Finish. This JNDI name will be used by your MQ Adapter inside the BPEL process. If it asks to Create/Save a Deployment Plan, Create/Save a deployment plan for this JNDI reference.
  • Go back to the MQSeriesAdapter > Configuration Tab > Outbound Connection Pool and expand the connection factory  javax.resource.cci.ConnectionFactory. Click on the JNDI created by you above.


  • Set the following properties for the above created JNDI. Leave the other properties to their default. Remember to hit Enter after updating each property. 

    S. No
    Property Name
    Property Value
    Description
    1
    channelName
    <Channel Name>
    The name of the channel which is of server-conection type. Ask your MQ Server Admin to provide this detail. Your process will connect to this channel.
    2
    hostName 
    <Host Name>
    The host name of the MQ server
    3
    password
    <Password to access MQ>
    Specify the password to access the MQ Server
    4
    portNumber
    <MQ Server Port>
    Network port to connect to MQ server
    5
    queueManagerName
    <Queue Manager name on MQ Server>
    Queue Manager provides access to the queues and also transfers messages to other queue managers through message channels.
    6
    SSLEnable
    false
    By default this value is false. As we're not using any SSL in this post, leave this value as false.
    7
    userID
    <username to connect MQ>
    User Id to access MQ server
    8
    XATransaction
    false
    By default this is False. Keep it false unless you want to enable global transactions on this adapter.

  • Save the properties by hitting the Save button at the bottom of the properties page.
  • Navigate back to Deployments and check MQSeriesAdapter. Now press Update button on the top.
  • On the next page, choose to Redeploy this application using the following deployment files and hit Finish.
After the JNDI is created successfully and properties are set as above, use this JNDI in a simple BPEL process to enqueue a message in MQ. If this is successful, JNDI configuration is correct.

Monday, May 21, 2012

Multiple IN parameters in DB Adapter Dynamic Query


I explained how to pass the multiple parameters to IN clause in Pure SQL here. However, the solution needed to assign the same input string to bind parameter #val 9 times. Later on while browsing Oracle Forums, I came across a more-refined query that would address this concern.

To select employees with f_name as 'NEERAJ' or 'JACOB' or 'ROBERT', write your Pure SQL in DB Adapter like below. This would create DB schema automatically further to which you might need to specify the type of the bind parameters as xs:string in this schema.

Now, invoke the DB Adapter and using the Assign activity , assign the bind parameter values in the above query as under:

#InputString - Your Input String with delimiters (but no spaces) e.g. 'NEERAJ,JACOB,ROBERT'
#Delimiter1 - Assign the delimiter e.g. ','. This is to suffix above string with same delimiter.
#Delimiter2 - Assign the same delimiter e.g. ','

And that's it. Invoke your process and test it. Happy Learning....


Tuesday, May 1, 2012

Changing the Archive File Name in Inbound File/FTP Adapter


Requirement:

To customize the archive file name, remove the junk characters from the archived file name. The default format is as under.

SOA 10g - filename_yyyymmdd_hh24mmss
SOA 11g - filename_encryptedToken_yyyymmdd_hh24mmss (new format introduced with 11g)

The possible customization is given in the solution below.

Solution:

SOA 10g

You have a JCA property for FIle/FTP adapter, UseLongArchiveFileName, which can be used to prefix the process name to the archive filename to make the format filename_processname_timestamp.

SOA 11g (11.1.1.3/+) 

UseLongArchiveFileName is not available in 11g. Apply Patch 10155914 and it will become available.    

SOA 11g (11.1.1.5/+) 

Apply Patch 13249896.
A new property  UseDigest can be used now in addition to  UseLongArchiveFileName (11g format as filename_processname_digest_timestamp) with File/FTP adapter.
By default UseDigest is set to true which leads to the digest (encrypted token) being sandwiched in the filename and timestamp as filename_digest_timestamp.
Setting this property to false will change the format to filename_timetamp. To use this property edit the .jca file to include this property as given below.

SOA 11g (11.1.1.7/+)

UseDigest property will be available by default without the need to apply the above patch.

There is, however, no further customization possible (presently) in terms of adding instance id to the file name or specifying custom file name. Hope the same gets available in the 11.1.1.7(+) or 12C version.

Tuesday, April 10, 2012

Polling files on-demand : File Based Triggers

Many a times there is a need to trigger the polling of File/FTP Adapter on the basis of some event e.g. after process A has finished writing the file F1, process B should poll for the file F1 OR just process the files only between 10.00 AM to 11.00 AM. While the above could be accomplished to some extent using Sync Read operation, but it requires the knowledge of the File Name in advance (wild cards can't be used).

Well, the solution is File-Based Triggers. File-based triggers can be used to control the File/FTP adapter activation. File Triggers are nothing but the files with .trg extension. The content of trigger file doesn't matter. When File-based triggers are used, File/FTP adapter checks for the existence of a Trigger file (e.g. ReadFile.trg) before reading the actual file. If the trigger file is found, it reads and processes the actual file else it does nothing. You can configure how frequently the adapter checks for the trigger file and hence can control the processing of the actual files.
To use a File-Based trigger, follow the below steps.
1.) Define a File/FTP adapter with Read Operation.
2.) On the File Polling page, Check the option Use trigger file and provide the Trigger File details as shown below.

3.) Complete the adapter wizard.
4.) Follow the normal steps to create a bpel process to poll the file. Deploy this process.

As soon as the process is deployed, File/FTP adapter looks for the trigger file in the C:/TriggerFileDir location. If it finds the triger file, it will poll and process the file. How frequently it looks for the trigger file depends on the property TriggerFileStrategy (we didn't specify this property anywhere because the property is set already by default to value EndpointActivation).

The various possible values for TriggerFileStrategy are:
OnceOnly: The adapter will looks for the trigger file only once in its lifetime. Once it finds the trigger file, it remembers that across restarts and redeployments. This could be very risky as the adapter would never look for a trigger file again in future.

EveryTime: The adapter looks for the trigger file everytime it goes for polling the file. At every polling interval, it checks if the trigger file is there or not. If the trigger file is present, it picks the actual file else it will do nothing and will check for the existence of trigger file at next polling cycle.

EndpointActivation (Default): The adapter looks for the trigger file every time the composite is activated that means everytime you Restart/Activate/Redeploy your composite.

Add the property in .jca file of your File Adapter as shown below and it's done.

Note: You may want to delete the Trigger file after your file has been successfully processed. For this, there is no Delete operation. But you can use Sync Read operation to read the trigger file and check Delete Files after successful retrieval option.

Happy to hear back if any suggestions or comments!

Sunday, January 22, 2012

Sending attachment using Email Activity in BPEL 11g

Sending an attachment using Email Activity (in SOA 11.1.1.5) is an easy task. All you have to do is drag and drop an email activity and double click on it. Assign the following parameters and the attachment will be sent along with the email.
Name- Name of the attachment as it should appear
MimeType- This MimeType is for attachment. Choose appropriate MimeType from here.
Value - Write what you would like to see in the attachment. Simply hard coding.

Well, sometimes the requirement may be to send some custom data, may be you fetched some data at runtime from the DB and would lke to send it as attachment. This isn't complex either, all you have to do is modify the ContentBody parameter as follows. You can do this successfully from the EmailParamsAssign Activity but don't forget to verify the same in the bpel source too.


Extending this a bit further, if you'd like to send some files (image,pdf,doc,xls,csv) that are already stored at some server location or you may have written them from your process, follow these  steps.
1.) Set the appropriate MimeType for the file.
2.) Add the following line in the .bpel source under appropriate BodyPart.

3.) Add another copy operation in the bpel source to assign string('base64') to ContentEncoding in BodyPart[2].

4.) Modify the  ContentBody  parameter to read the file at runtime using ora:readFile() function as follows.


Key Points to Note:

  • The file location and name in ora:readFile() above are case-sensitive.
  • Specifying the correct MimeType is very important. If the MimeType is incorrect, either the mail won't go or you may get encrypted characters in the attached file.
  • file:/// (three slashes mean absolute path and two slashes mean relative path)

The above solution works with all the files. Should anyone need the working project, I can mail the same. 

Inserting a New Line character in message using BPEL XSLT

In a requirement, we were trying to format the data fetched from DB (in XML format in BPEL) into a String variable with a new line inserted after each record. So that the data below would appear in the String variable like Following is the simple transformation to achieve the same.

<xsl:for-each select="/ns0:SelectFromLookupOutputCollection/ns0:SelectFromLookupOutput">
<xsl:value-of select='concat(ns0:property_name, ",", ns0:property_value,"&#10;")'/>
</xsl:for-each>

Key Points to Note:

  • The magic lies in the word &#10; which serves as a new line character in XSLT (11g). In above case, it gets appended at the end of each record resulting in new line at the end of each record.
  • The function somehow doesn't work in SOA Suite 11.1.1.3 (BUG-13602524, thanks to my colleague Nivea for identifying this) but works in 11.1.1.4 and older versions.


Tuesday, January 17, 2012

How to pass JNDI name dynamically to an Adapter

Recently, I've been trying configure an MQ adapter that could enqueue data of any structure into specified queue based on the specified JNDI, all passed dynamically at runtime. This post decsribes how you can pass the JNDI Name dynamically to an Adapter.

All you have to do is define a
String variable (say myJndiName) that stores your JNDI name (eis/MQ/someThing...already configured on Weblogic) and pass this variable into Invoke Activity properties directly in the .bpel source.   

Note that you'll not be able to find this property in the
Invoke Activity > Properties tab.


And that's it. You can assign different values on the fly to the variable myJndiName and same adapter can enqueue in different JNDI locations. It also works for FTP and JMS adapters too.