Thursday, January 24, 2013

Fuse ESB Enterprise WS-Security Quickstart with Fuse IDE

The objective of this article is to show how to compile, deploy and run a SOAP web service with Apache CXF using WS-Security and the Blueprint configuration.  The web service will be exposed through the OSGi HTTP Service in Fuse Enterprise Service Bus (ESB) Enterprise.   The project will be built with the Fuse Integrated Development Environment (IDE) and will include the code for the server as well as client code.  

I will highlight the following with the Fuse IDE:

  • how to configure JAX-WS Web services by using the blueprint configuration file
  • how to configure WS-Security on a CXF JAX-WS Web service in Blueprint
  • how to use standard Java Web Service annotations to define a Web service interface
  • how to use standard Java Web Service annotations when implementing a Web service in Java
  • how to use use an HTTP URL to invoke a remote Web service
  • how to deploy the bundle
  • how to test the Web Service

  Note: A quickstart is included with Fuse ESB Enterprise 7.1.0 that is located at <esb_home>/examples/secure-soap which concentrates on building, deploying and running the included example code from the command line.   We will be importing this project into the Fuse IDE.  Also a similar quickstart without the blueprint configuration is located  at <esb_home>/examples/cxf-ws-security-osgi in Fuse ESB 4.4.1.

One of the OSGi Best Practices is related to the usage of the Blueprint Container instead of Spring-DM.  The Blueprint container is now the preferred framework for instantiating, registering, and referencing OSGi services, because this container has now been adopted as an OSGi standard. Following this best practice and standard will ensure greater portability for your OSGi service definitions in the future.

Spring Dynamic Modules (Spring-DM) provided much of the original baseline for the definition of the Blueprint standard.  But currently Spring-DM would be considered deprecated.   Using the Blueprint container does not prevent you from using the Spring framework: the latest version of Spring is compatible with Blueprint.  


Overview of Products and Standards


Fuse ESB Enterprise


Fuse ESB Enterprise is a comprehensive, standards-based integration platform that can be configured with any combination of components for a customizable IT footprint.  The diagram below highlights the components and additional information can be found in the tech brief overview Fuse ESB Enterprise Tech Overview as well as detailed product documentation.

"An ESB is a standards-based integration platform that combines messaging, web services, data transformation, and intelligent routing to reliably connect and coordinate the interaction of significant numbers of diverse applications across extended enterprises with transactional integrity."   --David A. Chappell, Author Enterprise Service Bus

 Diagram 1 - Fuse ESB Enterprise Components


Fuse IDE


 The Fuse IDE is a graphical design and test environment for integration applications. The key tools that are used during the phases of application development include - template based project creation, visual route editor, container provisioning, JMX-based infrastructure monitoring, Fuse Fabric monitoring and
message tracing.

Detailed documentation for both the Fuse ESB Enterprise and Fuse IDE can be found on the Red Hat Customer Portal Product Documentation Page.

 Screen Shot 1 - Product Documentation Page with FuseSource Products



 Open Services Gateway initiative (OSGi ) is set of open specifications that make it easier to build and deploy complex software applications. The OSGi Framework, the key piece of OSGi technology, is responsible for loading and managing the dynamic modules of functionality, otherwise known as bundles.

For more information on OSGi and the specifications visit the OSGi site.

 Screen Shot 2 - OSGi Web Site



The Products and their versions used in the article are listed below:

·         Fuse ESB Enterprise 7.1.0
·         Fuse IDE 7.1.60
·         JDK 1.6

The Fuse products can be downloaded from the Red Hat Customer Portal JBoss Middleware Download Page.  The steps are the same for the Windows and RHEL platforms and both were tested.  Download the binaries and install into a Fuse directory.   The notations <esb_home> will indicate the default Fuse ESB extracted files location at <fuse_directory>/fuse-esb-7.1.0.fuse-047 and <ide_home> will be <fuse_directory>/FuseIDE.  

 Screen Shot 3 - Product Download Page

Import the project

Our first step is to start the FuseIDE by running the FuseIDE executable located in <fuse_home>.   Import the existing Maven Project by selecting File, import and then the Import Source Existing Maven Project.

 Screen Shot 4 - Import Existing Maven Project

Click next and then select the secure-soap example located at  <esb_home>/examples/secure-soap.

 Screen Shot 5 - Secure SOAP Project

Click on the OK button which will then display the project dialog with the project selected.

Screen Shot 6 - Maven Project

Click next and the Mavin plugin connector dialog will display which shows the Eclipse plugins mapped to Maven plugin goal executions.

  Screen Shot 7 - Maven plugin connectors

Click Finish which will start the importing of the project.

Screen Shot 8 - Import Maven project

After the project is imported then no problems should be showing in the problem pane.

Screen Shot 9 - Project Imported

Create the new server

Modify the file in <esb_home>/etc to contain the admin username and password required when setting up the new server instance in the IDE.  Remove comment from user admin and password admin.

#All users specified in this file, will be uploaded to the fabric registry and will

#be available to all containers that join the fabric.

#The password of the first user in the file will also be used as a registry (zookeeper) password

#unless a password is explicitly specified.


 Code Block 1 -

Next select File then New then other from the menu.  Click on server and the next button to add a new server.

Screen Shot 10 - New Server Wizard

Select the Fuse ESB Enterprise 7.x Server and click next to accept the defaults.

Screen Shot 11 - New server type

Browse to the <esb_home> for the installation directory and click on next.

 Screen Shot 12 - Installation directory

Enter the admin user name and password that was entered in the file in Code Block 1. Then click finish to create the new server.

Screen Shot 13 - Server Configuration

Build the project

Right click on the pom.xml and select Run as Maven clean.

Screen Shot 14 - Maven Clean

Next right click on pom.xml and select Run as Maven install.

Screen Shot 15 - Maven install

Next select the Fuse Integration perspective.

Screen Shot 16 - Fuse Integration Perspective

Start the Server

Start the server by clicking the start button in the Server panel.

Screen Shot 17 - Start Server

Deploy the Web Service

Setup the deploy folder for the bundle by right clicking on the pom.xml then select the deploy folder configurations.   Enter the Name and browse to the deploy folder at <esb_home>/deploy then click add.

Screen Shot 18 - Deployment Folder

Right click on pom.xml and select the deployment folder to deploy the service.

Screen Shot 19 - Service deployed

The bundled jar should be in the deployment folder.

Screen Shot 20 - jar file

Testing the Web Service

A full listing of all CXF Web services is available at http://localhost:8181/cxf.

After you deployed this example, you will see the `HelloWorldSecurity` service appear in the `Available SOAP Services` section, together with a list of operations for the endpoint and some additional information like the endpoint's address and a link to the WSDL file for the Web service.

Screen Shot 21 - CXF Web Service List

Clicking on the WSDL link above or entering the URL in the browser will display the WSDL http://localhost:8181/cxf/HelloWorldSecurity?wsdl

Screen Shot 22 - Service WSDL

Testing the service can be done with the provided client.html file or by using the SOAPUI plugin in the Fuse IDE.  Right click on the client.html file and open with the browser.  Click the send button to send the request and view the response.  Once the request has been successfully sent, a response similar to the following should appear in the right-hand panel of the web page.

Screen Shot 23 - Browser Client Test

You can also run the Java Client code by right clicking on the and selecting Run as Java Application.  The name in the sayHi method can be modified prior to running the client as seen in the highlighted code block below.

Screen Shot 24 - Java Client Test

The client uses a client proxy for the Web service to invoke the remote method - in reality, a SOAP message will be sent to the server and the response SOAP message will be received and handled.  You will see this output from the remote method:

        Apr 4, 2012 7:48:13 AM org.apache.cxf.service.factory.ReflectionServiceFactoryBean buildServiceFromClass
        INFO: Creating Service {}HelloWorldService from class
        Hello My Name

Files included in the example

The file descriptions below describe the main files in the example:

the Maven POM file for building the example
a Web client that can be used to test the Web service from your browser
 a Java interface that defines the Web service
a Java class that implements the Web service
a Java class implementing a client that connects to the Web service using an HTTP URL
a Java class implementing authentication callback by checking the identifier and password
a Java class which set the security properties for the client
the OSGI Blueprint file that defines the services

Additional configuration options


The following additional configuration options describe managing user credentials and changing the cxf servlet alias. 

Managing the user credentials

You can define additional users in the JAAS realm in two ways:

1. By editing the `etc/` file, adding a line for every user your want to add (syntax: `user = password, roles`).

            myuser = mysecretpassword

2. Using the jaas: commands in the Fuse ESB Enterprise console:

            jaas:manage --realm karaf
            jaas:useradd myuser mysecretpassword

Changing /cxf servlet alias

By default CXF Servlet is assigned a `/cxf` alias. You can change it in a couple of ways:

1. Add `org.apache.cxf.osgi.cfg` to the `/etc` directory and set the `org.apache.cxf.servlet.context` property, for example:


2. Use shell config commands, for example:

        config:edit org.apache.cxf.osgi
        config:propset org.apache.cxf.servlet.context /custom