Web Services CXF User Guide Red Hat

User Manual:

Open the PDF directly: View PDF .
Page Count: 55

Download
Open PDF In Browser	View PDF

JBoss Enterprise Application Platform 5
Web Services CXF User Guide
for use with JBoss Enterprise Application Platform 5
Edition 5.2.0

Last Updated: 2017-10-13

JBoss Enterprise Application Platform 5 Web Services CXF User Guide
for use with JBoss Enterprise Application Platform 5
Edition 5.2.0
Alessio Soldano

Edited by
Elspeth Thorne
Eva Kopalova
Petr Penicka
Rebecca Newton
Russell Dickenson
Scott Mumford

Legal Notice
Copyright © 2012 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0
Unported License. If you distribute this document, or a modified version of it, you must provide
attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red
Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert,
Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity
logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other
countries.
Linux ® is the registered trademark of Linus Torvalds in the United States and other countries.
Java ® is a registered trademark of Oracle and/or its affiliates.
XFS ® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United
States and/or other countries.
MySQL ® is a registered trademark of MySQL AB in the United States, the European Union and
other countries.
Node.js ® is an official trademark of Joyent. Red Hat Software Collections is not formally related
to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack ® Word Mark and OpenStack logo are either registered trademarks/service marks
or trademarks/service marks of the OpenStack Foundation, in the United States and other
countries and are used with the OpenStack Foundation's permission. We are not affiliated with,
endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.

Abstract
This is a guide for installing and running JBoss Web Services CXF with JBoss Enterprise
Application Platform 5 and its patch releases. It includes installation, configuration and tutorials.

Table of Contents

Table of Contents
. . . . . . . . . . . 1.
CHAPTER
. .INTRODUCTION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3. . . . . . . . . . . .
. . . . . . . . . . . 2.
CHAPTER
. . INSTALLATION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4. . . . . . . . . . . .
. . . . . . . . . . . 3.
CHAPTER
. . .SERVER
. . . . . . . . .SIDE
. . . . . .INTEGRATION
. . . . . . . . . . . . . . .CUSTOMIZATION
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5. . . . . . . . . . . .
. . . . . . . . . . . 4.
CHAPTER
. . .WS
. . . .ADDRESSING
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7. . . . . . . . . . . .
4.1. USING JAX-WS FOR ENABLING WS-ADDRESSING
4.1.1. Using CXF proprietary WSAddressingFeature

7
7

.CHAPTER
. . . . . . . . . . 5.
. . .ADDRESSING
. . . . . . . . . . . . . . TUTORIAL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9. . . . . . . . . . . .
5.1. TURNING ON WS-ADDRESSING 1.0
12
. . . . . . . . . . . 6.
CHAPTER
. . .WS-RELIABLE
. . . . . . . . . . . . . . .MESSAGING
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
.............
. . . . . . . . . . . 7.
CHAPTER
. . .USING
. . . . . . .WS-RELIABLE
. . . . . . . . . . . . . . .MESSAGING
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15
.............
.CHAPTER
. . . . . . . . . . 8.
. . .WS-RELIABLE
. . . . . . . . . . . . . . . MESSAGING
. . . . . . . . . . . . . TUTORIAL
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
.............
8.1. GENERATING WSDL AND JAX-WS ENDPOINT ARTIFACTS
18
8.2. GENERATING JAX-WS CLIENT ARTIFACTS
8.3. TURNING ON WS-RM 1.0

21
22

. . . . . . . . . . . 9.
CHAPTER
. . .WS
. . . .POLICY
. . . . . . . .FRAMEWORK
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
..............
9.1. USING THE POLICIES FEATURE
9.2. SPECIFYING THE LOCATION OF EXTERNAL ATTACHMENTS

29
29

. . . . . . . . . . . 10.
CHAPTER
. . . WS-SECURITY
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .31
.............
10.1. OVERVIEW OF ENCRYPTION AND SIGNING

31

.CHAPTER
. . . . . . . . . . 11.
. . . WSS4J
. . . . . . . . SECURITY
. . . . . . . . . . . ON
. . . .JBOSS
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
..............
11.1. CREATING THE WEB SERVICE ENDPOINT
33
11.2. TURN ON WS-SECURITY
11.2.1. Package and deploy

33
36

11.3. WS-SECURITY POLICIES
11.4. AUTHENTICATION

37
39

11.4.1. Java Authentication and Authorization Service
11.5. FURTHER INFORMATION

44
47

11.5.1. Samples
11.5.2. Username/password configuration
11.5.3. Crypto Algorithms

47
48
48

.CHAPTER
. . . . . . . . . . 12.
. . . .SOAP
. . . . . . MESSAGE
. . . . . . . . . . .LOGGING
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
..............
12.1. DEBUGGING TOOLS
50
. . . . . . . . . . . . A.
APPENDIX
. . .REVISION
. . . . . . . . . . HISTORY
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51
.............

1

Web Services CXF User Guide

2

CHAPTER 1. INTRODUCTION

CHAPTER 1. INTRODUCTION
JBoss Web Services CXF (JBossWS-CXF) is the JBoss Web Services stack implementation internally
based on Apache CXF. Apache CXF is an open source services framework. CXF helps you build and
develop services using front-end programming Application Programming Interfaces (APIs), like JAXWS.
CXF includes a broad feature set, but it is primarily focused on the following areas:
Web Services Standard Support
CXF supports a variety of web service standards including:
SOAP
WSI Basic Profile.
WSDL
WS-Addressing
WS-Policy
WS-ReliableMessaging
WS-Security
WS-SecurityPolicy
WS-SecureConversation
Front ends
CXF supports a variety of front-end programming models. CXF implements the JAX-WS APIs (TCK
compliant). It also includes a simple front end which allows creation of clients and endpoints
without annotations. CXF supports both contract first development with WSDL and code first
development starting from Java.
Ease of use
CXF is designed to be intuitive and easy to use.
There are simple APIs to quickly build code-first services.
Maven plug-ins to make tooling integration easy.
JAX-WS API support.
Spring 2.x XML support to make configuration easier.

3

Web Services CXF User Guide

CHAPTER 2. INSTALLATION



WARNING
Installing JBoss Web Services CXF is irreversible. You should make a complete
backup of your JBoss Enterprise Application Platform installation before installing
JBoss Web Services CXF.

Follow these steps to install JBoss Web Services CXF:
Procedure 2.1. Installing CXF
1. Download the Installer
Download and unzip the jboss-ep-ws-cxf-5.1.0-installer.zip in the home jboss-as
directory directly under the Platform installation root.
2. Replace WS Native with WS CXF
Run ant in the created directory, jbossws-cxf-installer.

NOTE
This step will replace JBoss Web Services Native with JBoss Web Services CXF in every
configuration that contains JBoss Web Services Native.
After completing the process, you should be able to access JBossWS under
http://localhost:8080/jbossws

4

CHAPTER 3. SERVER SIDE INTEGRATION CUSTOMIZATION

CHAPTER 3. SERVER SIDE INTEGRATION CUSTOMIZATION
JBossWS-CXF allows users to deploy their web service endpoints by simply providing their archives
the same way they used to do with JBossWS-Native. However, it is possible to customize the JBossWS
and CXF integration by incorporating a CXF configuration file to the endpoint deployment archive. The
convention is the following:
The file name must be jbossws-cxf.xml
For POJO deployments it is located in WEB-INF directory
For EJB3 deployments it is located in META-INF directory
If the user does not provide their own CXF configuration file, the default one will be automatically
generated during the runtime. For POJO deployments the generated jbossws-cxf.xml has the
following content:









For EJB3 deployments the generated jbossws-cxf.xml has the following content:









Providing custom CXF configuration to the endpoint deployment is useful in cases when users want to
use features that are not part of standard JAX-WS specification but CXF still implements them. See
Chapter 8, WS-Reliable Messaging Tutorial for more information. We provide custom CXF endpoint
configuration there to turn on WS-RM feature for the endpoint.

NOTE
When the user incorporates their own CXF configuration to the endpoint archive they
must reference either org.jboss.wsf.stack.cxf.InvokerJSE or the
org.jboss.wsf.stack.cxf.InvokerEJB3 JAX-WS invoker bean there for each
JAX-WS endpoint.

6

CHAPTER 4. WS ADDRESSING

CHAPTER 4. WS ADDRESSING
CXF provides support for the 2004-08 and 1.0 versions of WS-Addressing. Users can enable WSAddressing either using the standard JAX-WS approach or using the Apache CXF WS Addressing
Feature on their service.

4.1. USING JAX-WS FOR ENABLING WS-ADDRESSING
As per JAX-WS 2.1 specification, users can enable WS-Addressing on a web service endpoint by simply
adding the @javax.xml.soap.Addressing annotation.

package org.jboss.test.ws.jaxws.samples.wsa;
import javax.jws.WebService;
import javax.xml.ws.soap.Addressing;
@WebService
@Addressing(enabled=true, required=true)
public class ServiceImpl implements ServiceIface
{
public String sayHello()
{
return "Hello World!";
}
}
On the client side, WS-Addressing can be explicitly enabled by providing
org.apache.cxf.ws.addressing.WSAddressingFeature when getting the proxy instance from
the service:
ServiceIface proxy = (ServiceIface)service.getPort(ServiceIface.class,
new AddressingFeature());
proxy.sayHello());

4.1.1. Using CXF proprietary WSAddressingFeature
To enable WS-Addressing, enable the WSAddressingFeature on your service. If you wish to use XML to
configure this, use the following syntax:






You can also use the same exact syntax with a :




7

Web Services CXF User Guide





8

CHAPTER 5. ADDRESSING TUTORIAL

CHAPTER 5. ADDRESSING TUTORIAL
This tutorial will show you how to create client and endpoint communication with WS-Addressing
enabled. Creating a WS-Addressing based service and client is very simple. The first step is to create
regular JAX-WS service and client configuration; the last step is to configure the addressing on both
sides.
The Service
We will start with the following endpoint implementation.
package org.jboss.test.ws.jaxws.samples.wsa;
import javax.jws.web service;
@web service
(
portName = "AddressingServicePort",
serviceName = "AddressingService",
targetNamespace = "http://www.jboss.org/jbossws/wsextensions/wsaddressing",
endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
)
public class ServiceImpl implements ServiceIface
{
public String sayHello()
{
return "Hello World!";
}
}
The above endpoint implements the following endpoint interface:
package org.jboss.test.ws.jaxws.samples.wsa;
import javax.jws.WebMethod;
import javax.jws.web service;
@web service
(
targetNamespace = "http://www.jboss.org/jbossws/wsextensions/wsaddressing"
)
public interface ServiceIface
{
@WebMethod
String sayHello();
}
Let us say that compiled endpoint and interface classes are located in directory
/home/username/wsa/cxf/classes. The next step is to generate the JAX-WS artifacts and WSDL
that will be part of the endpoint archive.
Generating WSDL and JAX-WS Endpoint Artifacts
We will use the wsprovide command line tool to generate WSDL and JAX-WS artifacts. Here's the
command:

9

Web Services CXF User Guide

cd JBOSS_HOME/bin
./wsprovide.sh --keep --wsdl \
--classpath=/home/username/wsa/cxf/classes \
--output=/home/username/wsa/cxf/wsprovide/generated/classes \
--resource=/home/username/wsa/cxf/wsprovide/generated/wsdl \
--source=/home/username/wsa/cxf/wsprovide/generated/src \
org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl
The above command generates the following artifacts:
Compiled classes
SayHello.class
SayHelloResponse.class
Java Sources
SayHello.java
SayHelloResponse.java
Contract Artifacts
AddressingService.wsdl
All previously mentioned generated artifacts will be part of the endpoint archive, but before we create
the endpoint archive, we need to reference generated WSDL from the endpoint. We will use the
wsdlLocation annotation attribute. This is the updated endpoint implementation before it is
packaged to the war file:
package org.jboss.test.ws.jaxws.samples.wsa;
import javax.jws.web service;
@web service
(
portName = "AddressingServicePort",
serviceName = "AddressingService",
wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
targetNamespace = "http://www.jboss.org/jbossws/wsextensions/wsaddressing",
endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
)
public class ServiceImpl implements ServiceIface
{
public String sayHello()
{
return "Hello World!";
}
}
The created endpoint war archive consists of the following entries:

10

CHAPTER 5. ADDRESSING TUTORIAL

jar -tvf jaxws-samples-wsa.war
0 Mon Apr 21 20:39:30 CEST 2008 META-INF/
106 Mon Apr 21 20:39:28 CEST 2008 META-INF/MANIFEST.MF
0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/
593 Mon Apr 21 20:39:28 CEST 2008 WEB-INF/web.xml
0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/classes/
0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/
0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/
0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/
0 Mon Apr 21 20:39:26 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
0 Mon Apr 21 20:39:26 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/
0 Mon Apr 21 20:39:26 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/
0 Mon Apr 21 20:39:26 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsa/
374 Mon Apr 21 20:39:26 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceIface.class
954 Mon Apr 21 20:39:26 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsa/ServiceImpl.class
0 Mon Apr 21 20:39:26 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/
703 Mon Apr 21 20:39:26 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHello.class
1074 Mon Apr 21 20:39:26 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsa/jaxws/SayHelloResponse.cla
ss
0 Mon Apr 21 20:39:30 CEST 2008 WEB-INF/wsdl/
2378 Mon Apr 21 20:39:28 CEST 2008 WEB-INF/wsdl/AddressingService.wsdl
The content of the web.xml file is:




AddressingService
org.jboss.test.ws.jaxws.samples.wsa.ServiceImpl


AddressingService
/*


Writing Regular JAX-WS Client
The following is the regular JAX-WS client using endpoint interface to lookup the web service:
package.org.jboss.test.ws.jaxws.samples.wsa:

11

Web Services CXF User Guide

package.org.jboss.test.ws.jaxws.samples.wsa:
import java.net.URL;
import javax.xml.namespace.QName;
import javax.xml.ws.Service;
public final class SimpleServiceTestCase
{
private final String serviceURL = "http://localhost:8080/jaxws-sampleswsa/AddressingService";
public static void main(String[] args) throws Exception
{
// create service
QName serviceName = new QName("http://www.jboss.org/jbossws/wsextensions/wsaddressing", "AddressingService");
URL wsdlURL = new URL(serviceURL + "?wsdl");
Service service = Service.create(wsdlURL, serviceName);
ServiceIface proxy =
(ServiceIface)service.getPort(ServiceIface.class);
// invoke method
proxy.sayHello();
}
}
We have both endpoint and client implementations but without WS-Addressing in place. Our next goal
is to turn on the WS-Addressing feature.

5.1. TURNING ON WS-ADDRESSING 1.0
There are two steps remaining in order to turn on WS-Addressing in JBossWS-CXF.
Annotate service endpoint with @Addressing annotation.
Modify client to configure WS-Addressing using the JAX-WS web service feature.
Updating Endpoint Code to Configure WS-Addressing
Now we need to update endpoint implementation to configure WS-Addressing. Here's the updated
endpoint code:

package org.jboss.test.ws.jaxws.samples.wsa;
import javax.jws.web service;
import javax.xml.ws.soap.Addressing;
@web service
(
portName = "AddressingServicePort",
serviceName = "AddressingService",
wsdlLocation = "WEB-INF/wsdl/AddressingService.wsdl",
targetNamespace = "http://www.jboss.org/jbossws/wsextensions/wsaddressing",

12

CHAPTER 5. ADDRESSING TUTORIAL

endpointInterface = "org.jboss.test.ws.jaxws.samples.wsa.ServiceIface"
)
@Addressing(enabled=true, required=true)
public class ServiceImpl implements ServiceIface
{
public String sayHello()
{
return "Hello World!";
}
}
We have added the JAX-WS 2.1 Addressing annotation to configure WS-Addressing. The next step is to
repackage the endpoint archive to apply this change.
Updating Client Code to Configure WS-Addressing
We need to update client implementation to configure WS-Addressing. Here's the updated client code:
package org.jboss.test.ws.jaxws.samples.wsa;
import
import
import
import

java.net.URL;
javax.xml.namespace.QName;
javax.xml.ws.Service;
javax.xml.ws.soap.AddressingFeature;

public final class AddressingTestCase
{
private final String serviceURL = "http://localhost:8080/jaxws-sampleswsa/AddressingService";
public static void main(String[] args) throws Exception
{
// construct proxy
QName serviceName = new QName("http://www.jboss.org/jbossws/wsextensions/wsaddressing", "AddressingService");
URL wsdlURL = new URL(serviceURL + "?wsdl");
Service service = Service.create(wsdlURL, serviceName);
ServiceIface proxy =
(ServiceIface)service.getPort(ServiceIface.class, new
AddressingFeature());
// invoke method
proxy.sayHello();
}
}

We now have both JAX-WS client and endpoint communicating with each other using WS-Addressing.

13

Web Services CXF User Guide

CHAPTER 6. WS-RELIABLE MESSAGING
CXF supports the February 2005 version of the Web Service Reliable Messaging Protocol specification.
Like most other features in CXF, it is interceptor based. The WS-Reliable Messaging implementation
consists of four interceptors in total. These are listed below.
org.apache.cxf.ws.rm.RMOutInterceptor
Responsible for:
Sending CreateSequence requests.
Waiting for their CreateSequenceResponse responses.
Collecting the sequence properties (id and message number) for an application message.
org.apache.cxf.ws.rm.RMInInterceptor
Intercepting and processing RM protocol messages, as well as SequenceAcknowledgments
piggybacked on application messages.
org.apache.cxf.ws.rm.soap.RMSoapInterceptor
Encoding and decoding the RM headers
org.apache.cxf.ws.rm.soap.RetransmissionInterceptor
Responsible for creating copies of application messages for future resends.
Interceptor Based QoS
The presence of the RM interceptors on the respective interceptor chains alone will ensure that RM
protocol messages are exchanged when necessary. For example, upon intercepting the first
application message on the outbound interceptor chain, the RMOutInterceptor will send a
CreateSequence request and only proceed with processing the original application message after it
has the CreateSequenceResponse response. The RM interceptors are also responsible for adding
the sequence headers to the application messages and, on the destination side, extracting them from
the message.
This means that no changes to the application code are required to make the message exchange
reliable.
You can still control sequence demarcation and other aspects of the reliable exchange through
configuration. By default, CXF attempts to maximize the lifetime of a sequence. This reduces the
overhead incurred by the RM protocol messages, however you can choose to enforce the use of a
separate sequence per application message by configuring the source of the RM sequence termination
policy (setting the maximum sequence length to one). See the Chapter 7, Using WS-Reliable Messaging
for more details on configuring this and other aspects of the reliable exchange.

14

CHAPTER 7. USING WS-RELIABLE MESSAGING

CHAPTER 7. USING WS-RELIABLE MESSAGING
In order for JBoss WS-CXF/CXF to establish reliable messaging between two points, the CXF RM and
addressing interceptors need to be added to the interceptor chains. This can be achieved in one of the
ways outlined below.
Using the RMAssertion and the CXF WS-Policy Framework
The RM interceptors will be automatically added to their respective interceptor chains by the policy
framework if the following occurs:
1. A Policy with an RMAssertion element is attached to the wsdl:service element (or any
other WSDL element that is an attachment point for Policy or PolicyReference elements
according to the rules for WS-Policy Attachments).
2. The CXF WS-Policy Framework is enabled
The assertion attributes control the behavior of the source or destination. For example, to enable the
WS-Policy Framework on the server side, your configuration file will look like this:






Your WSDL will look like this:








...






Instead of attaching the PolicyReference to the wsdl:port element, you can also specify it as a child
element of the policies featured, such as the server endpoint.

15

Web Services CXF User Guide










Using the Reliable Messaging Feature
You can use the ReliableMessaging feature if you do not want to involve the WS-Policy Framework, or
want to configure additional parameters such as the sequence termination policy or the persistent
store. The supported child elements are listed below.
RMAssertion
An element of type RMAssertion.
deliveryAssurance
An element of type DeliveryAssuranceType that describes the delivery assurance that should apply
(AtMostOnce, AtLeastOnce, InOrder).
sourcePolicy
An element of type SourcePolicyType that allows you to configure details of the RM source, such as
whether an offer should always be included in a CreateSequence request, or the sequence
termination policy.
destinationPolicy
An element of type DestinationPolicyType that allows you to configure details of the RM
destination, such as whether inbound offers should be accepted.
store
The store to use (default: null). This must be an element of type jdbcStore (in the same
namespace), or a bean or a reference to a bean that implements the RMStore interface.
The jbdcStore element type is described below.
The following example is applied at bus level.









16

CHAPTER 7. USING WS-RELIABLE MESSAGING











Configuring the Reliable Messaging Store
To enable persistence, you must specify the object implementing the persistent store for RM. You can
develop your own, or use the JDBC based store that comes with CXF (class
org.apache.cxf.ws.rm.persistence.jdbc.RMTxStore). You can configure the latter using a
custom jdbcStore bean. The supported attributes are in the table below.
Table 7.1. Attributes
Attribute name

String

Default

driverClassName

String

org.apache.derby.jdbc.Embedded
Driver

userName

String

null

passWord

String

null

url

String

jdbc:derby:rmdb;create=true

Here is an example:

Configuring the Reliable Messaging Manager Manually
To configure properties of the RM Manager, you can use the RMManager element. It supports the same
child elements as the ReliableMessaging feature element above. For example, without using features,
you can determine that sequences should have a maximum length of five as follows:






17

Web Services CXF User Guide

CHAPTER 8. WS-RELIABLE MESSAGING TUTORIAL
In this sample we show you how to create client and endpoint communication using WS-Reliable
Messaging 1.0. Creating the WS-RM based service and client is very simple. The user needs to create
regular JAX-WS service and client first. The last step is to configure WS-RM.
We will start with the following endpoint implementation:
package org.jboss.test.ws.jaxws.samples.wsrm.service;
import javax.jws.Oneway;
import javax.jws.WebMethod;
import javax.jws.WebService;
@WebService
(
name = "SimpleService",
serviceName = "SimpleService",
targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
)
public class SimpleServiceImpl
{
@Oneway
@WebMethod
public void ping()
{
System.out.println("ping()");
}
@WebMethod
public String echo(String s)
{
System.out.println("echo(" + s + ")");
return s;
}
}
Let us say that compiled endpoint class is in directory /home/username/wsrm/cxf/classes. Our
next step is to generate JAX-WS artifacts and WSSDL.

8.1. GENERATING WSDL AND JAX-WS ENDPOINT ARTIFACTS
We will use the wsprovide command line tool to generate WSDL and JAX-WS artifacts. Here's the
command:
cd $JBOSS_HOME/bin
./wsprovide.sh --keep --wsdl \
--classpath=/home/username/wsrm/cxf/classes \
--output=/home/username/wsrm/cxf/wsprovide/generated/classes \
--resource=/home/username/wsrm/cxf/wsprovide/generated/wsdl \
--source=/home/username/wsrm/cxf/wsprovide/generated/src \
org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl
The above command generates the following artifacts:

18

CHAPTER 8. WS-RELIABLE MESSAGING TUTORIAL

Compiled classes
Echo.class
Echo response.class
Ping.class
Java sources
Echo.java
EchoResponse.java
Ping.java
Contract artifacts
SimpleService.wsdl
The artifacts generated above will be part of the endpoint archive, but before we create the endpoint
archive we need to reference generated WSDL from the endpoint. To achieve that we will use the
wsdlLocation annotation attribute. Here's the updated endpoint implementation before it is
packaged to the war file:

package org.jboss.test.ws.jaxws.samples.wsrm.service;
import javax.jws.Oneway;
import javax.jws.WebMethod;
import javax.jws.WebService;
@WebService
(
name = "SimpleService",
serviceName = "SimpleService",
wsdlLocation = "WEB-INF/wsdl/SimpleService.wsdl",
targetNamespace = "http://www.jboss.org/jbossws/ws-extensions/wsrm"
)
public class SimpleServiceImpl
{
@Oneway
@WebMethod
public void ping()
{
System.out.println("ping()");
}
@WebMethod
public String echo(String s)
{
System.out.println("echo(" + s + ")");
return s;
}
}

19

Web Services CXF User Guide

The created endpoint war archive consists of the following entries:
jar -tvf jaxws-samples-wsrm.war
0 Wed Apr 16 14:39:22 CEST 2008 META-INF/
106 Wed Apr 16 14:39:20 CEST 2008 META-INF/MANIFEST.MF
0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/
591 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/web.xml
0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/classes/
0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/
0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/
0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/
0 Wed Apr 16 14:39:18 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
0 Wed Apr 16 14:39:20 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/
0 Wed Apr 16 14:39:20 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/
0 Wed Apr 16 14:39:18 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/
0 Wed Apr 16 14:39:18 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/
0 Wed Apr 16 14:39:18 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
1235 Wed Apr 16 14:39:18 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/SimpleServiceImpl
.class
997 Wed Apr 16 14:39:18 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Echo.class
1050 Wed Apr 16 14:39:18 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/EchoRespons
e.class
679 Wed Apr 16 14:39:18 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Ping.class
0 Wed Apr 16 14:39:22 CEST 2008 WEB-INF/wsdl/
2799 Wed Apr 16 14:39:20 CEST 2008 WEB-INF/wsdl/SimpleService.wsdl
The content of web.xml file is:




SimpleService
org.jboss.test.ws.jaxws.samples.wsrm.service.SimpleServiceImpl


SimpleService
/*



20

CHAPTER 8. WS-RELIABLE MESSAGING TUTORIAL

8.2. GENERATING JAX-WS CLIENT ARTIFACTS
Before we write the regular JAX-WS client we need to generate client artifacts from WSDL. Here's the
command to achieve that:
cd $JBOSS_HOME/bin
./wsconsume.sh --keep \
--package=org.jboss.test.ws.jaxws.samples.wsrm.generated \
--output=/home/username/wsrm/cxf/wsconsume/generated/classes \
--source=/home/username/wsrm/cxf/wsconsume/generated/src \
/home/username/wsrm/cxf/wsprovide/generated/wsdl/SimpleService.wsdl
The artifacts that have been generated are below.
Compiled classes
Echo.class
ObjectFactory.class
Ping.class
SimpleService_Service.class
EchoResponse.class
package-info.class
SimpleService.class
SimpleService_SimpleServicePort_Client.class
Java sources
Echo.java
ObjectFactory.java
Ping.java
SimpleService_Service.java
EchoResponse.java
package-info.java
SimpleService.java
SimpleService_SimpleServicePort_Client.java
The last step is to write the regular JAX-WS client using generated artifacts.
Writing Regular JAX-WS Client
The following is the regular JAX-WS client using generated artifacts:

21

Web Services CXF User Guide

package org.jboss.test.ws.jaxws.samples.wsrm.client;
import
import
import
import

java.net.URL;
javax.xml.namespace.QName;
javax.xml.ws.Service;
org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;

public final class SimpleServiceTestCase
{
private static final String serviceURL = "http://localhost:8080/jaxwssamples-wsrm/SimpleService";
public static void main(String[] args) throws Exception
{
// create service
QName serviceName = new QName("http://www.jboss.org/jbossws/wsextensions/wsrm", "SimpleService");
URL wsdlURL = new URL(serviceURL + "?wsdl");
Service service = Service.create(wsdlURL, serviceName);
SimpleService proxy =
(SimpleService)service.getPort(SimpleService.class);
// invoke methods
proxy.ping(); // one way call
proxy.echo("Hello World!"); // request responce call
}
}
Now we have both endpoint and client implementations but without WS-Reliable Messaging in place.
Our next goal is to turn on the WS-RM feature.

8.3. TURNING ON WS-RM 1.0
Four steps are necessary to turn on WS-RM in JBossWS-CXF. They are outline below.
Extend WSDL with WS-Policy containing both WSRM and WS-Addressing policy.
Provide jbossws-cxf.xml endpoint configuration file.
Provide client CXF configuration.
Update client code to read CXF configuration file.
Extending WSDL Using WS-Policy
To activate WSRM we need to extend WSDL with WSRM and addressing policy. Here is how it looks:


















































23

Web Services CXF User Guide






































We added wsp:UsingPolicy;wsp:Policy and wsp:PolicyReference elements to WSDL.
Providing jbossws-cxf.xml Endpoint Configuration File
This is the JBossWS CXF integration extension file: Chapter 3, Server Side Integration Customization . In
our case, the relevant content is as follows:


















We need to include this jbossws-cxf.xml CXF configuration file in the WEB-INF directory of the
endpoint archive because we are creating a POJO deployment.
jar -tvf jaxws-samples-wsrm.war
0 Wed Apr 16 19:05:38 CEST 2008 META-INF/
106 Wed Apr 16 19:05:36 CEST 2008 META-INF/MANIFEST.MF
0 Wed Apr 16 19:05:38 CEST 2008 WEB-INF/
591 Wed Apr 16 19:05:36 CEST 2008 WEB-INF/web.xml
0 Wed Apr 16 19:05:38 CEST 2008 WEB-INF/classes/
0 Wed Apr 16 19:05:32 CEST 2008 WEB-INF/classes/org/
0 Wed Apr 16 19:05:32 CEST 2008 WEB-INF/classes/org/jboss/
0 Wed Apr 16 19:05:32 CEST 2008 WEB-INF/classes/org/jboss/test/
0 Wed Apr 16 19:05:32 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
0 Wed Apr 16 19:05:34 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/
0 Wed Apr 16 19:05:34 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/
0 Wed Apr 16 19:05:34 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/
0 Wed Apr 16 19:05:34 CEST 2008 WEB-

25

Web Services CXF User Guide

INF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/
0 Wed Apr 16 19:05:34 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/
1235 Wed Apr 16 19:05:34 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/SimpleServiceImpl
.class
997 Wed Apr 16 19:05:34 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Echo.class
1050 Wed Apr 16 19:05:34 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/EchoRespons
e.class
679 Wed Apr 16 19:05:34 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsrm/service/jaxws/Ping.class
1554 Wed Apr 16 19:05:36 CEST 2008 WEB-INF/jbossws-cxf.xml
0 Wed Apr 16 19:05:38 CEST 2008 WEB-INF/wsdl/
3237 Wed Apr 16 19:05:36 CEST 2008 WEB-INF/wsdl/SimpleService.wsdl
The next step is to create the client CXF configuration file that will be used by the client. It activates
the WS-RM protocol for the CXF client. We will name this file cxf.xml in our sample. The content of
this file is as follows:

















26

CHAPTER 8. WS-RELIABLE MESSAGING TUTORIAL




We are almost done. The client configuration needs to be picked up by the client classloader. In order
to achieve that the cxf.xml has to be put in the META-INF directory of client jar. That jar should then
be provided when setting the class loader.
Alternatively you can read the bus configuration programmatically.
Updating Client Code to Read Bus Configuration File
Here's the last piece of the updated CXF client:

package org.jboss.test.ws.jaxws.samples.wsrm.client;
import
import
import
import
import
import
import
import

java.net.URL;
java.io.File;
javax.xml.namespace.QName;
javax.xml.ws.Service;
org.apache.cxf.Bus;
org.apache.cxf.BusFactory;
org.apache.cxf.bus.spring.SpringBusFactory;
org.jboss.test.ws.jaxws.samples.wsrm.generated.SimpleService;

public final class SimpleServiceTestCase
{
private static final String serviceURL = "http://localhost:8080/jaxwssamples-wsrm/SimpleService";
public static void main(String[] args) throws Exception
{
// create bus
SpringBusFactory busFactory = new SpringBusFactory();
URL cxfConfig = new
File("resources/jaxws/samples/wsrm/cxf.xml").toURL();
Bus bus = busFactory.createBus(cxfConfig);
busFactory.setDefaultBus(bus);
// create service
QName serviceName = new QName("http://www.jboss.org/jbossws/wsextensions/wsrm", "SimpleService");
URL wsdlURL = new URL(serviceURL + "?wsdl");
Service service = Service.create(wsdlURL, serviceName);
SimpleService proxy =
(SimpleService)service.getPort(SimpleService.class);
// invoke methods
proxy.ping(); // one way call
proxy.echo("Hello World!"); // request responce call
// shutdown bus
bus.shutdown(true);
}

27

Web Services CXF User Guide

}

28

CHAPTER 9. WS POLICY FRAMEWORK

CHAPTER 9. WS POLICY FRAMEWORK
The calculation of the effective policy for each message as well as verification that the alternatives for
that policy are supported happens in interceptors.

9.1. USING THE POLICIES FEATURE
The policies feature supports the following attributes:
ignoreUnknownAssertions
Indicates an exception should be thrown when encountering assertions for which no
AssertionBuilders are registered (default:true). When set to false, a warning will be logged instead.
namespace
The namespace of the WS-Policy Framework specification (default: http://www.w3.org/ns/wspolicy).
The element also supports the following child elements:
alternativeSelector
A bean or reference to a bean that implements the
org.apache.cxf.ws.policy.selector.AlternativeSelector interface. The default
selector chooses the minimal alternative; that is, the one with the least number of assertions.
In addition, the element can have any number of Policy or PolicyReference child elements. This has the
same effect as if the Policy or PolicyReference elements were attached to the wsdl:port element of
the WSDL contract of the client or server endpoint to which the feature is applied (or to all endpoints if
the feature is applied to the bus).
For example, to apply this feature to the bus and prevent exceptions being thrown when encountering
unknown assertions:








9.2. SPECIFYING THE LOCATION OF EXTERNAL ATTACHMENTS

29

Web Services CXF User Guide

To specify the location of an external attachment that the policy framework should take into
consideration when aggregating the policies applying to a specific message, you can use the
 element in the same namespace. The following attribute is supported.
location
Location of the external attachment document. This takes the form of
http://static.springsource.org/spring/docs/2.0.x/reference/resources.html type property, for
example, classpath:etc/policies.xml or file:///x1/resources/polcies.xml.
Below is an example:

You can have any number of  elements in your configuration file.

30

CHAPTER 10. WS-SECURITY

CHAPTER 10. WS-SECURITY
WS-Security provides the means to secure your services beyond transport level protocols such as
HTTPS. Through a number of standards such as XML-Encryption, and headers defined in the WSSecurity standard, it allows you to:
Pass authentication tokens between services.
Encrypt messages or parts of messages.
Sign messages.
Timestamp messages.
Currently, CXF implements WS-Security by integrating WSS4J. To use the integration, you'll need to
configure these interceptors and add them to your service or client respectively.

10.1. OVERVIEW OF ENCRYPTION AND SIGNING
WS-Security makes heavy use of public and private key cryptography. It is helpful to understand these
basics to really understand how to configure WS-Security. With public key cryptography, a user has a
pair of public and private keys. These are generated using a large prime number and a key function.

The keys are related mathematically, but cannot be derived from one another. With these keys we can
encrypt messages. For example, if Bob wants to send a message to Alice, he can encrypt a message
using her public key. Alice can then decrypt this message using her private key. Only Alice can decrypt
this message as she is the only one with the private key.

Messages can also be signed. This allows you to ensure the authenticity of the message. If Alice wants
to send a message to Bob, and Bob wants to be sure that it is from Alice, Alice can sign the message
using her private key. Bob can then verify that the message is from Alice by using her public key.

31

Web Services CXF User Guide

32

CHAPTER 11. WSS4J SECURITY ON JBOSS

CHAPTER 11. WSS4J SECURITY ON JBOSS
Here is a brief chapter on how to use Chapter 10, WS-Security on JBossWS-CXF. Here you'll find some
explanations on how to create a simple application and what you need to do to leverage WSS4J
security on JBoss.

11.1. CREATING THE WEB SERVICE ENDPOINT
First of all you need to create the web service endpoint or client using JAX-WS. This can be achieved in
many ways. For instance you might want to:
1. Write your endpoint implementation, then run the wsprovide JBoss command line tool which
generates the service contract.
2. Run the wsconsume JBoss command line tool to get the client artifacts from the service
contract (top-down approach).
3. Write your client implementation.

11.2. TURN ON WS-SECURITY
WSS4J security is triggered through interceptors that are added to the service and client individually
or as required. These interceptors allow you to perform the most common WS-Security related
processes:
Pass authentication tokens between services.
Encrypt messages or parts of messages.
Sign messages.
Timestamp messages.
Interceptors can be added either programmatically or through the Spring xml configuration of
endpoints. For instance, on server side, you can configure signature and encryption in the jbosswscxf.xml file this way:



























34

CHAPTER 11. WSS4J SECURITY ON JBOSS

This specifies the whole security configuration (including algorithms and elements to be signed or
encrypted); moreover it references a properties file (bob.properties) providing the keystorerelated information:

org.apache.ws.security.crypto.provider=org.apache.ws.security.components.c
rypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.keystore.alias=bob
org.apache.ws.security.crypto.merlin.file=bob.jks
As you can see in the jbossws-cxf.xml file above, a keystore password callback handler is also
configured; while the properties file has the password for the keystore, this callback handler is used to
set password for each key (it has to match the one used when each key was imported in the store).
Here is an example:
package org.jboss.test.ws.jaxws.samples.wsse;
import java.io.IOException;
import java.util.HashMap;
import java.util.Map;
import
import
import
import

javax.security.auth.callback.Callback;
javax.security.auth.callback.CallbackHandler;
javax.security.auth.callback.UnsupportedCallbackException;
org.apache.ws.security.WSPasswordCallback;

public class KeystorePasswordCallback implements CallbackHandler
{
private Map passwords = new HashMap();
public KeystorePasswordCallback()
{
passwords.put("alice", "password");
passwords.put("bob", "password");
}
public void handle(Callback[] callbacks) throws IOException,
UnsupportedCallbackException
{
for (int i = 0; i < callbacks.length; i++)
{
WSPasswordCallback pc = (WSPasswordCallback)callbacks[i];
String pass = passwords.get(pc.getIdentifer());
if (pass != null)
{
pc.setPassword(pass);
return;
}
}
}
public void setAliasPassword(String alias, String password)
{

35

Web Services CXF User Guide

passwords.put(alias, password);
}
}
On the client side, you can similarly setup the interceptors programmatically; here is an excerpt of the
client for the above described endpoint:
Endpoint cxfEndpoint = client.getEndpoint();
Map outProps = new HashMap();
outProps.put("action", "Timestamp Signature Encrypt");
outProps.put("user", "alice");
outProps.put("signaturePropFile", "META-INF/alice.properties");
outProps.put("signatureKeyIdentifier", "DirectReference");
outProps.put("passwordCallbackClass",
"org.jboss.test.ws.jaxws.samples.wsse.KeystorePasswordCallback");
outProps.put("signatureParts", "{Element}{http://docs.oasisopen.org/wss/2004/01/oasis-200401-wss-wssecurity-utility1.0.xsd}Timestamp;{Element}
{http://schemas.xmlsoap.org/soap/envelope/}Body");
outProps.put("encryptionPropFile", "META-INF/alice.properties");
outProps.put("encryptionUser", "Bob");
outProps.put("encryptionParts", "{Element}
{http://www.w3.org/2000/09/xmldsig#}Signature;{Content}
{http://schemas.xmlsoap.org/soap/envelope/}Body");
outProps.put("encryptionSymAlgorithm",
"http://www.w3.org/2001/04/xmlenc#tripledes-cbc");
outProps.put("encryptionKeyTransportAlgorithm",
"http://www.w3.org/2001/04/xmlenc#rsa-1_5");
WSS4JOutInterceptor wssOut = new WSS4JOutInterceptor(outProps); //request
cxfEndpoint.getOutInterceptors().add(wssOut);
cxfEndpoint.getOutInterceptors().add(new SAAJOutInterceptor());
Map inProps= new HashMap();
inProps.put("action", "Timestamp Signature Encrypt");
inProps.put("signaturePropFile", "META-INF/alice.properties");
inProps.put("passwordCallbackClass",
"org.jboss.test.ws.jaxws.samples.wsse.KeystorePasswordCallback");
inProps.put("decryptionPropFile", "META-INF/alice.properties");
WSS4JInInterceptor wssIn = new WSS4JInInterceptor(inProps); //response
cxfEndpoint.getInInterceptors().add(wssIn);
cxfEndpoint.getInInterceptors().add(new SAAJInInterceptor());

11.2.1. Package and deploy
To deploy your web service endpoint, you need to package the following files along with your service
implementation and WSDL contract:
1. The jbossws-cxf.xml descriptor.
2. The properties file.
3. The keystore file (if required for signature/encryption).
4. The keystore password callback handler class.

36

CHAPTER 11. WSS4J SECURITY ON JBOSS

For instance, here are the archive contents for the signature and encryption sample (POJO endpoint)
mentioned before:
[cxf-tests]$ jar -tvf target/test-libs/jaxws-samples-wsse-sign-encrypt.war
0 Tue Jun 03 19:41:26 CEST 2008 META-INF/
106 Tue Jun 03 19:41:24 CEST 2008 META-INF/MANIFEST.MF
0 Tue Jun 03 19:41:26 CEST 2008 WEB-INF/
0 Tue Jun 03 19:41:26 CEST 2008 WEB-INF/classes/
0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/
0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/
0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/
0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/org/jboss/test/ws/
0 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/
0 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/
0 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsse/
1628 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsse/KeystorePasswordCallback.
class
364 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsse/ServiceIface.class
859 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsse/ServiceImpl.class
0 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsse/jaxws/
685 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsse/jaxws/SayHello.class
1049 Tue Jun 03 19:41:24 CEST 2008 WEBINF/classes/org/jboss/test/ws/jaxws/samples/wsse/jaxws/SayHelloResponse.cl
ass
2847 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/jbossws-cxf.xml
0 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/wsdl/
1575 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/wsdl/SecurityService.wsdl
641 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/wsdl/SecurityService_schema1.xsd
1820 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/bob.jks
311 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/classes/bob.properties
573 Tue Jun 03 19:41:24 CEST 2008 WEB-INF/web.xml
On client side, instead, you only need the properties and keystore files (assuming you set up the
interceptors programmatically). You just need to deploy and test your WS-Security-enabled
application.

11.3. WS-SECURITY POLICIES
JBossWS-CXF also includes CXF WS-Security Policy implementation, which can be used to configure
WS-Security more easily. Instead of manually configuring interceptors in the client or through the
jbossws-cxf.xml descriptor, you simply provide the right policies in the WSDL contract.
...


...















































...

38

CHAPTER 11. WSS4J SECURITY ON JBOSS

A few properties are also required to be set either in the message context or in the jbosswscxf.xml descriptor.
1. ((BindingProvider)proxy).getRequestContext().put(SecurityConstants.CALLBACK_HANDLER,
new KeystorePasswordCallback());
2. ((BindingProvider)proxy).getRequestContext().put(SecurityConstants.SIGNATURE_PROPERTIES,
Thread.currentThread().getContextClassLoader().getResource("META-INF/alice.properties"));
3. ((BindingProvider)proxy).getRequestContext().put(SecurityConstants.ENCRYPT_PROPERTIES,
Thread.currentThread().getContextClassLoader().getResource("META-INF/alice.properties"));










11.4. AUTHENTICATION
Read this section to learn how to authenticate a web service user using a number of available methods.
Task: Authenticate a Web Service User
Task Summary
The following procedure describes how to authenticate a web service user with JBossWS.
1. Secure access to the Stateless Session Bean

39

Web Services CXF User Guide

Secure access to the Stateless Session Bean (SLSB) using the @RolesAllowed, @PermitAll,
@DenyAll annotations.
The allowed user roles can be set with these annotations both on the bean class and on any of
its business methods.
@Stateless
@RolesAllowed("friend")
public class EndpointEJB implements EndpointInterface
{
...
}
2. Secure POJO endpoints
Secure Plain Old Java Object (POJO) endpoints by defining a  in the
WEB-INF/web.xml file of the application. The   element
specifies whether authentication is mandatory. It can be set to "not required" by specifying an
asterisk value in the  element.


All resources
/*


friend



friend

3. Define the security domain for EJB3 endpoints
Declare the security domain by appending the @SecurityDomain annotation
@Stateless
@SecurityDomain("JBossWS")
@RolesAllowed("friend")
public class EndpointEJB implements EndpointInterface
{
...
}
You can also modify JBOSS_HOME/server/PROFILE/deploy/jbossws.sar/jbossmanagement.war/WEB-INF/jboss-web.xml and specify the security domain.

JBossWS


40

CHAPTER 11. WSS4J SECURITY ON JBOSS

NOTE
For more information about Security Domains, refer to the JBoss Security Guide.
4. Define the security domain for POJO endpoints
Modify the JBOSS_HOME/server/PROFILE/deploy/jbossws.sar/jbossmanagement.war/WEB-INF/jboss-web.xml and specify the security domain.

JBossWS

5. Define the security context
Configure the security context in the JBOSS_HOME/server/PROFILE/conf/loginconfig.xml file.




props/jbosswsusers.properties
props/jbosswsroles.properties
anonymous




NOTE
The default UsersRolesLoginModule should be changed to another login
module that offers security suitable for your enterprise deployment. Follow
Task: Enable LDAP Authentication for steps to use the LdapLoginModule to
control user authentication.
6. Define HTTP basic authentication for EJB3 endpoints
Use @WebContext annotation on the bean class.
@Stateless
@SecurityDomain("JBossWS")
@RolesAllowed("friend")
@WebContext(contextRoot="/my-cxt", urlPattern="/*",
authMethod="BASIC", transportGuarantee="NONE",
secureWSDLAccess=false)

41

Web Services CXF User Guide

public class EndpointEJB implements EndpointInterface
{
...
}
7. Define HTTP basic authentication for POJO endpoints
Add into WEB-INF/web.xml of your web application

BASIC
Test Realm

8. Client side - set username and password
A web service client can use the javax.xml.ws.BindingProvider interface to set the
username and password combination.
URL wsdlURL = new File("resources/jaxws/samples/context/WEBINF/wsdl/TestEndpoint.wsdl").toURL();
QName qname = new QName("http://org.jboss.ws/jaxws/context",
"TestEndpointService");
Service service = Service.create(wsdlURL, qname);
port = (TestEndpoint)service.getPort(TestEndpoint.class);
BindingProvider bp = (BindingProvider)port;
bp.getRequestContext().put(BindingProvider.USERNAME_PROPERTY,
"jsmith");
bp.getRequestContext().put(BindingProvider.PASSWORD_PROPERTY,
"PaSSw0rd");
9. Client side - WSDL secured
Use java.net.Authenticator to set username and password when accessing wsdl file.
Authenticator.setDefault(new Authenticator() {
protected PasswordAuthentication getPasswordAuthentication() {
return new
PasswordAuthentication(username,password.toCharArray());
}
});
Service service = Service.create(wsdlURL, qname);
Task: Enable LDAP Authentication
Task Summary
Follow this task to configure Lightweight Directory Access Protocol (LDAP) authentication for a
JBossWS application. You use the LdapLoginModule as described in the JBoss Security Guide.
The initial configuration is the same as Task: Authenticate a Web Service User .
1. Secure access to the Stateless Session Bean
Secure access to the Stateless Session Bean (SLSB) using the @RolesAllowed, @PermitAll,
@DenyAll annotations.

42

CHAPTER 11. WSS4J SECURITY ON JBOSS

The allowed user roles can be set with these annotations both on the bean class and on any of
its business methods.
@Stateless
@RolesAllowed("friend")
public class EndpointEJB implements EndpointInterface
{
...
}
2. Secure POJO endpoints
Secure Plain Old Java Object (POJO) endpoints by defining a  in the
WEB-INF/web.xml file of the application.
The   element specifies whether authentication is mandatory.
It can be set to "not required" by specifying an asterisk (*) value in the  element.


All resources
/*


*



BASIC
JBossWS


NOTE
For more information about valid  values, refer to the Web
Content Security Constraints section of the JBoss Security Guide.
3. Define the security domain
Declare the security domain by appending the @SecurityDomain annotation
@Stateless
@SecurityDomain("JBossWS")
@RolesAllowed("friend")
public class EndpointEJB implements EndpointInterface
{
...
}
You can also modify JBOSS_HOME/server/PROFILE/deploy/jbossws.sar/jbossmanagement.war/WEB-INF/jboss-web.xml and specify the security domain.

43

Web Services CXF User Guide


JBossWS


NOTE
For more information about Security Domains, refer to the JBoss Security Guide.
4. Define the security context
Configure the security context in the JBOSS_HOME/server/PROFILE/conf/loginconfig.xml file.



com.sun.jndi.ldap.LdapCtxFactory<
/module-option>
ldap://ldaphost.jboss.org:1389/
simple
uid=
,ou=People,dc=jboss,dc=org
ou=Roles,dc=jboss,dc=org
member
true
cn
false





NOTE
Refer to the Security Guide for information about the LdapLoginModule and
other available login modules.

11.4.1. Java Authentication and Authorization Service
Starting EAP 5.1.1 the username token information can be used for Java Authentication and
Authorization Service (JAAS) on JBoss EA

44

CHAPTER 11. WSS4J SECURITY ON JBOSS

Procedure 11.1. On the Server
Specify Interceptors
Specify (possibly by using a jbossws-cxf.xml descriptor):
1. An interceptor for performing authentication and populating a valid SecurityContext;
the provided interceptor should extend
org.apache.cxf.ws.security.wss4j.AbstractUsernameTokenAuthenticating
Interceptor.
JBossWS integration comes with
org.jboss.wsf.stack.cxf.security.authentication.SubjectCreatingInter
ceptor for this use.
2. An interceptor for performing authorization; CXF requires this to extend
org.apache.cxf.interceptor.security.AbstractAuthorizingInIntercepto
r.
For instance, the SimpleAuthorizingInterceptor can be used for mapping endpoint
operations to allowed roles.
Example 11.1. SimpleAuthorizingInterceptor











45

Web Services CXF User Guide













Authentication and authorization will be delegated to the security domain configured for the
endpoint.

NOTE
You can specify the login module you prefer for that security domain.
Refer to the Login Modules chapter of the JBoss Enterprise Application Platform
Security Guide at docs.redhat.com for more information on this topic.
Procedure 11.2. On the Client
1. Ensure the username is provided through the API (or a custom Spring configuration used to
load the Bus):
Example 11.2. Username API
Endpoint cxfEndpoint = client.getEndpoint();
Map outProps = new HashMap();
outProps.put("action", "UsernameToken");
outProps.put("user", username);
outProps.put("passwordType", "PasswordText");
outProps.put("passwordCallbackClass",
"org.jboss.test.ws.jaxws.samples.wsse.UsernamePasswordCallback");
WSS4JOutInterceptor wssOut = new WSS4JOutInterceptor(outProps);
//request
cxfEndpoint.getOutInterceptors().add(wssOut);
cxfEndpoint.getOutInterceptors().add(new SAAJOutInterceptor());

46

CHAPTER 11. WSS4J SECURITY ON JBOSS

2. The password instead is provided through a password callback handler that needs to
implement javax.security.auth.callback.CallbackHandler, similarly to the
keystore's password callback handler.
If you are using an older JBossWS-CXF version, or you are not configuring the application
server authorization integration, you can use a password callback handler on server side too,
configured through a WSS4JInInterceptor:
Example 11.3. Callback Handler






Example 11.4. WSS4JInInterceptor callback handler
package org.jboss.test.ws.jaxws.samples.wsse;
import
import
import
import

java.io.IOException;
javax.security.auth.callback.CallbackHandler;
javax.security.auth.callback.UnsupportedCallbackException;
org.apache.ws.security.WSPasswordCallback;

public class ServerUsernamePasswordCallback implements
CallbackHandler
{
public void handle(Callback[] callbacks) throws IOException,
UnsupportedCallbackException
{
WSPasswordCallback pc = (WSPasswordCallback)callbacks[0];
if (!("kermit".equals(pc.getIdentifier()) &&
"thefrog".equals(pc.getPassword())))
throw new SecurityException("User '" +
pc.getIdentifier() + "' with password '" + pc.getPassword() + "'
not allowed.");
}
}

11.5. FURTHER INFORMATION
11.5.1. Samples

47

Web Services CXF User Guide

The JBossWS-CXF source distribution comes with some samples using X.509 certificate signature and
encryption as well as Username Token Profile. You can find them in package
org.jboss.test.ws.jaxws.samples.wsse

11.5.2. Username/password configuration
When using the Username Token Profile, the username and password are provided and verified
through two callback handlers that you need to provide. As the keystore password callback handler,
they need to implement javax.security.auth.callback.CallbackHandler; they are configured in
jbossws-cxf.xml (or programmatically) through the passwordCallbackClass attribute.

11.5.3. Crypto Algorithms
When requiring encryption, you might need to install an additional JCE provider supporting the crypto
algorithms Apache CXF uses. This usually means the Bouncy Castle provider needs to be configured in
your Java Runtime Environment ( JRE ). Please refer to the Installing the BouncyCastle JCE provider
section of the Administration and Configuration guide for further information about this.

48

CHAPTER 12. SOAP MESSAGE LOGGING

CHAPTER 12. SOAP MESSAGE LOGGING
The cxf-extension-jbossws.xml file contains the JBossWS extensions to the Apache CXF stack.
You need to manually add this file and link it in the cxf.extensions file. In cxf-extensionjbossws-xml you need to enable:











Once you've uncommented the cxf-extension-jbossws.xml contents, you need to re-pack the jar
or zip. Alternatively, Apache CXF offers multiple ways of configuring SOAP message logging; for
programmatic configuration, the below annotations can be used on either the SEI or the SEI
implementation class. If placed on the SEI, they activate logging both for client and server; if on the SEI
implementation class, they are relevant just for server-side logging.

@javax.jws.WebService(portName = "MyWebServicePort", serviceName =
"MyWebService", ...)
@Features(features = "org.apache.cxf.feature.LoggingFeature")
public class MyWebServicePortTypeImpl implements MyWebServicePortType {

Or equivalent:
import org.apache.cxf.interceptor.InInterceptors;
import org.apache.cxf.interceptor.OutInterceptors;
@javax.jws.WebService(portName = "WebServicePort", serviceName =
"WebServiceService", ...)
@InInterceptors(interceptors =
"org.apache.cxf.interceptor.LoggingInInterceptor")
@OutInterceptors(interceptors =
"org.apache.cxf.interceptor.LoggingOutInterceptor")
public class WebServicePortTypeImpl implements WebServicePortType {
For programmatic client-side logging, the following code snippet can be used as an example:
import
import
import
import

org.apache.cxf.endpoint.Client;
org.apache.cxf.frontend.ClientProxy;
org.apache.cxf.interceptor.LoggingInInterceptor;
org.apache.cxf.interceptor.LoggingOutInterceptor;

public class WSClient {
public static void main (String[] args) {
MyService ws = new MyService();

49

Web Services CXF User Guide

MyPortType port = ws.getPort();
Client client = ClientProxy.getClient(port);
client.getInInterceptors().add(new LoggingInInterceptor());
client.getOutInterceptors().add(new LoggingOutInterceptor());
// make WS calls...
Finally, you can also enable message logging using the Logging feature.









12.1. DEBUGGING TOOLS
Here is a list of tools that can be used to capture exchanged messages:
Tcpmon
TCPMon allows you to easily view messages as they go back and forth on the wire.
WSMonitor
WSMonitor is another option to Tcpmon with slightly more functionality.
SOAP UI
SOAP UI can also be used for debugging. In addition to viewing messages, it allows you send
messages and load test your services. It also has plug-ins for Eclipse, IDEA and NetBeans.
Wireshark
Wireshark, a network packet analyzer, is useful for following the routing of SOAP messages. It can
also help when you are getting an HTML error message from the server that your CXF client cannot
normally process, by allowing you to see the non-SOAP error message.

50

APPENDIX A. REVISION HISTORY

APPENDIX A. REVISION HISTORY
Revision 5.2.0-100.400

2013-10-31

Rüdiger Landmann

Wed 23 Jan 2013

Russell Dickenson

Rebuild with publican 4.0.0

Revision 5.2.0-100

Incorporated changes for JBoss Enterprise Application Platform 5.2.0 GA. For information about documentation changes to
this guide, refer to Release Notes 5.2.0.

Revision 5.1.2-100

Thu 8 December 2011

Russell Dickenson

Incorporated changes for JBoss Enterprise Application Platform 5.1.2 GA. For information about documentation changes to
this guide, refer to Release Notes 5.1.2.

51



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : No
Title                           : Web Services CXF User Guide
Creator                         : wkhtmltopdf 0.12.2.1
Producer                        : Qt 4.8.6
Create Date                     : 2017:10:12 20:58:32-04:00
Page Count                      : 55
Page Mode                       : UseOutlines

EXIF Metadata provided by EXIF.tools