Web Services Security with Apache Rampart – Part 1 ( Transport Level Security )
|
|
Post to twitterIntroduction
This tutorial is a step by step guide on how to use username token authentication with Apache Rampart using policy based configuration. We'll first look at a scenario. Then we'll look at deploying the Apache Rampart module in Axis2. We will then go on to look at how a Axis2 web service and a client can be secured with Rampart. With Axis2/Rampart proven to be highly interoperable, either the Web service or the client can be also written and secured using some Web service stack other than Axis2/Java, such as .NET , C or PHP. For example, Axis2 client with Rampart can be used to consume a secure .NET Web service.
Read Web Services Security with Apache Rampart – Part 2 (Message-Level Security)
Applies To
| Apache Axis2/Java | 1.3 |
| Apache Rampart/Java | 1.3 |
Table of Contents
- Scenario
- Deploying the Rampart Module
- Securing the Service
- Securing the Client
- SOAP Messages Exchanged
- Summary
- References
- Resources
Scenario
In this tutorial, we will look at a scenario, where message protection is provided by the transport layer. All message exchanges will be done over the https transport. Clients will authenticate to the service using username tokens (usename/password).
We will use the Axis2 WAR deployed in Apache Tomcat server for this tutorial, as it is one of the most common use cases.
Deploying the Rampart Module
Step 1. Deploying the Module and Necessary Jars
Apache Rampart 1.3 binary distribution can be downloaded here. Rampart distribution contains two module files, rampart-1.3 and rahas-1.3.mar . These module files should be copied to the "modules" directory of Axis2, that can be found in TOMCAT_HOME/webapps/axis2/WEB-INF/modules, where, TOMCAT_HOME is the home directory of the Apache Tomcat server in which Axis2 war is deployed. All the dependency jars needed for Apache Rampart can be found under the libs directory of the Rampart distribution. These has to be copied to the "lib" directory of Axis2, which can found under TOMCAT_HOME/webapps/axis2/WEB-INF/lib.
You can check whether Apache Rampart is successfully deployed by logging in to Axis2 as admin and using 'system components/available modules' option in admin Web console . Both "rampart" and "rahas" should be listed under available modules, if you have already successfully deployed Rampart and Rahas modules.
Step 2. Configuring SSL in Apache Tomcat
In this tutorial, we use https transport in Apache Tomcat to provide transport. So we have to modify the server.xml of Apache Tomcat, which can be found in TOMCAT_HOME/conf directory, to include SSL configuration. You can use the server.jks keytore which can be found in the source code zip file, as the keystore for this tutorial. Key store password is "password". SSL configuration in the server should look like the one given below:
<!-- Define a SSL HTTP/1.1 Connector on port 8443 -->
<Connector port="8443" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"
keystoreFile="path/to/server.jks"
keystorePass="password" />
Securing the Service
Step 1. Writing the Web Service and the Service Descriptor
For this tutorial, we will be using a simple service that has a single operation called "add", that adds two integers and returns the sum. For simplicity, we will be using the code first approach for this tutorial. Service implementation class is given below.
package tutorial.rampart.service;
/**
* Secure Service implementation class
*/
public class SecureService {
public int add(int a, int b) {
return a+b;
}
}
Service descriptor for the above mentioned service is given below. You can find more information on how to write an Axis2 Web service, in this tutorial: "Hello, World with Apache Axis2".
<service>
<parameter name="ServiceClass" locked="false">tutorial.rampart.service.SecureService </parameter>
<operation name="add">
<messageReceiver class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
</operation>
</service>
Step 2. Writing the Password Callback
As we use username token authentication in this scenario, we need to write a password callback class, to be used by the Web service to authenticate username tokens. The password callback class which we use for this tutorial, is given below. Even though passwords are hard coded in this example, passwords can be retrieved from a database, LDAP server or any storage, by writing the relevant password retrieval logic in the password callback class.
package tutorial.rampart.service;
import org.apache.ws.security.WSPasswordCallback;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
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++) {
//When the server side need to authenticate the user
WSPasswordCallback pwcb = (WSPasswordCallback)callbacks[i];
if(pwcb.getIdentifer().equals("apache") && pwcb.getPassword().equals("password")) {
//If authentication successful, simply return
return;
} else {
throw new UnsupportedCallbackException(callbacks[i], "check failed");
}
}
}
}
Step 3. Constructing the Security Policy
We will be using the policy based configuration approach in Apache Rampart for this tutorial. So we should construct a suitable security policy using WS-Security Policy Language, to define the requirements of the Web service. The security policy used in this tutorial is given below:
<wsp:Policy wsu:Id="UsernameTokenOverHTTPS" 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: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:Basic256/> </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>tutorial.rampart.service.PWCBHandler</ramp:passwordCallbackClass> </ramp:RampartConfig> </wsp:All> </wsp:ExactlyOne> </wsp:Policy>
As you can see, the above security policy contains two main security assertions, a transport binding assertion and a signed supporting token assertion. Transport binding assertion defines the requirement of using a SSL transport using the Https transport token assertion. Signed supporting token defines, the requirement of a username token that should be integrity protected at the transport level. You can find more information on constructing a security policy in this article: "Understanding WS-Security Policy Language" [3].
Last assertion, which is a Rampart specific assertion, is used to provide configuration details to Rampart. In the above policy, it defines a password callback class to be used. This assertion will not appear in WSDL.
Step 4. Engaging Rampart and Applying the Security Policy
Now, we will look at how we can engage Rampart to the Web service and apply the security policy. This is altogether done using the service descriptor. We don't have to modify the source of the Web service to secure it. First, we engage the Rampart module to the Web service adding <module ref="rampart"/> element to the service descriptor. Then we apply security, by adding the policy to the service descriptor. Modified service descriptor after engaging rampart and applying policy, is given below. Elements with the policy element is not shown for brevity.
<service>
<module ref="rampart"/>
<parameter name="ServiceClass" locked="false">tutorial.rampart.service.SecureService</parameter>
<operation name="add">
<messageReceiver class="org.apache.axis2.rpc.receivers.RPCMessageReceiver"/>
</operation>
<wsp:Policy wsu:Id="UsernameTokenOverHTTPS" 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:Policy>
</service>
Step 5. Deploy the Service
Now, we have to deploy this service in the Axis2 server. Create a service archive named SecureService.aar and drop it into the services directory which can found at: TOMCAT_HOME/webapps/axis2/WEB-INF/services, where, the TOMCAT_HOME is the home of Apache Tomcat server. You can find information on how to create an Axis2 service archive in the "Hello, World with Axis2" tutorial [2] listed under references.
Policy Annotated WSDL
When a security policy is applied to Web service, the WSDL will be annotated with the relevant security policy so the clients can secure SOAP messages according to the policy defined in the WSDL. Code generators that generates stubs to access the Web service can make use of these security policies defined in the WSDL. The policy annotated WSDL of the Web service we use for this tutorial can be found here.
Securing the Client
Step 1. Generating the Stub using WSDL2Java Tool
Java2WSDL tool provided by Axis2 can be used to generate stubs that can be used to call Web services. Given below is the command which we use in this tutorial to generate the stub. -uri option is used to provide the URL of the WSDL, -p option is used to specify a custom package name for the code generated, -o option to specify a directory path for the code generated and -uw option to switch on un-wrapping.
[Linux] $ sh WSDL2Java.sh -uri http://localhost:8080/axis2/services/SecureService?wsdl -p tutorial.rampart.client -uw -o /project/path/ [Windows] WSDL2Java.bat -uri http://localhost:8080/axis2/services/SecureService?wsdl -p tutorial.rampart.client -uw -o /project/to/path/
Step 2. Writting the Client
Now, we will write a client to the Web service using the stub generated. Source code of the client is given below:
package tutorial.rampart.client;
public class SecureServiceCGClient {
public static void main(String[] args) throws Exception {
SecureServiceStub stub = new SecureServiceStub(null,"https://localhost:8443/axis2/services/SecureService");
int a = 3;
int b = 4;
int result = stub.add(a, b);
System.out.println(a + " + " + b + " = " + result);
}
}
Step 3. Engaging Rampart and Setting Authentication Information
To secure SOAP request made by the client, we need to engage the Rampart module to the client. So we have to create a client repository and the rampart-1.3.mar should be deployed in the modules directory. We should make sure that all dependency .jar files of the Apache Rampart module are in the classpath of the client. Then we can use the following code to engage Rampart in the client. Note that username and password to be used in the Username token, is provided using the Options class.
As you can see, we don't have to apply the policy to the client manually. WSDL2Java tool does that for us. It extracts the relevant policy from the WSDL and apply it correctly to the generatd stub.
// Rampart module should be in the repository
ConfigurationContext ctx = ConfigurationContextFactory.createConfigurationContextFromFileSystem("path/to/client/repo", null);
SecureServiceStub stub = new SecureServiceStub(ctx,"https://localhost:8443/axis2/services/SecureService");
ServiceClient sc = stub._getServiceClient();
sc.engageModule("rampart");
Options options = sc.getOptions();
options.setUserName("apache");
options.setPassword("password");
Step 4. Adding Server Certificate as a Trusted Certificate
As we are using HTTPS as the transport protocoal , SSL handshake has to happen and the client need to trust the server's certificate. We have to add the key store containg the server's certificate as a trust store and it can be done by seting the following system properties:
System.setProperty("javax.net.ssl.trustStore", "/path/to/server.jks");
System.setProperty("javax.net.ssl.trustStorePassword", "password");//the storepass for the jks
NOTE: We only have to do this since we are using a self signed certificate. In a situation where the SSL channel is secured using a certificate signed by a known CA (Ceritificate Authority) we don't have to set these JSSE (Java Secure Socket Extension) properties.
Step 5. Calling the Web Service
Now, everything is well set and you can run the client and consume the Web service.
SOAP Messages Exchanged
We will take a look at the SOAP messages exchanged between the client and the service.
Without Security
This is SOAP message sent by the client without security;
<soapenv:Envelope> <soapenv:Body> <ns1:add xmlns:ns1="http://service.rampart.tutorial"> <ns1:a>4</ns1:a> <ns1:b>6</ns1:b> </ns1:add> </soapenv:Body> </soapenv:Envelope>
With Security
This is the SOAP message sent by the client when Rampart is engaged and the above security policy applied. As you can see, SOAP header with a security header, is added to the SOAP message. Security header is used to send all security claims required by the security policy of the server.
<soapenv:Envelope> <soapenv:Header> <wsse:Security soapenv:mustUnderstand="1"> <wsu:Timestamp wsu:Id="Timestamp-31497899"> <wsu:Created>2008-02-06T13:39:50.943Z</wsu:Created> <wsu:Expires>2008-02-06T13:44:50.943Z</wsu:Expires> </wsu:Timestamp> <wsse:UsernameToken wsu:Id="UsernameToken-10697954"> <wsse:Username>apache</wsse:Username> <wsse:Password Type="http://...#PasswordText">password</wsse:Password> </wsse:UsernameToken> </wsse:Security> </soapenv:Header> <soapenv:Body> <ns1:add xmlns:ns1="http://service.rampart.tutorial"> <ns1:a>4</ns1:a> <ns1:b>6</ns1:b> </ns1:add> </soapenv:Body> </soapenv:Envelope>
Summary
In this tutorial, we looked at how to deploy Apache Rampart module and apply security to a Web service. We aslo looked at how to consume a secure Web service.
In part II of this tutorial "Web services security with Apache Rampart - Part II ( Message level security), we will look at how to secure Web services with Apache Rampart using message level security. We will look at how to sign and encrypt various message parts, using Apache Rampart.
References
- Apache Tomcat SSL configuration
- Hello World with Apache Axis2
- Understanding the WS Security Policy Language
- Web Services Security with Apache Rampart – Part 2 (Message-Level Security)
557
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
