The Rational Integration Tester HTTP Proxy: Recording HTTPS

This is the third in my series of blog posts on the Rational Integration Tester HTTP proxy.  If you need to catch up, see

I sketched out a plan for this series several weeks ago.  The topic of this third blog was to be Recording HTTPS.  In the meantime, John Chewter (one of the smartest guys I know, by the way), has written two articles on the IBM developerWorks site on Using SSL with Rational Integration Tester:

JC has crammed a bunch of really valuable guidance into these articles.  He reveals the secrets behind a lot of the magic of SSL and HTTPS communications and how Rational Integration Tester works with it.  These two articles are absolute must-reads before you go any further.  Since there is little value in me just repeating what JC already documented, I decided to try hitting this from a little different angle that builds on JC’s articles.  Armed with the knowledge he provides, let’s walk through a brief example applying these concepts to a reasonably realistic scenario.

Let’s say we have a client web application running on Tomcat that consumes a hotel provider web service.  In order to record the secure conversation and to later properly route requests to a stub, we will insert the RIT HTTP Proxy between the client and server. In this example, the client will require authentication from the service but the service will accept requests from anyone and will not require mutual authentication.

Simple Architecture configured for Proxy

Simple Architecture configured for Proxy

The proxy configuration

The Rational Integration Tester proxy configuration is controlled by the registration.xml file in the proxy’s installation directory (on Windows, the default is C:\Program Files\IBM\RIT-Platform\httptcp).  The area of the registration.xml file we want to focus on is the https-proxy section.

Portion of the registration.xml file

Portion of the registration.xml file

The outboundKeyStoreFile is used in mutual authentication schemes where the proxy must authenticate with a server.  Our example is a single-authentication architecture so outboundKeyStoreFile is not relevant in our case.

The keyStoreFile is what the proxy will use when it is acting as a server.  This is the primary role it will play in a typical server authentication scheme.  RIT ships with a preconfigured greenhat.jks keystore which contains a preconfigured key called mykey.  In other words, when the client application requests the proxy to provide its credentials for authentication, the proxy will send it the “mykey” public key.

As John mentioned in his article, you can certainly use this key for testing.  The only thing to consider is that your client app will need to be configured to trust it.  The other option is to use a key that is already trusted by the client – or more precisely, a key that is signed by a certificate authority that the client trusts.  Since John walked you through the latter, I will stick with the greenhat keystore and the mykey key.

Configuring the application client

We know we will need to add the greenhat certificate to the client’s trust store.  This will tell the client application that it can trust the proxy.  but first,  we need to know where the client’s trust store is.  Therefore we will verify and update the configuration of the client application first.

What you need to do will depend on what client technology you are using.  In this example, the client is a web application running in Tomcat.  Tomcat’s configuration settings are generally in the setenv.bat (or file used to launch it.  We add two JVM arguments to the launch configuration to cause Tomcat to route HTTPS communications through the proxy.  So if the proxy is running on a host at, we add the following lines:

JVM arguments to enable proxy

JVM arguments to enable proxy

Note that unlike in the last blog, the prefix of the directives is https, not http.  Also, the default port the proxy uses for HTTPS traffic is 3129, although this can be changed in the registration.xml file.

Within the file, we see existing truststore JVM arguments:

Tomcat client truststore configuration

Tomcat client truststore configuration

These directives tell Tomcat where to find the trust store and how to open it.  The trust store contains certificates for servers that can be trusted or certificates for certificate authorities that the client application can consider reputable enough to vouch for a server.  This is where we will need to add the greenhat certificate which will enable the client to trust the proxy.

Exploring the keystore

System administrators will commonly use tools like the Java keytool program to manipulate keystores.  But RIT has a tool built into the UI that enables you to manage your configuration from within the project.  To use it, open the Physical view of the Architecture School perspective. Under the General toolbar, select Identity Store.  Use the Select browser to locate the wwtravelTrustStore.jks file.  You will be prompted for a keystore password.  This is the password in the setenv.bat file, above.

You will find at least one existing certificate in the trust store: wwtravel.  This is the certificate for the hotels server host which tells the client it can trust the hotel service.  We use the Import Key/Certificate(s) button to import the greenhat.cer file provided with RIT.  This certificate corresponds to the “mykey” public key that the proxy will send when the client attempts to open up a conversation with it.

identity store for wwtraveltruststore.jks

identity store for wwtraveltruststore.jks

Bounce the Tomcat server to get the changes to take effect.

Now you may be looking back at the simple architecture diagram at the beginning of this post and wondering why we need to go through all this work for the connection on the left side but not the connection on the right site.  Don’t we need to add the server’s certificate to the proxy so that the proxy will trust it?  To avoid putting you through all that, the RIT proxy is designed to “trust anybody”.  In other words, when the server sends its public key to the proxy, the proxy will accept it, no questions asked.

While we are in the Physical View, we will create an Identity Store for the greenhat.jks keystore as well.  We will need to reference that when we create the RIT model.  The keystore password is “passphrase”.

Identity Store for greenhat.jks

Identity Store for greenhat.jks

Verify the configuration

With the proxy settings configured on the client, the proxy configured to supply an SSL key when requested and the client’s trust store configured so that it will accept that key, everything should be functional.  The client should be able to make requests of the live service and get responses with the messages being passed through the proxy.  You should run two tests to verify your setup at this time:

  • With the proxy stopped, verify that the client is unable to make a request of the service.  This proves that you have all the plumbing configured correctly.  If the client can get a response from the service with the proxy stopped, it is bypassing the proxy.
  • With the proxy running, verify that the client can make a request and get a response from the service.  This proves that you have all the authentication set up right.

Configuring the RIT model

Next, we will configure the model in Rational Integration Tester for recording.  This is done just like it was for HTTP with one additional step.  On the SSL tab of the Web Server physical resource, you much check “Use SSL”.  This tells RIT tests to invoke the SSL handshake when they connect to the service.

There are two groups of SSL settings on the Web Server SSL tab that affect how RIT operates in an SSL environment.  The Provided Certificates area defines how RIT should behave when it is acting as a Server.  In other words, if you will run stubs on this endpoint, these settings will be used to define which key in which keystore RIT will send to the client when asked to identify itself.  Check Specify Provided Certificate; select the greenhat.jks keystore and the mykey key.

HTTPS Web Server physical resource

HTTPS Web Server physical resource

The Trusted Certificates group defines how RIT should operate when acting as a client.  RIT’s default behavior for tests is again to “trust anybody”, but you can override that behavior by specifying trusted certificates or verifying the certificate chain.

Recording HTTPS

With the keystores and model settings in place, recording HTTPS is really no different than recording HTTP.  Create an event monitor by right-clicking on the element in the Logical View and start recording in the Recording Studio perspective.  Because the proxy is acting as a “man in the middle”, it sees and records the messages in clear text.  You can modify tests and stubs based on those recordings just as you would plain text artifacts.

So working with SSL shouldn’t be scary.  It will require some understanding of the components of SSL (keystores, certificates, keys, etc.) and some understanding of the handshake process, but that should be expected.  If you are performing component-level integration tests, you will need to know how those components interact with each other – at least long enough to configure RIT.  Once the plumbing is in place, RIT makes it easy to work with data in plain text.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s