Distributed transaction sample: part 3 - preparation

Preparing Oracle and Windows for the distributed transaction. There's also some talk about transaction coordinators in this entry.

note: The Java CAPS and EJB parts of the sample application run in Sun GlassFish Enterprise Server (which comes with Java CAPS 6). To save a lot of typing I'll refer to it as GlassFish. An open source version of GlassFish is also available, and the sample can be run with that server as well. The open source version of GlassFish is included in OpenESB. The sample presented here should also work with OpenESB, but I have not tested that.

SoapUI

In the previous entry, about software installation and such, I forgot to mention installation of SoapUI. SoapUI is a tool that can be used to initiate web services. It can be downloaded here. On my system I have installed version 2.0.2.

SoapUI comes as a stand-alone application (that's the version I use), and as a plug-in for various environments. As Java CAPS 6 comes with NetBeans, you can install the NetBeans plug-in if you want to. For the stand-alone version, download the installer, and run it.

Oracle database

The Oracle database on my system is running with instance name oradb. The database runs on the local system (localhost) on the default Oracle port (1521. The table needed for the sample is stored in schema log (Oracle user log). If you want to use another instance name, another user, or run with an Oracle database on another system or on another port, you will have to change the WCF service. If you set up your database with the same properties, you can use the provided WCF sample without change.

One simple table is needed in the Oracle database. In the zip file found here you will find database scripts to create the log user (with password log) and its table, to clear the table, and to remove the user and its table. Please note that you must edit the creation script to provide the correct location for the location of the file containing the Oracle tablespace for the log user. Of course you can also change other things in the script, such as the user name and password. If you do make such changes, you must alter the WCF service application to reflect those.

The scripts can be executed with the Oracle SQL Developer tool, installed as part of the Oracle client (see the previous log entry for more on installing Oracle).

Transaction Coordinators

The example distributed transaction demonstrates a transaction where the activities are operations invoked via web services. Transactional behaviour in this sort of system uses the WS-AtomicTransaction (WS-AT) coordination type. In this sample, web services run in several different software environments. Each of those environments has its own transaction coordinator as shown in the picture below:

When bpProxy invokes bpMain, it will first register a new transaction with its transaction coordinator (TC). bpProxy runs in GlassFish, so the main TC for this transaction is the GlassFish one. bpMain is an atomic BPEL process. That means that when bpMain starts, it enlists in (joins) the existing transaction. It becomes part of that transaction. bpMain invokes several operations in ejbProxy. Operations in ejbProxy are specified to require an existing transaction, and therefore each of these operations also enlists in the existing transaction. Because up to now all activities took place in the GlassFish application server, the GlassFish TC is used by all these activities.

ejbProxy invokes operations on the WCF service. Each of these operations enlists in the existing transaction. However, this time a different TC, MSDTC (Microsoft Distributed Transaction Coordinator) is used. When an operation is invoked on the WCF service, MSDTC detects that a transaction is already active. In the WCF application the operations are specified as requiring an existing transaction. MSDTC communicates with the GlassFish TC, and together the coordinators ensure that the distributed transaction is dealt with in the proper way, with the GlassFish TC as the main TC. If the transaction would have been started by a WCF component, MSDTC would be the main TC.

The WCF service invokes Oracle. The Oracle activities participate in the existing transaction. Because the Oracle Data Access Components were installed, as mentioned in the previous entry, Oracle uses MSDTC to participate in the existing transaction.

When the last request has been processed by bpMain, control returns to bpProxy. The transaction is ended. Depending on previous events, the transaction is either committed (made permanent) or rolled back. The main TC (the GlassFish one in this case) would communicate to all participating TCs to ensure that all activities that have been executed in the transaction are committed or rolled back.

If bpProxy, bpMain, and ejbProxy would run in several GlassFish application servers, each would have registered with its own GlassFish TC. If other systems and environments would participate in the transaction, their TCs would be used (of course only systems that adhere to WS-AT can participate). The TC where the transaction was started would become the main TC. No matter how many TCs are involved, they would communicate to ensure proper management of the distributed transaction.

Certificates

Transaction coordinators need secure communication to ensure that no illegal parties get unrightfully involved in a transaction. To facilitate this, they use SSL as their communication protocol. Each TC authenticates the one(s) it communicates with by X.509 certificates.

To make this authentication possible, the public keys of the TCs must be present in the keystore of their counterparts. In our case we have two TCs. The GlassFish TC needs the public key of the MSDTC, and MSDTC needs the public key of the GlassFish TC. Each environment also has its own private key. During the SSL protocol certificates are exchanged and authenticated. The TCs use mutual authentication. When SSL keys are exchanged, public keys are used to encrypt data. The private key matching the public one is the only key that can be used to decrypt the data encrypted by using the public key. A simplified picture of the use of certificates (see the SSL protocol for how it really works):

The keys for GlassFish where created automatically when the domain was created during Java CAPS installation. For MSDTC the key must be created. Creating keys in Windows is done with the makecert command. A complete key consists of a private key and a public one. The private key must not be shared with other parties.

In certificate systems, a certificate must be authorised by a trusted certificate. These trusted certificates are called Certificate Authorities (CA). In our sample system we do not have an external CA. We can work in two ways: we can create one certificate that can then must be stored in both the CA keystore and the certificates keystore. Or we can create an authoritative certificate for our own little sample world, and sign the other certificate(s) we create with this CA certificate. Now the authoritative certificate should be stored in the CA keystore. When that is done, all certificates signed with the authoritative certificate will automatically be trusted. In this example, we will use the second method.

Please note that the commands in the procedure below may not always fit on one line. Please ensure that you issue the complete command, ignoring any line breaks.

• open a command Window
• navigate to the directory where you want to store your certificate files (preferably an empty directory)
• to save ourselves a lot of typing, let's set the location of the Windows SDK binary directory in an environment variable:
  set EXEC_DIR="C:\Program Files\Microsoft SDKs\Windows\v6.1\Bin"
• to create the authoritative certificate issue the following command:
  %EXEC_DIR%\makecert TempCA.cer -sv TempCA.pvk -a sha1 -n "CN=TempCA" -r -sky signature -pe -len 2048 -sr CurrentUser -ss My
• to create a certificate for msdtc, signed with the certificate created before issue command:
  %EXEC_DIR%\makecert.exe msdtc-ssl.cer -sv msdtc-ssl.pvk -a sha1 -n "CN=statler.muppets.local" -ic TempCA.cer -iv TempCA.pvk -sky exchange -pe -len 2048 -sr CurrentUser -ss My
  note: it is important to replace "statler.muppets.local" with the fully qualified domain name of he machine where your WCF service runs, because during the SSL handshake the FQDN of the machine sending the certificate and the CN in the certificate are compared, and the connection fails if they are not
• to package the msdtc certificate with its private key in a .pfx file (needed later) issue command:
  %EXEC_DIR%\pvk2pfx.exe -pvk msdtc-ssl.pvk -spc msdtc-ssl.cer -pfx msdtc-ssl.pfx -po changeit
  note: the password for the pfx file created will be "changeit"

The certificate for the GlassFish domain will also be needed in later steps. Portecle is used to export the certificate.

• start Portecle
• open the keystore for the GlassFish domain created when installing Java CAPS 6. The keystore and cacert files are found in the config directory for the domain (for example c:\jcaps6\appserver\domains\domain1\config)
  note: Portecle will prompt for the keystore password. The default password for the keystore is "changeit" (if you changed it during installation of Java CAPS 6, type your password instead of "changeit")
• right-click on the s1as certificate
• select export from the popup menu
• leave the dialog that appears unchanged, and click the OK button
• name the export file s1as.cer
• click the Export button to save the certificate in a convenient location (possibly the location where you created the msdtc certificates)

This looks like:

Now all certificates needed are stored in .cer files.

In GlassFish the MSDTC certificate (public key) is needed, and MSDTC needs GlassFish's public key and the key we created for MSDTC before (its private key).

While still in Portecle, we can import the msdtc-ssl certificate in the GlassFish keystore and cacerts files.

• open the keystore.jks file
• on the menu select Tools->Import Trusted Certificate...
• select the msdtc-ssl.cer file created earlier
• open the cacerts.jks file
• on the menu select Tools->Import Trusted Certificate...
• select the msdtc-ssl.cer file created earlier

The MSDTC certificate is now imported in the GlassFish keystore and root certificates file, ready for use by SSL.

To store the GlassFish public key and the MSDTC private key in MSDTC's keystore do the following:

• open the Certificates mmc snap-in (described in the previous entry)
• navigate to Certificates (Local Computer)\Trusted Root Certificate Authorities\Certificates
• right-click on Certificates (in the tree on the left) and select All Tasks -> Import...
• in the wizard that appears click Next
• click the Browse... button
• browse to the s1as.cer file exported before from GlassFish (using Portecle) and select that file
• click Next in the Certificate Import Wizard dialog
• without changing the options click Next again
• now click Finish
• click OK in the notification that the import is done
• right-click the newly added certificate. The name of the certificate will be the FQDN of your machine ("statler.muppets.com" in my case)
• select Properties
• set the Friendly Name to "s1as", type a description if you want to, and click OK
  note: this is an important step, because all certificates will be listed with the FQDN found in the certificate. If you don't change the friendly name, you'll not be able to tell the various certificates apart in several configuration tasks that follow
• repeat this procedure (from All Tasks -> Import...)
• this time select the TempCA.cer file, created earlier
• set the friendly name to "Temporary Certificate Authority"

This looks like this:

Setting the friendly name (and possibly the description) in the properties:

The Root Certificate Authorities are now imported and available to Windows. Now the certificates themselves must be imported. To import the GlassFish certificate, continue where we were before the pictures, and:

• navigate to Certificates (Local Computer)\Personal\Certificates
• right-click on Certificates (in the tree on the left) and select All Tasks -> Import...
• in the wizard that appears click Next
• click the Browse... button
• browse to the s1as.cer file exported before from GlassFish (using Portecle) and select that file
• click Next in the Certificate Import Wizard dialog
• without changing the options click Next again
• now click Finish
• click OK in the notification that the import is done

To import the MSDTC private key do the following (it s similar, but not exactly the same):

• right-click on Certificates (in the tree on the left) and select All Tasks -> Import...
• in the wizard that appears click Next
• click the Browse... button
• change "Files of type" to "Personal Information Exchange (*.pfx;*.p12)
• browse to the msdtc-ssl.pfx file created before and select that file
• click Next in the Certificate Import Wizard dialog
• type the password for the msdtc-ssl.pfx file ("changeit" if you did not change it), and check "Mark this key as exportable" (this last option is just for convenience) and click Next
• without changing the options click Next again
• now click Finish
• click OK in the notification that the import is done

All the necessary certificates are now available for MSDTC. Now MSDTC must be configured to use its certificate, and to allow GlassFish as its counterpart.

MSDTC configuration

To configure MSDTC, do the following:

• go to Start->Programs->Administrative Tools->Component Services (if you don't have Administrative Tools in Programs, you can enable it by right-clicking on the task bar and then customising the task bar)
• click on Component Services. A sub-entry called Computers will appear
• expand the Computers entry
• right-click on Computer and select Properties...
• in the window that appears, select the MSDTC tab
• click the Security Configuration... button
• in the window that comes up enable all check boxes (you can leave the Allow Remote Administration box unchecked if you want to)
• click OK
• if a message box appears that asks if it is OK to stop and restart the MS DTC service, click Yes
• select the WS-AT tab
• check the Enable WS-Atomic Transaction network support check box
• select a port that is not in use by other processes on your system (on my system I use 8001)
• click the Select... button for Endpoint certificate to select the endpoint certificate to use by MSDTC
• in the list of certificates, select the msdtc-ssl certificate (this is where the friendly name comes in handy! If you had not set the friendly name, you wouldn't be able to tell which if the certificates to select)
• click OK
• click the Select... button for Authorized certificates to select which certificates MSDTC will accept
• ensure that the s1as certificate is authorised (in the picture you will see all certificates authorised). Certificates are authorised by checking the check box in front of them. Friendly names allow you to distinguish the certificates.
• click OK
• if a message box appears that asks if it is OK to stop and restart the MS DTC service, click Yes
• click OK again
• if a message box appears that asks if it is OK to stop and restart the MS DTC service, click Yes

The windows described above look like this:

MS DTC is now configured, and ready to participate in our transactions.

Posted at 01:21PM Jan 05, 2009 by marjo in Distributed transaction  |  Comments[0]