Web services are virtual software components that can be accessed and invoked through a variety of protocols and formats. The environment for these components is heterogeneous and distributed. As a result, a secure communication infrastructure is required to ensure the security of the messages (and the content) among these components.
Web Services Security (WS-Security or WSS) is flexible and designed to be used as the basis for the construction of a wide variety of security models, including public key infrastructure (PKI), Kerberos, and Secure Sockets Layer (SSL). Specifically, WS-Security provides support for multiple security tokens, multiple trust domains, multiple signature formats, and multiple encryption technologies.
This specification provides three main mechanisms:
- security token propagation
- message integrity
- message confidentiality.
These mechanisms by themselves do not provide a complete security solution. Instead, WS-Security is a building block that can be used in conjunction with other Web service extensions and higher-level application-specific protocols to accommodate a wide variety of security models and encryption technologies. These mechanisms can be used independently (for example, to pass a security token) or in a tightly integrated manner (for example, to sign and encrypt a message and to provide a security token hierarchy associated with the keys used for signing and encryption).
This article assumes a basic knowledge of Web services, J2EE technologies and WebSphere® Application Server V5.0.2. After reading this article, you will have an understanding of how to use WS-Security in your existing infrastructure and appreciate the declarative programming model that WebSphere Application Server V5.0.2 provides for securing your applications' communication infrastructure.
WS-Security in WebSphere Application Server V5.0.2
WebSphere Application Server V5.0.2 uses a declarative model for using WS-Security. It can be created and modified using WebSphere Studio Application Developer Version 5.1, the Application Server Toolkit (ASTK) available in WebSphere Application Server V5.0.2, or the WebSphere administrative console. For the purpose of providing a deeper understanding of the technology, we will describe the manual procedure here.
The security tokens that can be propagated are Username token, X.509-based certificates, and Lightweight Third Party Authentication (LTPA); there is also an API provided for plugging in user-defined tokens. Message integrity is provided by digital signatures based on PKI (currently, there is no support for symmetric key signatures) and XML Encryption provides confidentiality.
The WebSphere security handlers read the declared deployment extensions to obtain the configuration and enforce the WS-Security infrastructure, as shown in Figure 1. These are implemented as WebSphere runtime-based JAX-RPC handlers, and are transparent to the application developer.
Figure 1. WS-Security in WebSphere Application Server V5.0.2
The sample account service
WebSphere Application Server V5.0.2 offers an elegant and powerful way to enable WS-Security to provide MLS for your application's communication link. It enables you to take any existing service's Web Services Description Language (WSDL) and provide the necessary WS-Security extensions and bindings to secure the messages between your Web service client and server.
This article assumes there is an existing Web service that needs to be enabled for WS-Security. The example service used here is an AccountService, provided by a fictitious bank, SomeBank.
The AccountService is a simple Web service; for demonstration purposes, the service does no real business processing. It contains a simple operation accountEnquiry, which takes an AccountRequest message and returns an AccountResponse message. The AccountRequest message contains AccountID and AccountType information. The AccountResponse contains the balance for the account information passed. The accountEnquiry operation does not do any processing based on the request message, but instead returns a fixed balance value of 12345.0. However, these messages are important because we will monitor them going over the wire using tcpmon (a utility to visually snoop messages) -- looking at the unsecured wire message formats and then later with the various WS-Security configurations.
For ease of demonstration, the accountEnquiry operation has been exposed as four separate ports within the service; the ports will be used when WS-Security in configured. For the unsecured service, however, all the ports are similar. The individual ports are discussed when configuring WS-Security for the AccountService.
First, install the unsecured AccountService and its client.
Install and run the unsecured service
To install and test the unsecured AccountService:
- Download and extract the
WSS-Sample.zipfile into a temporary directory.
- Using the WebSphere administrative console, install the enterprise application AccountService (the
SomeBankService.earfile). This is available under the
code/servicedirectory. Make sure you choose the default options and save the configuration after the install.
- Start the enterprise application using the console.
- Launch a browser and test whether the service is available by accessing
http://localhost:9080/SomeBankService/services/SomeBankPort. If you get the message "And now ... Some Services", you have successfully configured the SomeBank AccountService.
- You can also check the AccountService WSDL by accessing
http://localhost:9080/SomeBankService/services/SomeBankPort?WSDL. The WSDL should be similar to the WSDL shown in the Appendix.
Instal and run the unsecured client
To install the client for the AccountService:
- Using the WebSphere administrative console, install the Web application (the
SomeBankClient.warfile). This is available under the
code/clientdirectory. While installing the WAR file, make sure you enter the Context Root for the Web module. Select the defaults and save the configuration after the install.
- Start the Web application using the console.
- Launch a browser and test whether the client is installed correctly by accessing it at
- You should see screen shown in Figure 2.
Figure 2. The AccountService client
- The default selections of the client are available and can be used to test the AccountService just installed. Click Submit and you will see the results page shown in Figure 3.
Figure 3. The client results page
Now that the service and client have been successfully installed, review the client input options:
- Account ID and Account Type: These are dummy inputs because the service response is fixed. However, they are important because you can see them when you monitor the messages using
- Message Encryption: Turns on XML Encryption of the messages on the wire after WS-Security is configured, providing confidentiality of the messages.
- Message Signing: Turns on XML Digital Signature of the messages on the wire after WS-Security is configured, providing message integrity.
- Service Port: Points to the HTTP-based port on which the service is available. You can use this option to point to a
tcpmonproxy port (discussed next) for observing the Web service request and response messages.
- Transport Protocol: To choose whether to use SSL or not. When HTTPS is selected, the client is hardwired to use the WebSphere internal SSL port, 9443. Obviously, when this is selected
tcpmonis not able to observe the messages over the wire.
Therefore, for configuring the security options using both MLS and TLS, there are eight combinations, made up of:
- XML Encryption [on/off]
- Digital Signing [on/off]
- SSL [on/off].
This makes the client versatile enough to watch the mechanisms of WS-Security.
Using tcpmon to observe the messages
tcpmon is a utility shipped with WebSphere Application Server V5.0.2. Using a proxy port,
tcpmon can be used to view and inspect SOAP messages (request and response).
tcpmon for monitoring the messages in the unsecured scenario:
- Check if there is a
<WAS_HOME>/bindirectory. If there is one, proceed to Step 3.
- Create a
tcpmon.batfile by copying and pasting Listing 1 into a file.
Listing 1. Source for tcpmon.bat
@REM Copyright IBM Corp. 2002 , 2003 @setlocal @echo off SET CONSOLE_ENCODING=-Dws.output.encoding=console call "%~dp0setupCmdLine.bat" "%JAVA_HOME%\bin\java" %CONSOLE_ENCODING% "- Dws.ext.dirs=%WAS_EXT_DIRS%;%WAS_USER_DIRS%" -classpath "%WAS_HOME%"\lib\webservices.jar;"%WAS_CLASSPATH%";"%CLASSPATH%" com.ibm.ws.bootstrap.WSLauncher com.ibm.ws.webservices.engine.utils.tcpmon @endlocal
- Run the
tcpmon.batprogram and you will see the screen shown in Figure 4.
Figure 4. Tcpmon Admin window
- Enter an available port (for example,
9999) for the Listen Port #.
localhostfor Target Hostname.
9080(WebSphere internal HTTP port) for the Target Port #.
- Click Add to display a panel that listens to port 9999 and forwards the request to localhost:9080.
- Now, switch to the browser that has the AccountService client and enter port
9999for Service Port. Click Submit.
- The Account Service client behaves as before. In the
tcpmonpanel, notice the request (the upper panel) and response (the lower panel) messages as shown in Figure 5.
Figure 5. Tcpmon showing intercepted messages
Look at the messages carefully, especially the SOAP header and body. Identify the SOAP body of the request, which contains the request parameters
accountType. Similarly, inspect the SOAP body of the response.
Because WS-Security is not configured, selecting the Message Signing and Message Encryption options on the client will create the same messages over the wire.
Now that you are comfortable running the service and the client, and using
tcpmon to intercept and inspect the SOAP messages flowing over the wire, you can apply WS-Security to AccountService.
Before applying WS-Security to the AccountService, review the AccountService WSDL and IBM declarative Web services extensions for WebSphere.
Looking closer at the WSDL
Listing 2 shows the WSDL section that is key to enabling WS-Security. Four different ports are used for the service to demonstrate all combinations of MLS, namely:
- Only Digital Signature (using WSS XML Signatures for message integrity).
- Only XML Encryption (using WSS XML Encryption for message confidentiality).
- Both Digital Signature and XML Encryption (for integrity and confidentiality).
- No message-level security.
In practice, you would not need to define all the different security configurations for one single operation. However, to demonstrate all combinations supported by WS-Security, this example introduces multiple service endpoints for one single operation.
Listing 2. SomeBank service section from AccountService WSDL
The important attributes to note in the WSDL Service section are those highlighted in bold. References to these will be used in the WS-Security declarations in the IBM extensions and bindings for WebSphere Application Server V5.0.2.
Looking at the WebSphere Web Services Security extensions
Before applying WS-Security, it will be useful to tour the key Web services deployment descriptor files. Figure 6 shows a topological view of the various descriptors.
Figure 6. JSR101 and JSR109 artifacts in WebSphere
The Enterprise Web services for J2EE specification (JSR109) introduces a Web services deployment descriptor called
webservices.xml. This file defines the set of Web services that are to be deployed in a Web services for J2EE-enabled container. This file is generated by the WSDL2Java tool when specifying the server role. It is packaged in the same directory as the module deployment descriptor, that is,
META-INF for EJB modules and
WEB-INF for WAR modules.
Similarly, for the client side, JSR109 introduces the
webservicesclient.xml file. The
webservices.xml deployment descriptor contains service reference entries. These entries declare references to Web services used by a J2EE component in the Web, EJB, or application client container. The
webservicesclient.xml file is also packaged in the same directory as the deployment descriptor for the module.
In addition to these standard deployment descriptors, IBM provides extensions to both the service and the client as shown in Figure 7. For the service, IBM provides the
ibm-webservices-ext.xmi file (which defines the extensions used by the service) and the
ibm-webservices-bnd.xmi file (which defines the bindings for the extensions to work). Similarly for the client, IBM provides the
ibm-webservicesclient-ext.xmi and the
Figure 7. IBM Web services extensions for WebSphere Application Server V5.0.2
For the purposes of enabling WSS, this article is only concerned with the IBM extension files. IBM provides for WS-Security through extensions for J2EE because deployment descriptors have not yet been standardized. To avoid the need to generate X.509-based certificates and keystores, this article re-uses the sample keystore files that are part of the WebSphere Application Server V5.0.2 install. The sample keystores are based on the JCE (Java Cryptography Extension) keystore (JCEKS) and the traditional keystore in the standard JDK (JKS). The JCEKS-based keystore is used for XML Encryption. The JKS-based keystore is used for XML Digital Signatures. These keystores are located under the directory
Securing the service
Depending on the kind of container (EJB or Web) chosen for the service, the descriptor files generated are placed under the relevant module directory (
WEB-INF respectively). The SomeBank AccountService uses the Java bean-based implementation, which runs in the WebSphere Web container.
First, apply the WS-Security extensions. Use the following steps to WSS-enable and apply the desired security characteristics for each port of the AccountService:
- Back up the files under the
- Move to the unzipped sample directory
- Copy the
ibm-webservices-bnd.xmifiles to the
code/service/BankWAR/WEB-INFdirectory. Click Yes to overwrite it.
- Move to the
code/service/BankWARdirectory and issue the following command:
%WAS_HOME%/java/bin/jar cvf ..\SomeBankService.war WEB-INF META-INF
- Move to the
code/servicedirectory and issue the following command:
%WAS_HOME%/java/bin/jar cvf SomeBankService.ear SomeBankService.war META-INF
- Run the endpoint enabler on the resultant EAR file.
- Open the WebSphere administration console, and stop and uninstall the unsecured AccountService. Save the master configuration after applying the changes.
- Re-start the WebSphere Application Server.
- Now, install the WSS-enabled AccountService following the steps provided for the unsecured AccountService.
- Run the same tests and also check the WSDL response, as before.
Next, examine the WS-Security IBM extension files just copied. It is important to note that no code modifications were needed to WSS-enable the AccountService. It is a pure declarative and elegant mechanism provided by WebSphere.
ibm-webservices-ext.xmi file contains only the empty elements for each of the service endpoints defined in the WSDL service section. For each service endpoint, depending on the desired message level security, you apply the corresponding WSS declaration.
Now, examine the WSS-enabled
ibm-webservices-ext.xmi file (available under
code/snippets/service ). Because the service will use "symmetric" security, each port has a requestor sub-element (
<securityRequestReceiverConfig>) and a response sub-element (
For the signed port, SomeBankPortSigned, the service endpoint expects to only apply message integrity (the
<requiredIntegrity> element) to the body part of the SOAP message.
For the encrypted port, SomeBankPortEncrypted, the service endpoint expects to only apply encryption to provide message confidentiality (the
<requiredConfidentiality> element). By specifying
bodycontent , only the body of the SOAP message is encrypted.
The SomeBankPortSignedAndEncrypted uses both of the signed and encrypted elements mentioned above to provide message integrity and confidentiality.
You must provide a binding for these declared security artifacts. The second file
ibm-webservices-bnd.xmi contains the bindings. The bindings are built using the sample keystores and certificate chains that are part of the WebSphere Application Server V5.0.2 installation. Depending on the port characteristic, X.509-based certificates are used to sign and encrypt the messages.
To extrapolate this and apply it to your own custom Web service, you just need to modify the IBM extension files and copy the corresponding stanza, depending on the security characteristic you desire. Make sure that you copy the correct and consistent stanza (they are conveniently partitioned and commented in the samples) and apply it for both the
Securing the client
Before securing the client, use the following exercise to test the expected case where a WSS-enabled service will not respond to an unsecured client. Select the Message Signing or the Message Encryption options on the client and click Submit (remember that WS-Security is configured for a combination of these two options). The client will not get a response and the log files display the corresponding security error.
Perform the following steps to WSS-enable the client:
- Back up the files under the
- Move to the unzipped sample directory
- Copy the
ibm-webservicesclient-bnd.xmifiles to the
code/client/WEB-INFdirectory. Click Yes to overwrite it.
- Move to the
code/clientdirectory and issue the following command:
%WAS_HOME%/java/bin/jar cvf SomeBankClient.war WEB-INF META-INF *.jsp *.GIF
- Open the WebSphere administration console, and stop and uninstall the unsecured client. Save the master configuration after applying the changes.
- Re-start the WebSphere Application Server.
- Now, install the WSS-enabled client following the steps performed earlier for the unsecured client.
- Test the client as you did previously, choosing the Message Encryption and Signing radio buttons to test the WSS functionality.
ibm-webservicesclient-bnd.xmi files contain entries similar to the corresponding entries for each port in the services extension files examined earlier.
Inspect the secured messages using tcpmon
tcpmon as before and configure a proxy port to inspect the WSS-related SOAP messages. Make sure you provide the proxy port as input to the Service Port field on the sample client.
When you select only the Message Signing option, you will see that a WSS
<Security> element has been placed in the SOAP Header for both the request and response. This security element contains the
<Signature> sub-element which, in turn, contains the XML Digital Signature. The values of the parameters in the SOAP Body are still clear text. XML Digital Signature only ensures message integrity. This means that the message has not been tampered with in its path from the requestor to the provider and back. For convenience, these messages can also be viewed by looking at the
When you select only the Message Encryption option, you will see again the WSS
<Security> element in the SOAP Header. However, this time it contains the
<Encrypted> element containing information about the key, cipher, and so on. Additionally, the SOAP body does not have the clear text for the parameters. The request and response in the SOAP body have been encrypted and are contained in the
<EncryptedData> element. XML Encryption provides confidentiality, which guarantees that the data passed between the requester and provider is protected from eavesdroppers (like
tcpmon!). For convenience, these messages can be viewed by looking at the
Finally, select both Message Encryption and Signing. This time,
tcpmon shows both the
<Signature> elements within the WSS
<Security> element contained in the SOAP Header. The SOAP body is encrypted and cannot be read to spy on the parameter. Hence, this option provides both message integrity and confidentiality. These messages can also be viewed in the
When none of these options is enabled, the messages look like the unsecured messages inspected earlier.
Applying transport level security
Web services security infrastructure provides message-level security only. Additional steps are required for enabling TLS.
The sample code has already been enabled to use HTTPS/SSL. You can inspect the file
Certain SSL-related properties need to be set for the client JVM to make it aware of the protocol handlers and the location of the keystores. The code fragment in Listing 3 uses the stores shipped with WebSphere for providing the default security for its Web server. These properties need to be initialized before any SSL-related client invocation; a good place would be the rudimentary servlet's init method, as shown in the SomeBankServlet class.
Listing 3. Code fragment to set SSL properties
System.setProperty("java.protocol.handler.pkgs", "com.ibm.net.ssl.internal.www.protocol"); System.setProperty("javax.net.ssl.keyStore", "etc\\DummyClientKeyFile.jks"); System.setProperty("javax.net.ssl.keyStorePassword", "WebAS"); System.setProperty("javax.net.ssl.trustStore", "etc\\DummyClientTrustFile.jks"); System.setProperty("javax.net.ssl.trustStorePassword", "WebAS");
Next, the endpoint accessed by the client needs to point to the SSL port, for example:
https://localhost:9443/SomeBank/services/BankService/SomeBankPortSigned. This can be done in two ways:
- Changing the endpoint string in the locator file (
- Modifying the code to set the endpoint on the client stub dynamically (as in the case of the sample). This is demonstrated in the following code fragment:
((javax.xml.rpc.Stub) portTypeSigned)._setProperty(END_POINT, getLocatorURL(dataBean)+"/SomeBankPortSigned");
The getLocatorURL method inspects whether HTTP or HTTPS has been selected on the client and whether the client returns the fully formed URL to be used, for example,
Application of Web Services Security is quite straightforward in WebSphere Application Server V5.0.2. This is primarily due to the declarative model used to enable the security infrastructure. It provides a complete separation of the application development from the security aspects.
WS-Security incurs processing overhead and slows response times. Therefore, it should be used selectively based on compelling requirements mandated by application use cases. However, when a certain scenario warrants its use, WS-Security can be supported by supplementing the descriptor files with IBM extensions. As Web Services Security becomes adopted in the J2EE space, the IBM extensions will be provided through standard J2EE-based deployment descriptors.
SomeBank Account Service WSDL
|Code sample||WSS-Sample.zip ( HTTP | FTP )||.2 MB|
- Web Services Security (WS-Security) version 1.0
- WS-Security Specification Draft
- Security in a Web Services World: A Proposed Architecture and Roadmap
- Implementing WS-Security
- developerWorks WebSphere Web services zone
- developerWorks Web services zone
- JSR 109: Implementing Enterprise Web Services
- JSR 101: Java APIs for XML based RPC
- WebSphere Version 5 Web Services Handbook (SG24-6891-00)
- Meet the Experts: Tony Cowan on Web services security