Domains, Environment and Projects – Administration

This is a follow-up to my previous post Domains, Environments and Projects – making sense of it all.

Now that we understand the purpose of Domains and their related artifacts in the Rational Test Control Panel, let’s take a look at how we can make use of them.

Visibility

Again, as described in the KnowledgeCenter, A domain represents a logical grouping of related systems that are part of a real business project and it is the basic unit of management within IBM Rational Test Virtualization Server.  In the last post, I mapped each organizational division to a domain.  This will enable JKE to organize which stubs are published and visible in which domains.  That will help us make only relevant stubs visible to the various teams.

Security Access

Domain-level security is disabled by default.  As an administrator, go into the Administration > Security tab of Rational Test Control Panel and enable it.

Enable Domain-level security

Once enabled, any user that is not specifically added to a domain will not have access to anything in that domain.

No domains for unauthorized user

Users are added to domains in the Administration > Domains and environments area by selecting the domain and then the Users sub-menu and clicking the green add icon.  Users can be given three levels of access: Domain administrator, User and API User.

Add a user to a domain

Now that user will see any available domains in the domain selection box at the upper-right of RTCP.

Domains available to a user appear in the domain selection list

With this in place, you not only provide visibility constraints, but also access constraints.  But, access constraints apply not only to users, but to proxies and agents as well.  Since we have not yet configured any proxies or agents for domain-level security, they cannot register to domains or environments within those domains.  If our domain user looks at the Environments tab (was VIE tab prior to v8.6), he will see this message:

No agents registered for this environment

This brings us to our third use for domains – controlling access to services.

Proxy/Agent access control

Proxy and Agent access control is implemented with security tokens.  An administrator creates a security token which is used by the proxy or agent to authenticate to RTCP.  The security token’s permissions determine which domains the proxy or agent can register with.  The security token is associated to a user when it is created.  The proxy or agent therefore gets the access of the user who corresponds to the security token being presented.

As an administrator user, create a token in the Administration > Security tab.  Select the user to which the security token will be bound and enter a description for the token.

Create user security token

Now provide the security token to the proxy or agent configuration settings.  For proxies, this is done by pasting the security token string into the security-token attribute of the server element of the registration.xml file for the proxy.

Adding the security token to the proxy registration.xml file

For agents, this is done by pasting the security token string into the security-token attribute of the rtcpURL element of the Agent.config file for the agent.

Adding the security token to the Agent.config file

Restart any proxies or agents you have modified.  The proxies and agents started using this security token will be visible in all domains and environments, but they can only be used in domains where the user associated with the security key has permissions to work.

Proxy/Agent visibility

A proxy or agent’s visibility can be restricted as well.  This is done by the domains element in the proxy’s registration.xml or the agent’s Agent.config file.  For example, to cause my proxy and agent to only be visible to the Mobile Banking domain, I would add the following:

Restricting proxies or stubs to a specific domain

You can further restrict a proxy or agent’s access to only given environments within a domain.

Restricting proxies or stubs to a specific environment within a domain

Wrapping it all up

Now this becomes really powerful.  So consider again our multiple JKE teams all trying to build client applications that leverage the same payment calculator service.  Each team wants to use a stub for the payment calculator service, but they each want their own variant of that service.  The domain architecture of Rational Test Control Panel and the
ability to control which domains the proxies and agents can register into would enable each team to have their own personal proxy/agent pair visible only in their domain.  The members of each team would have permissions to their own domain.  Each team would publish and run their own Payments Calculator stub to their own domain.  Now, without changing the endpoints of any of the client applications, each team’s proxy will route requests from their client to their stub.  There are all sorts of options where multiple domains could share proxies and agents, thereby enabling them to use a common stub.  This could be part of a strategy to use incremental integration testing at an enterprise level.

Domains with separate and shared proxies

The Rational Integration Tester HTTP Proxy: Recording HTTP

This blog post is the second in a series about the Rational Integration Tester HTTP Proxy.  If you are just now joining us, I suggest you drop back and first read

The Rational Integration Tester HTTP Proxy: What is it?

Now that we have covered what the proxy is, what it is used for and the basics of installing it, we will look deeper into using the proxy for its first application – recording.  There probably is no better way to describe how the proxy works than “man in the middle”.  That term strikes fear into most people.  You think of malicious attacks on web sites bent on malfeasance.  In such attacks, a 3^rd party finds a way to convince a client application to allow it to listen in as that client talks to a service it uses.  In an attack like that, the goal is to enable the 3^rd party to harvest information in those messages.  Although the Rational Integration Tester HTTP proxy uses the same general approach, you are the 3^rd party and the purpose of harvesting information in those messages is ultimately to create either tests that replicate the client or stubs that emulate the service.

Yes, there are security implications here.  And that’s exactly why you really need to understand what is going on and how to ensure you are only giving the Rational Integration Tester HTTP Proxy access to your messages.  The next post in this series will dig deeper into security, but we need to get a foundational understanding of how to set up an unsecured system first and then build on that.

Overview

The overall process you will follow consists of the following steps:

1. Understand the System Under Test (SUT)
2. Configure the client to route requests through the proxy.
3. Verify the SUT works correctly with the proxy in place.
4. Model the endpoint in Rational Integration Tester and verify you can access the service.
5. Use RIT to record as you send messages to the service by exercising the client.

The Process

Understanding the System Under Test

This probably sounds obvious.  Of course you need to understand the system you are testing.  But the system you want to test is probably a complex mishmash of subsystems and sub-subsystems sending messages through all sorts of protocols and message formats.  What do you need to know about the system and what is just extra information that doesn’t help?  Ultimately any given communication path you want to record boils down to a client sending messages and receiving responses from a service. Let’s consider a simple example where a web client application running in Tomcat consumes a service that provides hotel search and booking:

Simple Communication Architecture

The key details you need to know are the hostname of the server hosting the service and the port number on which the service listens.  In the example, the hotel service runs on a fictitious server called myHotelServer.com on port 8089.  Once we start considering authentication and security, there will be other things you will need to know, but we will get to that later.

Configuring the client

Recording messages with the proxy requires that you reconfigure your System Under Test (SUT) a bit.  This might sound like invasive testing.  The thought that you must tweak your system in order to enable testing might rub you the wrong way.  But then again, think about it this way: should your SUT allow just anyone to tap into the wire and record messages?  Rest assured that Rational Integration Tester – or any other tool – can’t somehow sneak into a properly configured and secured system to record data.  You must deliberately configure your system’s client to allow this recording to occur.  This is a necessary thing – and a good thing.

The specific steps required to configure your client will depend on the container your client runs in.  Some specific technologies are addressed in the InfoCenter.  In the case of most Java-based containers, you will be able to add two Java startup switches to the command line that launches the container and then restart the container.  For our example where the client is running in Apache Tomcat, we would add the following switches to the script that launches Tomcat:

-Dhttp.proxyHost=myHotelServer.com –Dhttp.proxyPort=3128

Note that the InfoCenter recommends editing catalina.bat or catalina.sh.  I prefer to keep environment settings like this localized to the setenv.bat or setenv.sh scripts.

Simple Architecture configured for Proxy

As long as your client application correctly uses the standard Java HTTP client libraries, this will cause it to route messages through the proxy.  There are many corner cases where simply setting these two switches will not be sufficient.  This all depends on how the client is implemented.  For now, let’s assume this works for our example.  Troubleshooting these corner cases may be a good topic for a future blog article.

Verifying the System Under Test

Before you go any further, it is very important that you verify that A) you haven’t broken your SUT and B) messages are actually routing through the proxy.  It is easy to make typos when modifying textual startup scripts so double-check your edits.

Start the Rational Integration Tester HTTP proxy.  As we discussed in the previous blog article, you normally want to have the proxy installed as a Windows service and have it start automatically upon boot.  Now is a good time to NOT do that.  Go to the Windows Services and stop the IBM RIT HTTP Proxy service.  Now navigate to your proxy install location (C:\Program Files\IBM\RIT-Platform\httptcp by default) in a command prompt and launch startup.bat.  Many lines of logging information will scroll by.  This may be worth referencing later if you have problems.

If you haven’t done so already, restart your client application.  You will need to restart for the startup directives to take effect.  It is worth checking log files in your client that might indicate whether or not the client picked up your startup directives.

Now try invoking the service from the client.  The first thing to verify is that the client gets the response you would expect and does not get errors.  If your client isn’t able to send the request or get a response back, then you broke something.  One thing to verify is that you started the proxy.  If the proxy isn’t running, no messages will get through.

Secondly, check the command window where you launched the proxy.  You should see a number of new logging messages.  In particular, look for the string “proxy rule found: Proxy on port 3128”.  This indicates that the request made it from the client to the proxy.  Further down in the messages you should see something like “Sending request message to endpoint”.  A little further down you should see “Reading response message from endpoint”.

Proxy messages indicating a successful route

Don’t bother proceeding if this isn’t happening for you.  There are a number of possible reasons that messages aren’t getting through.  Firewalls are common blockers.  You will need to correct the situation because nothing beyond this point will work.

Configuring the RIT model

With the proxy in place and verified, we are ready to model the system in Rational Integration Tester in preparation for recording.  I wrote some weeks ago about the model in Rational Integration Tester.  Since this post is about the proxy, I’ll stick to the bare minimum modeling and focus on what we need to get a recording.

At a minimum, you will need a logical HTTP Connection and a physical Web Server in your model.  Create the HTTP Connection in the logical view.  Create a physical Web Server.  On the Config > Settings tab, enter the host and port of the hotels server.

Physical resource for the Web Server

Note – you should NOT be entering any information about the proxy here.  Rational Integration Tester handles all the proxy stuff behind the scenes with the help of Rational Test Control Panel.  All you need to do in the model is describe the SUT.

Also, switch the Recording Mode on the Recording tab to External Proxy Server.  This is not the default.  If you forget to switch the recoding mode to use the proxy, you will get no errors or messages, but you will get no recording.  If it is any comfort, you won’t be the first to forget this.  It happens all the time.

Recording Mode setting on the physical Web Server

Recording events

Start up recording in RIT on the HTTP Connection.  You should see a couple more messages appear in the proxy command window such as “Added recording rule…”.  This appears when RIT registers a rule in the proxy which tells the proxy to copy all the messages it sees and send them to RIT where they will appear as events in the Recording Studio perspective.

Proxy message indicating a recording rule

In the events view, you should now see the messages that were recorded.  In our example, the client sent a request consisting of an HTTP POST to the getHotels operation on the Hotel Server.  The service replied with a list of hotels in an XML message.

Recorded events in RIT

These events can then be used to create operations, requirements, tests or stubs.

With the recorder engaged, here is what you really have in place:

Recording Architecture

The request comes from the client destined for the service, but routed through the proxy.  The recording rule that has been registered with the proxy causes it to send a copy of the request to RIT at the same time that it forwards on the request to the service.  When the service replies, the proxy once again sends a copy of the reply to RIT while forwarding on the reply to the client.

I have left out some important details such as the role of the Rational Test Control Panel but I wanted to keep things fairly simple for now and focus on the role of the proxy.  Hopefully this article has helped clear up any confusion you may have had around recording basic HTTP with the proxy.  In my next post, I will look at recording HTTPS which adds another dimension to things.