Using SSL in a SoapUI mock service (including client authentication)

Not only can SoapUI mock a web service, it supports using SSL to connect to that service, and even to require client authentication via certificate.  This post on the SoapUI support blog walks through the steps to enable SSL support, but doesn’t handle client authentication.  There are also a couple of tricky things that I wanted to mention.  So here’s a very short tutorial, which uses the same mock service I created in this post.

The process to enable SSL is short:

1. Create the keyStore to use.
2. Configure SoapUI to use the created keyStore for mock services.
3. Restart SoapUI

If you want to require client authorization, then just add a few more steps:

1. Export client certificate and private keys into a keyStore.
2. Configure SoapUI to require client authorization and provide the client keyStore
3. Restart SoapUI

Enabling SSL in Mock Services

Create the keystore

Most of the keystore and certificate manipulation needed in this tutorial can be done using keytool, the command-line utility in the JDK.  But that’s really a pain in the neck, so I’m going to use Portecle instead, which is an open-source GUI keystore tool which hides most of the ugliness of keytool and provides some additional functionality.

Using the tool, generate a new keystore.  For this sample I’ll use Sun’s keystore format.  I’ve found that SoapUI won’t work with the PKCS #12 option in the mocks, though you can use keystores of that type in calls made to real services with SoapUI, which I’ll show later.

Generate a key-pair in the keystore.  First step is to select the algorithm and key size.  I just leave these as default.

Now enter in the details about the key pair.  If you’ve ever worked with LDAP, this should look familiar.  Most of the fields are optional, but be sure to enter the Common Name.

Finally, specify the alias for the new key-pair:

Here is a shot of Portecle after the key-pair is generated.

All that’s left is to save the keystore to wherever you’d like.  You’ll need to enter and confirm the keystore password (I recommend using the same password as you did for the key-pair, just for simplicity later), then name the new keystore file.  In my case, it’s called soapUIsslTest.pks.

Configure SoapUI to use the new keystore for mock services

All the SSL functionality in SoapUI is managed from preferences.

1. Select File: Preferences from the menus.  Click on the SSL Settings tab
2. Make sure KeyStore and KeyStore Password are blank.
3. Check Enable Mock SSL
4. Enter a free port to use for accessing the mock via SSL
5. Enter the path to the keystore you just created as both the Mock Keystore and Mock TrustStore
6. Enter the password you used when saving the keystore (not when creating the key-pair!) as Mock Password, Mock TrustStore Password.
7. Enter the password you entered when creating the key-pair as the Mock Key Password
8. Do not check Client Authentication

Here is a screen capture after completing this process:

Restart SoapUI

I’ve found that whenever you make changes to the Mock portion of the SSL settings, you need to restart SoapUI to get them picked up.

Once SoapUI has restarted, you can start the mock service and use it however you’d like.

Demonstrating that SSL is enabled

You won’t actually see the traffic encrypted in SoapUI, but you can verify that SSL was used in two ways.  Here is a screen capture showing the test request and the mock service response after a call was made that did not use SSL:

Note that the endpoint used in the request was http://localhost:8088/doMathStuff which specifies non-SSL traffic to the original port, not the port given in the SSL Settings tab.  Also, you can see that the SSL Info section of the response received by the test request does not have any SSL information; it’s greyed out.

Here is a screenshot of the same request sent using SSL (Note: As long as you aren’t concerned with client authentication via certificate, only the endpoint address needs to change!):

You can see that the endpoint used now specifies the https:// protocol and the port given in the preferences.  Also, there is now data given on the SSL Info for the response.  If you click on that, you’ll actually see details matching the key-pair you created earlier.

Requiring Client Authentication

These steps assume you’ve already enabled SSL for mock services, per the above tutorial.

Export client certificate and private keys into a keystore

You need to have a keystore that contains the client certificate you’re planning to use for authentication, as well as the generated private keys.  I’ve had success using the same keystore as I created for the mock service, but only if I use the same password for the keystore and the key-pair I generate.  I’m not sure why this is, but for completeness, I’ll step through creating a new client keystore by exporting the needed data from the keystore already created above.

Note: I don’t believe you can do this sort of export using keytool; it takes extra coding.  So I’ll use Portecle, which offers this capability.

In Portecle, right-click on the key-pair you created before, and select Export from the popup menu.

Select Private Key and Certificates as the Export Type.

Enter the password for the key-pair, if prompted.  If you’ve kept Portecle open throughout the tutorial, it may already be cached.

Enter the password for the new keystore into which you’re exporting the certificate.

Save the new keystore wherever is convenient.

Configure SoapUI to require client authorization and provide the client keystore

In order to enable client authorization, you’ll first need to set up the mock keystore and truststore as listed above.  Once that’s done:

Restart SoapUI

Since you changed the Mock portion of the settings (by requiring client authentication), you need to restart SoapUI.

Once SoapUI has restarted, you can start the mock service and use it however you’d like.  Your client certificate will be provided during authentication.

Demonstrating that client authentication with certificate is enabled

One way of checking whether authentication was used is to change the keystore or type in an incorrect password.  This will fail, and you’ll be able to check the logs for the relevant stack traces.  This might seem a little brutish, but it is a good way of attempting to replicate problems you may be seeing in your real service code when trying to use certificates. It doesn’t take long, either.  If you only change the KeyStore and KeyStore Password settings in SoapUI, you don’t have to restart anything (since they aren’t part of the Mock settings).

There is another way to verify the details of client authentication, however.  The SoapUI display when using client authentication is no different than when just using SSL, but if you look at the SSL Info details in the response, you can confirm the certificate was used.  Here is the SSL Info for a request that was sent without requiring client authentication (doing the first part of this tutorial):

Note that the first entry after CipherSuite is PeerPrincipal.  By contrast, here is the SSL Info for a request sent while requiring client authentication:

You see that there is a LocalPrincipal given, and that it is the key-pair that you exported into the keyStore earlier.  There will also be a PeerPrincipal entry which matches the details when not using client authentication.