Introduction

e-business relies on the exchange of information between business partners over a network. In such a setup, as the information/data travels from the source to the destination, there is always the risk of the data being stolen or modified. The same security risks are applicable to web services transactions. In web services transactions using SOAP, the data are passed between the service invoker and service provider as plain XML, so anyone who intercepts the messages can read the data that are exchanged. In the web services scenario the security aspect is more complicated because:

• Soap messages can be sent using different transport applications or protocols like HTTP, SMTP, etc., which might have a very high security model to no security model at all. Hence, there is a need for a comprehensive security framework for web services applications, which is common to all types of transport protocols.
• There could be legitimate intermediaries that might need to access a part or whole of the SOAP message, and even modify the message. Thus the security model must be comprehensive enough to allow such intermediaries.

This article will introduce the various aspects of web services security and will provide step-by-step guidelines on how to write and deploy secure web services applications with existing technologies.

Back to top

Web services security guidelines

The W3C Web Services Architecture Requirements outlines the following six important security considerations for a comprehensive security framework:

1. Authentication: guarantees that the service is accessible for anyone with a verified identity.
2. Authorization: guarantees that the authenticated person has the right to access the service or data.
3. Confidentiality: guarantees that the data passed between the requester and provider is protected from eavesdroppers.
4. Integrity: offers that the message was not modified in its path from requestor to provider.
5. Non-repudiation: guarantees that the sender of the message cannot deny that he/she sent it at a later point in time.
6. Accessibility: ensures that the service is always accessible and that it is not impaired by attacks, like denial-of-service (DoS), from outside or inside of the system hosting the service.

OASIS is another important standards organization that is developing a formal model/specification for providing more robust and scalable web services security.

Back to top

Web services today

Web services security is still in its infancy. New standards and applications are being continually developed and deployed. Web services security as of today can be achieved at two levels:

1. Security at the transport level
   Security at the transport level uses the inbuilt security features of transport technologies like HTTP, IBM WebSphere MQSeries, etc. This article describes how the inbuilt security features of HTTP can be used to secure web services transactions.
2. Security at the SOAP or messaging level
   This level is currently being extensively researched and specifications are being developed by groups like OASIS. This involves usage of digital signatures, certificates, etc., at the XML document level. This will be discussed in more detail in the second part of this series.

Back to top

Securing web services with HTTP

Web services transactions over HTTP can be secured by using the following:

• HTTP basic authorization
• HTTPS (HTTP Secure) or HTTP with secure socket layer (SSL)
• HTTP basic authorization + HTTPS

However, HTTP security does not address all of the web services security guidelines, listed earlier. The best possible configuration is to use HTTPS with HTTP basic authorization, which addresses all aspects of web services security except non-repudiation and accessibility. The remainder of this article shows how to configure and develop web services using these approaches. The machine and software configuration we have chosen for demonstrating the examples below are as follows:

Soap client/server: Apache Axis v1.0 Beta 3 (Note: Release version has a bug relating to the use of SSL)
Web server: Apache Jakarta Tomcat v4.0.2
JDK: Sun J2SE v1.4.1
Platform: Microsoft Windows 2000 Professional, Service Pack 3

Back to top

HTTP basic authorization

HTTP basic authorization (BASIC-AUTH) is a simple mechanism used in HTTP. Using this mechanism we can protect web resources from unauthorized access. To access resources protected using HTTP BASIC-AUTH, a user has to provide a username and password. The web site administrator configures the web server with a list of valid users and resources that a user can access. Since web services invocation over HTTP is the same as accessing a URL (endpoint URL) we can make use of BASIC-AUTH to restrict web services access.

In this section, we will show how to setup BASIC-AUTH for a web service deployed in Apache Axis running on the Apache Jakarta Tomcat Web Server.

Step 1: Writing and deploying a Web Service
We shall begin by writing a simple 'Echo Service'. The Echo Service is a simple Java class as shown in Listing 1.

		
public class EchoService {
   public String echoString( String echoStr ) {
      return echoStr;
   }
}

Save the above file as 'EchoService.java'. To deploy the program as a service, just copy it into '%TOMCAT_HOME%\webapps\axis' and rename it as 'EchoService.jws'. That is all there is to it, and you have deployed your first web service. Now your simple web service can be accessed from the URL http://localhost:8080/axis/EchoService.jws?wsdl.

But the service is not yet secure. In order to secure it, create a directory named 'protected' (or any name of your choice) inside '%TOMCAT_HOME%\webapps\axis' and move 'EchoService.jws' into this directory. Now the web service URL becomes http://localhost:8080/axis/protected/EchoService.jws?wsdl.

Step 2: Define user credentials
To add new user credentials, edit 'tomcat-users.xml' in '%TOMCAT_HOME%\conf' and add a new user as shown in Listing 2.

		
<tomcat-users>
  <user name="tomcat" password="tomcat" roles="tomcat,manager" />
  <user name="role1"  password="tomcat" roles="role1"  />
  <user name="both"   password="tomcat" roles="tomcat,role1" />
  <!-- Define new user name and password with the role -->

		  <user name="wsuser" password="wspwd" roles="wsuser" />
</tomcat-users>

This step simply defines a new user and the role the user plays. In the next step we will show you how to associate a security constraint to a particular user role.

Step 3: Add a security constraint to the web service URL
In order to add a security constraint, edit 'web.xml' in '%TOMCAT_HOME%\webapps\axis\WEB-INF' and insert the lines shown in Listing 3 immediately before the end of the element <web-app>.

		
<Security-constraint>
   <web-resource-collection>
      <web-resource-name>Protected</web-resource-name>
      <!-- specify the directory for restricted web Services application -->
      <url-pattern>/protected/*</url-pattern>
   </web-resource-collection>
   <auth-constraint>
      <!-- specify the role name of the new user added in step 2 -->
      <role-name>wsuser</role-name>
   </web-resource-collection>
   <auth-constraint>
</security-constraint>

<!-- Define the Login Configuration for this Application -->
<login-config>
   <auth-method>BASIC</auth-method>
   <realm-name>Protected Web Services</realm-name>
</login-config>

Restart the Tomcat server so that the settings take effect. Try accessing the WSDL by going to the URL http://localhost:8080/axis/protected/EchoService.jws?wsdl. The browser will request you to authenticate yourself by entering your username and password.

Step 4: Writing a Java client program to access the web service
Listing 4 shows a sample Java client program taken from the Apache Axis User Documentation. We do the following modifications to enable automated client authentication:

• Change the endpoint/web service address.
• Set the username and password.

		
import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import javax.xml.namespace.QName;
  
public class TestClient {
 public static void main(String [] args) {
  try {
    String endpoint = "http://localhost:8080/axis/protected/EchoService.jws";
    Service service = new Service();
    Call    call    = (Call) service.createCall();
    call.setTargetEndpointAddress( new java.net.URL(endpoint) );
    call.setOperationName(new QName("echoString"));
  	    
    call.setUsername("wsuser");
    call.setPassword("wspwd");

    String ret = (String) call.invoke( new Object[] { "Hello!" } );
    System.out.println("Sent 'Hello!', got '" + ret + "'");
  } catch (Exception e) {
    System.err.println(e.toString());
  }
 }
}

Examination of the SOAP message using TCPMon reveals a new HTTP 'Authorization' header added to the HTTP message as shown in Listing 5. The string after Basic is the BASE64 encoded username and password.

		
POST /axis/protected/EchoService.jws HTTP/1.0
Host: localhost
Content-Type: text/xml; charset=utf-8
SOAPAction: ""
Content-Length: 1663
Authorization: Basic c2lsdmVyOnNpbHZlcg==

<SOAP-ENV:Envelop>
...
...
</SOAP-ENV:Envelop>

But in the method shown above, the message/data exchanged by SOAP have not been secured. Only the username and password have been encoded. The actual SOAP message is not encrypted and is displayed in plain XML. Anyone who captures the HTTP message, as we have, can read the data/message that is being exchanged, alter it and resend it again. HTTP basic authorization addresses only the authentication and authorization aspects of web services security described above. So we need a more sophisticated mechanism, which addresses other aspects of web services security.

Back to top

HTTP secure (HTTPS)

Secure socket layer (SSL), is a technology which allows web browsers and web servers to communicate over a secured connection. This means that the data being sent are encrypted by one side, transmitted, and decrypted by the other side before processing. This is a two-way process, meaning that both the server and the browser encrypt all traffic before sending out data.

The following sections show how to developing a secure web services application using Axis and HTTPS.

Step 1: Configuring a web server for SSL
Here we show how to configure Apache Jakarta Tomcat to use SSL. Before you start, ensure you have Java JDK v1.4.0 or above. If not, you need to have Java Secure Socket Extension (JSSE) downloaded and installed on your system.

First, create the SSL certificate which will be used for authenticating and encrypting data. This can be created using the 'keytool' utility provided with J2SE 1.4+. The tool can be found in the '%JAVA_HOME%\bin' directory. Execute the following from the terminal command line:

This command will create a new file, in the home directory of the user under which you run it, named '.keystore'. In Windows 2000, if the user is an Administrator, the file can be found in 'C:\Documents and Settings\Administrator'. After executing this command, you will first be prompted for the keystore password. The default password used by Tomcat is 'changeit' (all lower case), although you can specify a custom password if you like. However for the purpose of this demo we will use the default password.

Second, edit the 'server.xml' file located in the '%TOMCAT_HOME%\conf' directory. Look for a commented connector element defined in XML (Listing 6).

		
<!-- Define an SSL HTTP/1.1 Connector on port 8443 -->
<!--
<Connector className="org.apache.catalina.connector.http.HttpConnector"
           port="8443" minProcessors="5" maxProcessors="75"
           enableLookups="true"
           acceptCount="10" debug="0" scheme="https" secure="true">
  <Factory className="org.apache.catalina.net.SSLServerSocketFactory"
             clientAuth="false" protocol="TLS"/>
</Connector>
-->

Remove the comment tags around the Connector element. After completing the above configuration, restart the Apache Tomcat web server. You should now be able to access web applications supported by Apache Tomcat via SSL. For example try, https://localhost:8443 and you should see the usual Tomcat splash page (unless you have modified the ROOT web application). For more detailed information on configuring the web server for SSL, see your web server documentation.

Step 2: Writing and deploying a web service
We use the same 'Echo Service' example used earlier. Copy 'EchoService.jws' into '%TOMCAT_HOME%\webapps\axis'. Access the WSDL URL for the service, but specify the transport protocol as https instead of http and port as 8443 instead of 8080 (port 8443 is the default port for HTTPS in the Apache Jakarta web server). Therefore, the WSDL URL for the 'Echo Service' will be https://localhost:8443/axis/EchoService.jws?wsdl.

Step 3: Creating the SSL certificate for a client
If you are running the server and client on the same machine, then you can use the same certificate that you created for the server in Step 1. However, if the client and the server are running on different machines, then create a new certificate for the client using the 'keytool' utility as explained above in Step 1.

Step 4: Writing a Java client program to access the web Service
Listing 7 shows a sample Java client program taken from the Apache Axis User Documentation. We do the following modifications to enable automated client authentication:

• Change the endpoint or SOAP web service address to reflect the HTTPS protocol and port.
• Set the path and filename of the client SSL certificate.

		
import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import javax.xml.namespace.QName;
  
public class TestClient {
 public static void main(String [] args) {
  try {
    String endpoint = "https://localhost:8443/axis/EchoService.jws";
    System.setProperty("javax.net.ssl.trustStore", 
    "C:\\Documents and Settings\\Administrator\\.keystore");
    Service service = new Service();
    Call    call    = (Call) service.createCall();
    call.setTargetEndpointAddress( new java.net.URL(endpoint) );
    call.setOperationName(new QName("echoString"));

    String ret = (String) call.invoke( new Object[] { "Hello!" } );
    System.out.println("Sent 'Hello!', got '" + ret + "'");
  } catch (Exception e) {
    System.err.println(e.toString());
  }
 }
}

Step 5: Run the client
Compile and run the program and you should be able to see your string echoed back from the server. The difference this time is that the data have been sent encrypted and received encrypted.

Back to top

HTTP basic authorization + HTTP secure

HTTPS provides excellent security to web services transactions. HTTPS also provides an authorization mechanism for a user by means of signed certificates. However, if a duplicate of the certificate is available, anyone can impersonate the participating agent. So the best form of security can be derived by a hybrid of HTTP BASIC-AUTH and HTTPS. This also satisfies the first four aspects of WS-Security listed earlier as well as providing a better degree of protection from Repudiation. The following steps will explain how to configure your web services application to take advantage of it.

Step 1: Configure web server for HTTPS
Follow Step 1 from the section "HTTP secure" to configure the web server for HTTPS. If you have already configured the server, then it need not be configured again.

Step 2: Write and deploy the web service with BASIC-AUTH
In this section, we will also take the simple 'Echo Service' to demonstrate HTTPS + HTTP BASIC-AUTH. Follow Steps 1 to 3 to write and deploy the web service application from the section "HTTP basic authorization." The WSDL address for the Echo Service is now available at the URL https://localhost:8443/axis/protected/EchoService.jws?wsdl.

Step 3: Creating the SSL certificate for client
Follow Step 3 from the section "HTTP secure" to create an SSL certificate for the client.

Step 4: Writing a Java client program to access the web service
Listing 8 shows a sample Java client program taken from the Apache Axis User Documentation. We do the following modifications to enable automated client authentication:

• Change the endpoint or SOAP web service address to reflect the HTTPS protocol and port.
• Set the path and filename of the client SSL certificate.
• Set the username and password.

		
import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import javax.xml.namespace.QName;
  
public class TestClient {
 public static void main(String [] args) {
  try {
    String endpoint = "https://localhost:8443/axis/EchoService.jws";
    System.setProperty("javax.net.ssl.trustStore", 
    "C:\\Documents and Settings\\Administrator\\.keystore");
    Service service = new Service();
    Call    call    = (Call) service.createCall();
    call.setTargetEndpointAddress( new java.net.URL(endpoint) );
    call.setOperationName(new QName("echoString"));
  	    
    call.setUsername("wsuser");
    call.setPassword("wspwd");

    String ret = (String) call.invoke( new Object[] { "Hello!" } );
    System.out.println("Sent 'Hello!', got '" + ret + "'");
  } catch (Exception e) {
    System.err.println(e.toString());
  }
 }
}

Step 5: Run the client
Compile and run the program and you should be able to see your string echoed back from the server. The difference this time is that the web service data have been authenticated as well as encrypted.

Back to top

Summary

The security methods discussed provide simple, but effective, solutions to secure your web services transactions over HTTP. However, a word of caution. As the complexity of web services transactions increases, these methods may become unsuitable. Consider, for example, that the methods discussed above would be unsuitable if the same SOAP messages were exchanged using SMTP (Simple Mail Transfer Protocol). Similarly, the solutions presented above might not be applicable if there were legitimate intermediaries present. In order to address these issues, a comprehensive WS-Security specification is being developed and standardized. The second article in this series will introduce the WS-Security specification and provide a detailed account of how it can be used to take the security of your web services applications to the next level.

Resources

• Check out the Jakarta Tomcat Documentation.
  
  
• Read the Apache Axis Users Guide.
  
  
• Find out more information about SSL.
  
  
• Find more web services architecture requirements.
  
  
• Download the IBM Web Services Toolkit (WSTK) from alphaWorks.
  
  

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Web services security guidelines
• Web services today
• Securing web services with HTTP
• HTTP basic authorization
• HTTP secure (HTTPS)
• HTTP basic authorization + HTTP secure
• Summary
• Resources
• About the authors
• Comments