WS-Security and SAML for Mule

motif

Mule ESB has had support for WS-Security via for some time now, but the enterprise edition of Mule 2.2.4 goes a bit further still with the inclusion of the Mule SAML Module and a new WS-Security example. In this article, I will step through the WS-Security example so that you can see the different possibilities available for incorporating WS-Security into your Mule application. For a good introduction to security and SAML, check out the blog post on the Atos site on Security in the Open Source SOA.

Running the example

You will find the new WS-Security example in the directory $MULE_HOME/examples/security, where $MULE_HOME is the path to your installation of Mule 2.2.4 Enterprise. From that directory run ./security (Unix/Linux/Mac) or security.bat (Windows), and once Mule starts up, you should see the following menu:

Each of these options will invoke an instance of the same simple web service, each of which is protected by a different form of security.

All of the configuration files used by the example are in the conf directory (i.e., $MULE_HOME/examples/security/conf). The principle configuration file is called secure-services.xml.

The basic web service we will use without any security whatsoever looks like this in our Mule configuration:

Select option #1 from the menu to call this service. We can see the simple SOAP request message sent:

and the service’s equally simple response message:

UsernameToken

Now let’s add some simple security to the service. We’ll start with a basic Username authentication. For this, we’ll add a WSS4J interceptor to our inbound CXF endpoint:

The most important thing we specify on this interceptor is the action, which is the list of features/aspects of WS-Security that we want to validate upon receiving an incoming message. In this case, we specify UsernameToken, which will check the username and password, and Timestamp, which will verify that the message is not too stale. We also specify a password callback so that our password is not stored in the config file itself.

Selecting option #2 from the menu will create an appropriate WS-Security header for our SOAP request:

We can see the Username and Password as well as the Timestamp in the header. Note that the password is in digest form rather than plain text, which is the default behavior.

Now select option #3 to see what happens if the wrong password is provided:

Signatures

A more advanced way of authenticating the user is via a digital signature. To validate based on a signature, we’ll need to add a new Signature action to our inbound endpoint:

Signatures are validated based on a keystore, so we’ll also need to specify some information about the keystore we’re using. The following properties are in the wssecurity.properties file:

We can use the Java keytool command to verify that the certificate for user “joe” exists in our keystore:

Note that this certificate is self-signed. In the real world, it would be issued by a trusted third party such as Verisign.

Selecting option #4 from the menu will invoke the web service using a signed SOAP message:

And option #5 shows what happens if we try to send a message that isn’t signed by joe:

Encryption

Note that so far, all security information has been contained in the header of the SOAP message, but the body of the message is completely transparent. We can encrypt the body of the message by adding an Encrypt action to our service:

Selecting option #6 will send a SOAP message with the body encrypted:

The message will not be decrypted without the user’s signature, so the keystore is once again used for encryption.

Since SAML is used for Single Sign-On, authentication of the user is assumed to have already occurred, and the SAML Token simply contains one or more subjects, which provide some information understood by other systems. In this case we will configure our service to require a SAML subject of AllowGreetingServices. To our inbound endpoint we add a SAMLVerifyInterceptor with a callback, which will check for the correct SAML subject:

Option #7 adds the expected SAML token to the WS-Security header of the message:

Selecting option #8 will send a SAML token without the expected subject:

To verify that the received SAML token is authentic, SAML offers two different modes of trust: Sender Vouches and Holder of Key. In this case, we are using Sender Vouches, which means that the sender of the message must be trusted (e.g., via a digital signature). In Holder of Key mode, the sender of the message does not matter, but the SAML token subject must contain a key from a trusted source (e.g., an X.509 certificate from Verisign).

For more information on SAML, refer to:
http://saml.xml.org/wiki/saml-wiki-knowledgebase


We'd love to hear your opinion on this post


2 Responses to “WS-Security and SAML for Mule”

  1. Thanks for the codes, hopefully i can get this working sometime today 🙁

  2. Great guide, work first time for me. I would suggest make a backup ASAP after this just incase you mess up the settings later