AXIS2 WEB SERVICES AND SECURITY COOKBOOK

thumbsshameΔιακομιστές

17 Νοε 2013 (πριν από 3 χρόνια και 10 μήνες)

204 εμφανίσεις


Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/


AXIS2 WEB SERVICES AND SECURITY COOKBOOK
Implementing WS-Security with Apache Axis2, Rampart and Tomcat


Hugo Gabignon
<hgabigno@etud.insa-toulouse.fr>
Thibaut Probst
<probst@etud.insa-toulouse.fr>
Abstract


Enterprise-level web services deal with sensitive information which is a critical asset
to a business. This cookbook presents a very powerful open-source framework for web
services development, deployment and monitoring: Apache Axis2. This Java engine is a way
for common users to easily manage their web services and add additional modules such
as Apache Rampart, which implements security features. Thus, the cookbook also quickly
introduces different techniques for securing the messages exchanged between the components
of a Web services architecture. Emphasis is placed on the Web Services Security (WS-Security)
specification from W3C, which operates on SOAP messages to ensure end-to-end security.
This is done using XML Security features: message signature, encryption and authentication.
The first recipe shows how to install Apache Axis2 and Apache Rampart (the main
components needed to provide security features in Web Services) on an Apache Tomcat7 (the
most popular Web container) fresh installation. A second recipe explains how to configure the
IDE we use, Eclipse, to work with our Web Services environment. A third recipe shows the
creation of a simple Web Service with Eclipse, and a fourth one explains how to configure it
following a certain security policy, and also how to generate its matching client.



INSA - 5 RT 2011
1



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Table of Contents

Abstract
Table

of

Contents
Introduction
Prerequisites
The

Ingredients
:
Definitions

and

Terminology
Recipe
1:
Installing

Axis
2
and

Rampart

on

an

Apache

Tomcat
7
fresh

installation
Step
1
Step
2
Step
3
Recipe
2:
Configuring

the

Eclipse

IDE

to

work

with

this

new

working

environment
Step
1
Step
2
Step
3
Recipe
3:
Developing

a

Web

service

with

Eclipse

IDE
Step
1
Step
2
Step
3
Where

We

Are

So

Far
:
an

Unsecured

Web

Service
.
Recipe
4:
Configure

security

features

in

a

Web

service

and

generate

a

matching

client
Part
1:
server

configuration
Step
1
Step
2
Part
2:
Client

generation
Step
1
Step
2
Step
3
Step
4
Step
5
Step
6
Step
7
Recommended

Documentation
Feedback


INSA - 5 RT 2011
2



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Introduction
Nowadays, Web services are a very widespread mechanism in distributed programming,
and many risks of attacks are present in unsecured Web services where messages are
exchanged between remote objects in clear text. For instance, when there is no security layer, a
common possible attack is the Man In The Middle (MITM) attack, where an attacker (someone
not supposed to be part of the conversation between two entities) intercepts the messages
exchanged by making two independent connections (one with each entity), and relays them.
The communicating entities are unable to know they are being eavesdropped upon, thinking
they are sending and receiving messages to each other.
It seems obvious that security features need to be brought to such an infrastructure. This
cookbook aims to provide the reader with solutions for securing a Web services infrastructure,
adding integrity, authentication and encryption features, as it is very important to take security
into account. Since the SOAP standard relies on XML, the next sections focus on how to
implement messages signatures, encryption and authentication in XML syntax by using
sophisticated tools. We thus need a powerful and modular framework to manage Web services.
This is why we will focus on the Apache Axis2 framework. Based on a modular architecture, this
tool allows different modules to act at different phases of the emission and reception of a SOAP
message. One of these modules, called Rampart, allows us to implement security.
INSA - 5 RT 2011
3



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Figure from
http
://
axis
.
apache
.
org
/
axis
2/
java
/
core
/
docs
/
userguide
.
html
In this cookbook, you will learn how to install and configure Axis2 and Rampart, and
moreover, how to first deploy a Web service using those tools. You will also understand how to
apply a security policy to your Web service. Keep in mind that we will provide security from an
end-to-end (i.e. client-to-server) point of view: on the SOAP message level. A good security
policy to avoid MITM attack is a public-key encryption, signing and ciphering (using a public key)
/deciphering (using a private key) messages, considering the attacker cannot intercept the
public keys exchanged (otherwise a Public Key Infrastructure is required to sign the certified
keys).




INSA - 5 RT 2011
4



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/


Prerequisites

We will be using an already-installed infrastructure of Web service based on a servlet
container and using an Integrated Development Environment (IDE). Therefore, we will not
explain here the procedure for installing and configuring the main tools mentioned further down,
as this is not the goal of this cookbook. The servlet container is Apache Tomcat 7.0, composed
of:


Catalina: the application server (which contains the implemented servlets);

Coyote HTTP/1.1: the connector which receives and transfers the HTTP messages from
the network to the application server and from the application server to the network. In
our case, it is also a Web server;

Jasper: the JSP engine.

We use Eclipse as IDE with Java Enterprise Edition (Java EE) to develop (classes,
interfaces, ...) the features of our Web services. The Web Tools Platform (WTP) is also required
as a set of tools to develop Java EE and Web applications.

Starting with this infrastructure, we will explain how to install and use Apache Axis2 and
Rampart. The Apache Axis2 framework is in charge of the XML code generation from Java
classes, and the WSDL file generation from Java code as well as the reverse. It will also be
the main servlet of our Web services. Apache Rampart is the security module used in Axis2.
It intercepts messages before they are sent or received and alters them to add or remove the
security layers we will define in the last recipes.
INSA - 5 RT 2011
5



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/


To learn more about all these technologies, please refer to the next section.




INSA - 5 RT 2011
6



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/











Note that this cookbook requires basic UNIX and programming skills, and we assume that the
reader has some knowledge in Web services development and security.
The Ingredients: Definitions and Terminology

SOAP
(formerly Simple Object Access Protocol) is the main protocol for exchanging Web
services messages. It is usually based on HTTP (HyperText Transfer Protocol), although some
other protocols, like SMTP, can be used to carry SOAP messages. The syntax of the messages
INSA - 5 RT 2011
7



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
is standardized by XML, and is structured with an envelope containing a header and the body of
the message.

WSDL
(Web Services Description Language) is an XML-based format that describes how to
use a Web service: protocol, message format, methods to be invoked, location of the service,
ciphers, etc.

Java EE
(Java Enterprise Edition) is a Java platform which implements libraries providing
features to deploy Web-based or rich enterprise applications online.

Servlet
is a Java EE class processing (mainly HTTP) requests and responses to define the
behaviour of the methods.

Apache Tomcat
is a Java EE servlet container developed by the Apache Foundation. It is
composed of an HTTP connector (Coyote HTTP/1.1), an application server (Catalina), and a
JSP engine (Jasper). The current version is 7.0.

Apache Axis
(Apache eXtensible Interaction System) is an implementation of the SOAP
protocol developed by the Apache Foundation. It allows the deployment, testing and monitoring
of Web services, the automatized creation of WSDL files (on the server side), the generation
of Java code from a WSDL file (on the client side) and the serialization/deserialization of Java
object in SOAP messages (as a servlet).

Apache Axis2
is the successor of Apache Axis, including many new features making it more
powerful, flexible and efficient. It also includes additional modules such as Apache Rampart.

Apache Rampart
is a security module for Axis2, and a implementation of the WS-Security
specification by the W3C. It intercepts ingoing and outgoing messages and modifies or checks
them if necessary.

WS-Security
(Web Services Security) is a member of the WS-* (Web Services-*) specifications
conducted by the
Organization for the Advancement of Structured Information Standards
(OASIS). It aims to describe the three main mechanisms for securing SOAP messages
:

signature, encryption and authentication.

Eclipse
is an Integrated Development Environment, designed at first to develop Java
applications. Its modularity and huge community made it a main choice for many other
applications (C++ development, Real-time with TOPCASED, etc.).

INSA - 5 RT 2011
8



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
XML
is eXtensible Markup Language. Its main advantage is its ability to define new formats
(such as the WSDL) easily by creating new markups and describing them in document format
files (DTD/XSD).

WAR
is a Web ARchive allowing the easy deployment of a Java EE application in a servlet
container: usually, the administrator only has to drop the WAR file in a specific folder for the
application to be immediately deployed and run.

INSA - 5 RT 2011
9



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Recipe 1: Installing Axis2 and Rampart on an Apache
Tomcat 7 fresh installation

This recipe was written using the
tomcat7
package from Ubuntu 11.10. Therefore, installation
paths may differ from your settings. Please refer to your Linux distribution documentation for
more information about where your Tomcat server is located.

This recipe introduces the use of Apache Axis2, a SOAP/WSDL/Web service engine. It
is the successor of Apache Axis, which was only a SOAP stack. Apache Axis2 is a framework
which can simplify a lot of tasks in the development of a Web service, as you will see further on
in the cookbook. However, we will use it here as a servlet for a more widely known container:
Apache Tomcat.

Step 1

For Axis2 to be used within Tomcat, download the WAR (Web Archive) distribution from the
Apache Foundation Website:
http
://
axis
.
apache
.
org
/
axis
2/
java
/
core
/
download
.
cgi
.

Step 2

Unzip the distribution:

user@system:~$ unzip axis2-war-1.6.1.zip

You will get an axis2.war file. This file must be dropped in the Webapps folder of Tomcat. The
server will then automatically extract the Web archive and configure and run the Axis2 servlet.
Tomcat 7 installation is by default located in
/var/lib/tomcat7/


user@system:~$ cp axis2.war /var/lib/tomcat7/Webapps/
user@system:~$ service tomcat7 restart

Open a Web browser and go to
http
://
localhost
:8080/
axis
2
. You should see a Web page similar
to this one:
INSA - 5 RT 2011
10



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/

If yes, Axis2 is running on your Tomcat installation.

Step 3

The next step is to insert the Rampart module into the Axis2 installation. Get Rampart from:
http
://
axis
.
apache
.
org
/
axis
2/
java
/
rampart
/
download
/1.6.1/
download
.
cgi
.

The standard installation process begins with unzipping the downloaded Rampart archive:

user@system:~$ unzip rampart-dist-1.6.1-bin.zip

This will give you a rampart-1.6.1 folder. Then, copy the MAR module into the Axis2 installation
folder:
user@system:~$ cp rampart-1.6.1/lib/* /var/lib/tomcat7/Webapps/axis2/
Web-INF/lib
INSA - 5 RT 2011
11



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
user@system:~$ cp rampart-1.6.1/modules/* /var/lib/tomcat7/Webapps/
axis2/Web-INF/modules

and restart Tomcat 7:

user@system:~$ service tomcat7 restart

Go to
http
://
localhost
:8080/
axis
2/
axis
2-
admin
and log in with admin/axis2 credentials.
Check that you have rampart and rahas in the available modules.


If so, congratulate yourself, have a cup of coffee/tea/milk/whatever you like and prepare for the
next step: configuring Eclipse IDE to work with your new Web Services environment!






INSA - 5 RT 2011
12



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Recipe 2: Configuring the Eclipse IDE to work with
this new working environment

This recipe introduces the configuration of Eclipse to make it work with your Web Services
environment, including WTP, Apache Tomcat, Apache Axis2 and Apache Rampart.

Step 1

The first thing to do is install the Eclipse WTP in your IDE.

Open Eclipse, click on Help on the command bar, and select Install New Software....
Be sure to work with --All Available Sites--.
Select the Web, XML, and Java EE Development item and click on Next.


Eclipse will compute the dependencies. Make sure all the packages are selected and click on
Finish.

INSA - 5 RT 2011
13



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/


Step 2

Now you have to tell Eclipse where the Axis2 runtime (axis2.war) is located.

Click on Window > Preferences
Under Web Services, click on Axis2 Preferences and set the Axis runtime location to
/var/
lib/tomcat7/Webapps
.
IMPORTANT: this path MUST NOT end with a slash (“/”)

You should get an “Axis2 runtime loaded successfully” message.

Step 3

The next step consists in setting the Tomcat server in Eclipse. This will allow us to perform real-
time compilation of the Web service and testing in the Eclipse environment (whereas in normal
time, you would deploy the application each time you would like to try it).

Click on File > New. In the window that appears, click on ‘Server’ in the Server section.
INSA - 5 RT 2011
14



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
The wizard will ask you for the server settings.

Select the server version (which is 7.0 here), name your server with a specific name, and click
on Next. Then make sure the Tomcat installation directory points to
/usr/share/tomcat7.

Finish the wizard.


Your server will then appear in the Server tab at the bottom of the Eclipse window. You can run
the server by pressing the play button at the top right corner of the tab.

IMPORTANT:
the Tomcat server is here running with a different configuration file (i.e. a different
axis2.xml
file) than the one you set in Windows or your Linux distribution. For instance, you
will not find the Axis2 servlet home page by reaching the
/axis2
URI. So far, the Tomcat 7
server run by Eclipse does not contain any servlet. Every request made to http://localhost:8080
will end up with an HTTP 404 error.

You are now ready to start developing Web services with Eclipse, Tomcat and Axis2!






INSA - 5 RT 2011
15



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Recipe 3: Developing a Web service with Eclipse IDE

This is where the serious business begins. This recipe will explain you how to literally put a Java
class on a Web service, with a few clicks in Eclipse. At the end of this recipe, you will have a
fully working Web Service based on Axis2 and described in WSDL!

Make sure your business logic is in place. The example scenario we will deal with here
is a simple calculator implementing only the addition function. This is implemented as a
JavaCalculator project containing only one
Calculator.java
file, for which code is given
below:

Calculator.java
package
com.hugo.calculator;
public class
Calculator {

public int
addition(int a, int b) {


return
a+b;
}
}


Step 1

The first step consists in creating a Dynamic Web Project. An Eclipse Dynamic Web Project
enables you to code and run your program on an application server, such as Apache Tomcat.
This is the most convenient way to implement servlets in Java EE. This project will host each
one of our webservices and will also be a way to tell Axis2 how to do its job!

Click on New > Other....
Then, in the Web section, click on Dynamic Web Project.
INSA - 5 RT 2011
16



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/

In the window that appears, select the Dynamic Web module in the 2.5 version, and in the
Configuration section, click on Modify....

INSA - 5 RT 2011
17



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/

The Project Facets window will allow you to edit the facets for the configuration of Tomcat in
Eclipse. Select Axis2 Web Services and save your configuration with a custom name. When you
are done, end the wizard.
You should now have a Dynamic Web application in your project Explorer.

Step 2

Add the Rampart/Rahas library and module to your application. Open the folder where you
extracted Rampart and copy the contents of the
lib/
directory into the project in:
WebContent > Web-INF > lib
Do the same with the
modules/
folder, which contents must be pasted into Web
Content >
Web-INF > modules

Step 3

Finally, you can generate your Web Service and place it in the Dynamic Web project you just
made. This step is done with the Eclipse WTP Web services wizard, which will parse your Java
file and create a matching servlet, accessible via

the Tomcat instance declared in Eclipse, and
described in WSDL.

Right click on the Java class you want to make available as a Web service. Click on Web
Services > Create Web Service
INSA - 5 RT 2011
18



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
The Web Services wizard will appear. Make sure to select a Bottom-Up approach. This is the
case here because we have the implementation (the bottom) and want to make it available at a
higher lever. The other approach, Top-Down, is used in Client generation, which we deal with
further in the cookbook.

Select the Start service level, so the WS is accessible right after this wizard. In the
configuration, select your Tomcat 7 server, the Axis2 Web service runtime, and the Dynamic
Web project you just made.
In the next window, click on “Generate a default
services.xml
file”.
Finally, click on Start Server if the Tomcat server is not launched yet. Once this is done, click on
Finish.

Note:

services.xml
is the XML configuration file for the Apache Axis2 servlet. This file
describes where the Web services implementation is located and which Uniform Resource
Identifier (URI) patterns match each Web service.

You should see your Web service in the Servers View.
INSA - 5 RT 2011
19



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
To consult it, right click on your Dynamic Web project and
Run As... > Run on Server.
You will then see your service running at the URL: http://localhost:8080/YourWebProjectName/



The WSDL for your Web service is available at:
http
://
localhost
:8080/
YourWebProjectName
/
services
/
YourWebService
?
wsdl

Make sure that Rampart is in the Available Axis2 modules by going to the Administration
console. (default credentials are admin/axis2)
If so, you have successfully created a Web service with Apache Axis2!



INSA - 5 RT 2011
20



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Where We Are So Far: an Unsecured Web Service.
If we would create the matching Web service client with the current implementation of our
architecture, we would have a perfectly working Web service from the functional point of view,
but with a very low level of information security. Exchanged SOAP messages would not be
encrypted nor signed in a common HTTP transport channel. The two screenshots below show
Wireshark TCP dumps of such a situation.
Request made from the client to the server. Note the
<soap>
envelope.
INSA - 5 RT 2011
21



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Corresponding response.
INSA - 5 RT 2011
22



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Recipe 4: Configure security features in a Web service
and generate a matching client

Did we tell you serious things have already begun? This is where they actually begin. Now you
will learn how to add security to a Web service. This recipe shows how to provide a security
policy for your Web service, such as username tokens or signature and encryption. We will
show you how to use the main elements involved so you understand how to customize your
security configuration.
There are two parts: one for the server configuration, and another one for the client generation
from the new WSDL.

Part 1: server configuration

Step 1

Go back to your installed Web Service on the server. Open your Eclipse IDE and open your
Dynamic Web Project (Calculator), which also contains the Web Service. Remember, we set
all this up in Recipe 3. A file describing the services running in your project is produced by
Axis2. This file is
services.xml.
Open the file, which is located in WebContent->Web-INF-
>services->Calculator->META-INF. The very first parameters define the usual configuration of
an Axis2 web service. After this, insert the type of security you want to add to your service.

Here is an example to define username tokens:
(The bold part describes the policy we want to use.)

services.xml
<service name="Calculator" >
<Description>
Please Type your service description here
</Description>
<messageReceivers>
<messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-only"
class="org.apache.axis2.rpc.receivers.RPCInOnlyMessageReceiver" />
<messageReceiver mep="http://www.w3.org/2004/08/wsdl/in-out"
class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
</messageReceivers>
<parameter name="ServiceClass" locked="false">Calculator</parameter>
INSA - 5 RT 2011
23



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/

<module ref="rampart" />
<module ref="addressing" />

<wsp:Policy wsu:Id="UTOverTransport" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/
oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/
policy/ws-policy.xsd">
<wsp:ExactlyOne>
<wsp:All>
<sp:TransportBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/
securitypolicy">
<wsp:Policy>
<sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken RequireClientCertificate="false"/>
</wsp:Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic128/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Lax/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
</wsp:Policy>
</sp:TransportBinding>
<sp:SignedSupportingTokens xmlns:sp="http://schemas.xmlsoap.org/ws/2005/
07/securitypolicy">
<wsp:Policy>
<sp:UsernameToken sp:IncludeToken="http://
schemas.xmlsoap.org/ws/2005/07/securitypolicy/IncludeToken/AlwaysToRecipient" />
</wsp:Policy>
</sp:SignedSupportingTokens>

<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<ramp:passwordCallbackClass>PWCBHandler</
ramp:passwordCallbackClass>
</ramp:RampartConfig>

</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

</service>
INSA - 5 RT 2011
24



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/

Below is an example of a WS-Security policy for signing and encrypting SOAP messages.
Explanations follow the code.

<wsp:Policy wsu:Id="EncrOnly" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-
wss-wssecurity-utility-1.0.xsd" xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:ExactlyOne>
<wsp:All>
<sp:AsymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/
securitypolicy/IncludeToken/AlwaysToRecipient"/>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Token sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/07/
securitypolicy/IncludeToken/Never">
<wsp:Policy>
<sp:RequireThumbprintReference/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>

<wsp:Policy>
<sp:TripleDesRsa15/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
</wsp:Policy>
</sp:AsymmetricBinding>
<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body/>
</sp:EncryptedParts>

<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<ramp:encryptionUser>clientkey</ramp:encryptionUser>

<ramp:passwordCallbackClass>com.sosnoski.ws.library.adb.PWCBHandler</
ramp:passwordCallbackClass>



<ramp:signatureCrypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</
ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">server.keystore</
ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">nosecret</
ramp:property>
</ramp:crypto>

</ramp:signatureCrypto>



<ramp:encryptionCypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">
INSA - 5 RT 2011
25



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</
ramp:property>
<ramp:property name="org.apache.ws.security.crypto.merlin.file">server.keystore</
ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">nosecret</
ramp:property>
</ramp:crypto>

</ramp:encryptionCypto>
</ramp:RampartConfig>
</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>


This second WS-Security policy defines an asymmetric binding of the client and the server.
You can see that a common secret for a TripleDES symmetric cipher is negotiated between
the client and the server using RSA: the server and the client will exchange cryptographic
parameters encrypted with the other part public key and build a key shared by both of them,
without having to transmit this key over the channel. This key is then used with the TripleDES
cipher to ensure message confidentiality.
Two parts concerning signature (SignatureCrypto) and encryption of the message
(EncryptionCrypto) contain the cryptography configuration for Rampart. They define the JKS
(Java Key Store) file containing the key couples used in the negotiation process, and the
password to decrypt this file. You will find at the end of the cookbook an annex for managing
Java Key Stores.
This is exactly the type of application you can do from the schema shown at the end of the
introduction of the cookbook.

There is a
<ramp:passwordCallbackClass>
tag at the end of the file. Put PWCBHandler
between the tags. If you want to put another name, keep it in mind because we will use it right
now.

Step 2

Create a
PWCBHandler.java
class on the server in the Dynamic Web Project you previously
created.

PWCBHandler.java
package com.hugo;

import java.io.IOException;

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
INSA - 5 RT 2011
26



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
import javax.security.auth.callback.UnsupportedCallbackException;

import org.apache.ws.security.WSPasswordCallback;


public class PWCBHandler implements CallbackHandler {

@Override
public void handle(Callback[] callbacks) throws IOException,
UnsupportedCallbackException {
int i;
//When the server side need to authenticate the user
for (i=0;i<callbacks.length;i++) {
WSPasswordCallback pwcb = (WSPasswordCallback)callbacks[i];
if (pwcb.getIdentifier().equals("
apache
") &&
pwcb.getPassword().equals("
password
")) {
//If authentication successful, simply return
return;
} else {
throw new UnsupportedCallbackException(callbacks[i], "check failed");
}

}
}

}

Configure the username and password you want to be checked, here “apache” and “password”.

Part 2: Client generation

So far, our Web Service is created and running in our environment, but it is still only accessible
via a Web browser, which does not really fit the Web Services definition. Therefore, this recipe
will explain how to use Axis2 to generate Java helpers for the Java EE programmer to create
clients for a specific Web Service, having only its WSDL file stored on the server.

Step 1

Clients only need Axis2 with Apache Rampart and Eclipse IDE with Java EE and WTP tools.
Tomcat is not required on this side of the infrastructure, since no Web service will be hosted on
the client side.
The first step is thus to download the latest version of the Axis2 binary distribution from the
Apache Foundation Website:
http
://
axis
.
apache
.
org
/
axis
2/
java
/
core
/
download
.
cgi
.
INSA - 5 RT 2011
27



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/

Also download Rampart:
http
://
axis
.
apache
.
org
/
axis
2/
java
/
rampart
/
download
/1.6.1/
download
.
cgi
.

Step 2

Unzip the archives:
user@system:~$ unzip rampart-dist-1.6.1-bin.zip

user@system:~$ unzip axis2-1.6.1-bin.zip
user@system:~$ unzip rampart-dist-1.6.1-bin.zip

You can move the extracted
axis2
directory wherever you want in your system. (We put it in
/
opt/.
)
Then include Rampart libraries inside your Axis2.

user@system:~$ cd rampart-1.6.1/
user@system:~/rampart-1.6.1/ ant

Step 3

Make sure your
JAVA_HOME
environment variable is correctly set to your Java Development Kit
(JDK) location, generally located in the
/usr/lib/jvm/
directory.
Do it if you haven’t done it yet:
ser@system:~$ unzip rampart-dist-1.6.1-bin.zip

user@system:~$ export JAVA_HOME="/usr/lib/jvm/java-1.6.0-openjdk/"

Also set the AXIS2_HOME environment variable to your new axis2 directory:

user@system:~$ export AXIS2_HOME="/opt/axis2/"

This is where you will see the power and convenience of Axis2. Axis2 binary tools contain a
code generator and a WSDL generator called respectively
WSDL2Java
and
Java2WSDL
. We
are interested here in producing Java code from WSDL. We will thus use the first tool.

Create a new folder for the code.
INSA - 5 RT 2011
28



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/

user@system:~$ mkdir /home/thibaut/workspace/Client/

Change the current working directory to the
bin/
directory inside your new axis2 directory.

user@system:~$ cd /opt/axis2/bin/

Run the
WSDL2Java
tool, giving two parameters:


the URI, which specifies the location of the WSDL file on the server, and generally looks
like:
http
://
server
:8080/
WebProjectName
/
services
/
WebService
?
wsdl
m:~$ un.6.1-
bin.zip

the directory you created to host the client Java code.
us
user@system:/opt/axis2/bin$ sh wsdl2java.sh -uri http://server:8080/
WebProjectName/services/WebService?wsdl /home/thibaut/workspace/
Client/
er@system:~$ cd /opt/axis2/bin/
This command creates a
build.xml
file which will tell the Apache Ant build tool where the
source code is located and which classes are to be compiled.

Now go to your new project directory.

user@system:/opt/axis2/bin$ cd /home/thibaut/workspace/Client/

Build the client library you will need.

user@system:~/workspace/Client$ ant

You should have a
src/
directory containing the Java client source code package and a
build/
directory containing a
lib/
directory and a
classes/
directory.

Step 4

INSA - 5 RT 2011
29



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
You are almost ready to use your generated client. In your Eclipse IDE, you just have to create
a Java project using the wizard. Click on File->New->Other...->Java->Java Project and Next.

Select “Create project from existing source” and input the directory of your previously generated
project. Click “Finish”. You should see your project in the Project Explorer.

Step 5

You are able to configure your client with the Web service. We will now explain how to query it
in a secure fashion. On the client side, the security policy to apply is described in a specific file
called
policy.xml
. So create a new file called
policy.xml
.

Fill it with these lines to use username tokens:

policy.xml
<wsp:Policy wsu:Id="UTOverTransport" xmlns:wsu="http://docs.oasis-open.org/wss/2
004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd" xmlns:wsp="http://schemas.xm
lsoap.org/ws/2004/09/policy">
<wsp:ExactlyOne>
<wsp:All>
INSA - 5 RT 2011
30



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
<sp:TransportBinding xmlns:sp="http://schemas.xmlsoap.org/ws/200
5/07/securitypolicy">
<wsp:Policy>
<sp:TransportToken>
<wsp:Policy>
<sp:HttpsToken RequireClientCertificate="false"/>
</wsp:Policy>
</sp:TransportToken>
<sp:AlgorithmSuite>
<wsp:Policy>
<sp:Basic128/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Lax/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
</wsp:Policy>
</sp:TransportBinding>
<sp:SignedSupportingTokens xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/
securitypolicy">
<wsp:Policy>
<sp:UsernameToken sp:IncludeToken="http://schemas.xmlsoap.org/ws/
2005/07/securitypolicy/Inc
ludeToken/AlwaysToRecipient" />
</wsp:Policy>
</sp:SignedSupportingTokens>

<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<ramp:user>alice</ramp:user>
<ramp:passwordCallbackClass>com.hugo.PWCBHandler</ramp:passwordCa
llbackClass>
</ramp:RampartConfig>

</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

Note the username (“apache”) is given between the
<ramp:user>
tags. You will also have to
provide the password, which is done in
Step 6
.

Now fill the
policy.xml
file with these lines to apply signature and encryption of messages
instead:

policy.xml
<wsp:Policy wsu:Id="SigEncr"
xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-
utility-1.0.xsd"
INSA - 5 RT 2011
31



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
xmlns:wsp="http://schemas.xmlsoap.org/ws/2004/09/policy">
<wsp:ExactlyOne>
<wsp:All>

<sp:AsymmetricBinding xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:InitiatorToken>
<wsp:Policy>
<sp:X509Token
sp:IncludeToken="http://schemas.xmlsoap.org/ws/2005/
07/securitypolicy/IncludeToken/Alwa
ysToRecipient">
<wsp:Policy>
<sp:RequireThumbprintReference/>
<sp:WssX509V3Token10/>

</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:InitiatorToken>
<sp:RecipientToken>
<wsp:Policy>
<sp:X509Token

sp:IncludeToken="http://schemas.xmlsoap.org/ws/
2005/07/securitypolicy/IncludeToken/Neve
r">
<wsp:Policy>
<sp:RequireThumbprintReference/>
<sp:WssX509V3Token10/>
</wsp:Policy>
</sp:X509Token>
</wsp:Policy>
</sp:RecipientToken>
<sp:AlgorithmSuite>
<wsp:Policy>

<sp:TripleDesRsa15/>
</wsp:Policy>
</sp:AlgorithmSuite>
<sp:Layout>
<wsp:Policy>
<sp:Strict/>
</wsp:Policy>
</sp:Layout>
<sp:IncludeTimestamp/>
<sp:OnlySignEntireHeadersAndBody/>
</wsp:Policy>
</sp:AsymmetricBinding>
<sp:Wss10 xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<wsp:Policy>
<sp:MustSupportRefKeyIdentifier/>
<sp:MustSupportRefIssuerSerial/>

</wsp:Policy>
</sp:Wss10>

<sp:SignedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body/>
</sp:SignedParts>
<sp:EncryptedParts xmlns:sp="http://schemas.xmlsoap.org/ws/2005/07/securitypolicy">
<sp:Body/>
INSA - 5 RT 2011
32



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
</sp:EncryptedParts>

<ramp:RampartConfig xmlns:ramp="http://ws.apache.org/rampart/policy">
<ramp:user>client</ramp:user>
<ramp:encryptionUser>service</ramp:encryptionUser>

<ramp:passwordCallbackClass>com.hugo.PWCBHandler</ramp:passwordCallbackClass>
<ramp:signatureCrypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.file">client.jks</ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">apache
</ramp:property>
</ramp:crypto>
</ramp:signatureCrypto>
<ramp:encryptionCypto>
<ramp:crypto provider="org.apache.ws.security.components.crypto.Merlin">

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.type">JKS</ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.file">client.jks</ramp:property>

<ramp:property name="org.apache.ws.security.crypto.merlin.keystore.password">apache
</ramp:property>
</ramp:crypto>
</ramp:encryptionCypto>
</ramp:RampartConfig>

</wsp:All>
</wsp:ExactlyOne>
</wsp:Policy>

Note the password handler class is once again given. Then you have two “
client.jks
” keys
provided. They just specify your own private key.

Step 6

From this, we will define the main classes of the client, which applies the policy and queries the
Calculator.

In your client project, add a handler class called PWCBHandler.java.

PWCBHandler.java

package com.hugo;

import org.apache.ws.security.WSPasswordCallback;

import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;

INSA - 5 RT 2011
33



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
import java.io.IOException;

public class PWCBHandler implements CallbackHandler {

public void handle(Callback[] callbacks) throws IOException,
UnsupportedCallbackException {
for (int i = 0; i < callbacks.length; i++) {


WSPasswordCallback pwcb = (WSPasswordCallback)callbacks[i];



//When the client requests for the password to be added in to the
//UT element
pwcb.setPassword("password");
}
}

}
The handler instantiates a password callback handle and sets the password to “password”.

Step 7

The final step in the client side configuration is to write the main class which queries the Web
service. In your client project, create a
Client.java
class. Put the following code into it:

Client.java
package com.hugo;

import java.io.InputStream;
import java.rmi.RemoteException;

import javax.xml.stream.XMLStreamException;
import javax.xml.ws.WebServiceClient;

import org.apache.axiom.om.impl.builder.StAXOMBuilder;
import org.apache.axis2.AxisFault;
import org.apache.axis2.client.Options;
import org.apache.axis2.client.ServiceClient;
import org.apache.axis2.context.ConfigurationContext;
import org.apache.axis2.context.ConfigurationContextFactory;
import org.apache.neethi.Policy;
import org.apache.neethi.PolicyEngine;
import org.apache.rampart.RampartMessageData;

import com.hugo.CalculatorStub.AdditionResponse;

public class Client {



/**
* Load policy file from classpath.
INSA - 5 RT 2011
34



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
*/
private static Policy loadPolicy(String xmlPath) throws Exception {
StAXOMBuilder builder = new StAXOMBuilder(xmlPath);
return PolicyEngine.getPolicy(builder.getDocumentElement());
}


/**
* @param args
* @throws RemoteException
* @throws XMLStreamException
*/
public static void main(String[] args) throws RemoteException, XMLStreamException {
// Rampart module should be in the repository

ConfigurationContext ctx =
ConfigurationContextFactory.createConfigurationContextFromFileSystem("/opt/axis2/repository/",
null);




CalculatorStub stub = new CalculatorStub(ctx,"http://server:8080/WSCalculator/services/
Calculator");




ServiceClient sc = stub._getServiceClient();


Options options = sc.getOptions();

options.setUserName("apache");
options.setPassword("apache");
try {

options.setProperty(RampartMessageData.KEY_RAMPART_POLICY,

loadPolicy("policy.xml"));
} catch (Exception e) {
// TODO Auto-generated catch block
e.printStackTrace();
}

sc.engageModule("rampart");



CalculatorStub.Addition request = new CalculatorStub.Addition();

request.setA(10);
request.setB(1);






CalculatorStub.AdditionResponse response = stub.addition(request);


System.out.println("addition result is "+response.get_return());


}

}

If you look at the
main
method, you’ll see a configuration context loading your repository (
/
opt/axis2/repository/
) where our services and modules are located. Then a stub (which
is like a mask, giving local access to the Web service) is instantiated, a service client is gotten
INSA - 5 RT 2011
35



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
from the stub and several options (username, password, policy, etc) are loaded into it. The
service client also allows the Rampart module activation.
Finally, the request object is created from the stub, and then you can add parameters (
a

and
b
) to the request. The response is also instantiated from the stub and returned by the

stub.addition
call.







INSA - 5 RT 2011
36



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Conclusions

In this cookbook, you have learned how to deploy and run a Web service using Apache Axis2
on a specific working platform. You can now realize how powerful and easy to use it is, thanks
to the efficient working environment you put in place. Indeed, after installing the required
elements, you can manage all the Web services you built in a few clicks, even without worrying
about the architecture details.
The security features scope is very flexible. We presented only two security policies, but you
might want to apply other types of security layers, which is possible just by peeking in rampart
samples folder. As an extension of this cookbook, a couple of more detailed recipes showing
how to add other types of security features could be elaborated, by following the WS-Security or
just using Rampart simple features.


























INSA - 5 RT 2011
37



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/

Recommended Documentation

1.
Apache Axis2 Installation Guide
:

htt
p
://
axis
.
apache
.
org
/
axis
2/
java
/
core
/
docs
/
installationguide
.
html

2.
Apache Axis2 Quick Start Guide
. This document describes the basic use of this powerful web
services framework and how to create a web service starting with business logic classes.

http
://
axis
.
apache
.
org
/
axis
2/
java
/
core
/
docs
/
quickstartguide
.
html

3.
Apache Axis2 Documentation
:

http
://
axis
.
apache
.
org
/
axis
2/
java
/
core
/
docs
/
userguide
.
html

4.
Apache Rampart Quick Start Guide.
This document describes the examples provided in the
Rampart samples folder. Each use case matches one on the key aspects of the WS-Security
specification:

http
://
axis
.
apache
.
org
/
axis
2/
java
/
rampart
/
quick
-
start
.
html

5.
IBM examples
of the implementation of Axis2 and Rampart on a DeveloperWorks installation:

http
://
www
.
ibm
.
com
/
developerworks
/
java
/
library
/
j
-
jws
4/
index
.
html


INSA - 5 RT 2011
38



Distributed Computing over the Internet
Axis2 Web Services and Security Cookbook
Implementing WS-Security with Apache Axis2, Rampart and
Tomcat
Hugo Gabignon
Thibaut Probst
bin/
Feedback

If you have any questions, comments or suggestions about this cookbook, please send us an
email at either:
hgabigno
@
etud
.
insa
-
toulouse
.
fr
or
probst
@
etud
.
insa
-
toulouse
.
fr





INSA - 5 RT 2011
39