Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Developer's Guide

Configuring Message Security

In message security, security information travels along with the web services message. WSS in the SOAP layer is the use of XML Encryption and XML Digital Signatures to secure SOAP messages. WSS profiles the use of various security tokens including X.509 certificates, SAML assertions, and username/password tokens to achieve this.

Message layer security differs from transport layer security (which is discussed in the Security chapter of the J2EE 1.4 Tutorial) in that message layer security can be used to decouple message protection from message transport so that messages remain protected after transmission, regardless of how many hops they travel on.

WSS is a security mechanism that is applied at the message-layer in order to secure web services. For the purposes of this document, when we discuss WSS, we are talking about security for web services as described by the Oasis Web Services Security (WSS) specification. Message security for the Application Server follows this specification, which can be viewed at the following URL:

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

For more information about message security, see the following:

The J2EE 1.4 Tutorial chapter titled Security, which can be viewed from:http://java.sun.com/j2ee/1.4/docs/tutorial/doc/index.html.
The Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide chapter titled Configuring Message Security.

The following web services security topics are discussed in this section:

Message Security Responsibilities

Message security responsibilities are assigned to the following:

Application Developer

The application developer can implement message security, but is not responsible for doing so. Message security can be set up by the System Administrator so that all web services are secured, or set up by the Application Deployer when the Application Server provider configuration is insufficient.

The application developer is responsible for the following:

Determining if an application-specific policy is necessary for an application. If so, ensure that policy is satisfied at application assembly, or communicate the requirement for application-specific message security to the Application Deployer, or take care of implementing the application-specific policy.
Determining if message security is necessary at the Application Server level. If so, ensure that need is communicated to the System Administrator, or take care of implementing message security at the Application-Server level.

Application Deployer

The application deployer is responsible for:

Securing the application if it has not been appropriately secured by upstream roles (the developer or assembler) and only if an application-specific policy is appropriate for the application.
Implementing application-specific security by adding the message security binding to the web service endpoint.
Modifying Sun-specific deployment descriptors to add message binding information.

These security tasks are discussed in Application-Specific Message Protection. An example application using message security is discussed in Understanding and Running the Example Application.

System Administrator

The system administrator is responsible for:

Configuring message security providers on the Application Server.
Managing user databases.
Managing keystore and truststore files.
Configuring a Java Cryptography Extension (JCE) provider if using Encryption and running a version of the Java SDK prior to version 1.5.0.
Installing the samples server in order to work with the example message security applications.

A system administrator uses the Admin Console or the asadmin tool to manage server security settings and keytool to manage certificates. System administrator tasks are discussed in the Configuring Message Security chapter of the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

Application-Specific Message Protection

When the Application Server provided configuration is insufficient for your security needs, and you want to override the default protection, you can apply application-specific message security to a web service.

Application-specific security is implemented by adding the message security binding to the web service endpoint, whether it is an EJB or servlet web service endpoint. Modify Sun-specific XML files to add the message binding information.

For more details on message security binding for EJB web services, servlet web services, and clients, see the XML file descriptions in Appendix A, Deployment Descriptor Files.

For sun-ejb-jar.xml, see The sun-ejb-jar.xml File.
For sun-web.xml, see The sun-web.xml File.
For sun-application-client.xml, see The sun-application-client.xml file.

This section contains the following topics:

Using a Signature to Enable Message Protection for All Methods

To enable message protection for all methods using digital signature, update the message-security-binding element for the EJB web service endpoint in the application’s sun-ejb-jar.xml file. In this file, add request-protection and response-protection elements, which are analogous to the request-policy and response-policy elements discussed in the Configuring Message Security chapter of the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide. In order to apply the same protection mechanisms for all methods, leave the method-name element blank. Configuring Message Protection For a Specific Method Based on Digital Signatures discusses listing specific methods or using wildcard characters.

This section uses the sample application discussed in Understanding and Running the Example Application to apply application-level message security in order to show only the differences necessary for protecting web services using various mechanisms.

To enable message protection for all methods using digital signature

In a text editor, open the application’s sun-ejb-jar.xml file.

For the xms example, this file is located in the directory install-dir /samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf.

Modify the sun-ejb-jar.xml file by adding the message-security-binding element as shown:

<sun-ejb-jar>
  <enterprise-beans>
    <unique-id>1</unique-id>
    <ejb>
      <ejb-name>HelloWorld</ejb-name>
      <jndi-name>HelloWorld</jndi-name>
      <webservice-endpoint>
        <port-component-name>HelloIF</port-component-name>
        <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
        <message-security-binding auth-layer="SOAP">
          <message-security>
            <request-protection auth-source="content" />
            <response-protection auth-source="content"/>
          </message-security>
        </message-security-binding>
      </webservice-endpoint>
    </ejb>
  </enterprise-beans>
</sun-ejb-jar>

Compile, deploy, and run the application as described in To Run the Sample Application.

Configuring Message Protection For a Specific Method Based on Digital Signatures

To enable message protection for a specific method, or for a set of methods that can be identified using a wildcard value, follow these steps. As in the example discussed in Using a Signature to Enable Message Protection for All Methods, to enable message protection for a specific method, update the message-security-binding element for the EJB web service endpoint in the application’s sun-ejb-jar.xml file. To this file, add request-protection and response-protection elements, which are analogous to the request-policy and response-policy elements discussed in the Configuring Message Security chapter of the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide. The Administration Guide includes a table listing the set and order of security operations for different request and response policy configurations.

To enable message protection for a particular method or set of methods using digital signature

In a text editor, open the application’s sun-ejb-jar.xml file.

For the xms example, this file is located in the directory install-dir/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf.

Modify the sun-ejb-jar.xml file by adding the message-security-binding element as shown:

<sun-ejb-jar>
  <enterprise-beans>
  <unique-id>1</unique-id>
    <ejb>
      <ejb-name>HelloWorld</ejb-name>
      <jndi-name>HelloWorld</jndi-name>
      <webservice-endpoint>
        <port-component-name>HelloIF</port-component-name>
        <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
        <message-security-binding auth-layer="SOAP">
          <message-security>
            <message>
              <java-method>
                <method-name>ejbCreate</method-name>
              </java-method>
            </message>
            <message>
              <java-method>
                <method-name>sayHello</method-name>
              </java-method>
            </message>
            <request-protection auth-source="content" />
            <response-protection auth-source="content"/>
          </message-security>
        </message-security-binding>
      </webservice-endpoint>
    </ejb>
  </enterprise-beans>
</sun-ejb-jar>

Compile, deploy, and run the application as described in To Run the Sample Application.

Understanding and Running the Example Application

This section discusses the WSS sample application, xms, which is located in the directory install-dir/samples/webservices/security/ejb/apps/xms/. This directory and this sample application is installed on your system only if you have selected to install the samples server when you installed the Application Server. If you have not installed the samples, see To Set Up the Sample Application.

The objective of this sample application is to demonstrate how a web service can be secured with WSS. The web service in the xms example is a simple web service implemented using a J2EE EJB endpoint and a web service endpoint implemented using a servlet. In this example, a service endpoint interface is defined with one operation, sayHello, which takes a string then sends a response with Hello prefixed to the given string. You can view the WSDL file for the service endpoint interface at install-dir/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf/HelloWorld.wsdl.

In this application, the client lookups the service using the JNDI name java:comp/env/service/HelloWorld and gets the port information using a static stub to invoke the operation using a given name. For the name Duke, the client gets the response Hello Duke!

This example shows how to use message security for web services at the Application Server level and at the application level. The WSS message security mechanisms implement message-level authentication (for example, XML digital signature and encryption) of SOAP web services invocations using the X.509 and username/password profiles of the OASIS WS-Security standard, which can be viewed from the following URL:

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf

This section includes the following topics:

To Set Up the Sample Application

Before You Begin

The example application is located in the directory install-dir/samples/webservices/security/ejb/apps/xms/. For ease of reference throughout the rest of this section, this directory is referred to as simply app-dir/xms/.

In order to have access to this sample application, you must have installed the samples server during installation of the Application Server. To check to see if the samples are installed, browse to the directory install-dir/samples/webservices/security/ejb/apps/xms/. If this directory exists, you do not need to follow the steps in the following section. If this directory does not exist, the samples server is not installed, and must be installed for access to the sample application discussed here.

Start the installation for the Application Server.

Click Next on the Welcome page.

Click Yes on the Software License Agreement page. Click Next.

Click Next to accept the installation directory, or change it to match the location where the Application Server is currently installed.

Select Continue to install to the same directory.

You want to do this because you want the samples/ directory to be a subdirectory of the Application Server directory, install-dir/samples/.

Reenter the Admin User Name and Password. Click Next.

You are on the page where you select to install just the samples.

Deselect everything except Create Samples Server. Click Next.

Click Install Now to install the samples.

Click Finish to complete the installation.

To Run the Sample Application

Make sure that the Application Server is running.

Message security providers are set up when the asant targets are run, so you don’t need to configure these on the Application Server prior to running this example.

If you are not running HTTP on the default port of 8080, change the WSDL file for the example to reflect the change, and change the common.properties file to reflect the change as well.

The WSDL file for this example is located at install-dir/samples/webservices/security/ejb/apps/xms/xms-ejb/src/conf/HelloWorld.wsdl. The port number is in the following section:
```
<service name="HelloWorld">
  <port name="HelloIFPort" binding="tns:HelloIFBinding">
    <soap:address location="http://localhost:8080/service/HelloWorld"/>
  </port>
</service>
```
Verify that the properties in the install-dir/samples/common.properties file are set properly for your installation and environment. If you need more description of this file, refer to the Configuration section for the web services security applications at install-dir/samples/webservices/security/docs/common.html#Logging.

Change to the install-dir/samples/webservices/security/ejb/apps/xms/ directory.

Run the following asant targets to compile, deploy, and run the example application:
1. To compile samples:
  
  asant
2. To deploy samples:
  
  asant deploy
3. To run samples:
  
  asant run
If the sample has compiled and deployed properly, you see the following response on your screen after the application has run:

run:[echo] Running the xms program:[exec] Established message level security : Hello Duke!

To undeploy the sample, run the following asant target:
asant undeploy
All of the web services security examples use the same web service name (HelloWorld) and web service ports in order to show only the differences necessary for protecting web services using various mechanisms. Make sure to undeploy an application when you have completed running it, or you receive an Already in Use error and deployment failures when you try to deploy another web services example application.

Monitoring Message Security

To view SOAP messages containing security elements in the server.log file, set the parameter dumpMessages=true in the file domain-dir/config/wss-server-config.xml, and then restart the server.

The section of the wss-server-config.xml file that needs to be modified to enable this is as shown below:

<xwss:SecurityConfiguration
    xmlns:xwss="http://com.sun.xml.wss.configuration"
    useTimestamps="true"
    dumpMessages="true">

After you have enabled SOAP messages in the server.log file, you can verify if the username-password token is enabled by checking the domain-dir/logs/server.log file for the tag <wsse:UsernamePassword>. The following selection of code is similar to what you might see in the server.log file, with the UsernameToken tag.

<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:enc="http://schemas.xmlsoap.org/soap/encoding/" 
xmlns:ns0="http://tax.org/wsdl" 
xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" >
<env:Header>
  <wsse:Security   xmlns:wsse="http://docs.oasis-open.org/wss/2004/
    01/oasis-200401-wss-wssecurity-secext-1.0.xsd" env:mustUnderstand="1">
    <wsse:UsernameToken>
      <wsse:Username>j2ee</wsse:Username>
      <wsse:Password Type="http://docs.oasis-open.org/wss/2004/
      01/oasis-200401-wss-username-token-profile-1.0#PasswordText">j2ee
      </wsse:Password>
    </wsse:UsernameToken>
    <wsu:Timestamp xmlns:wsu="http://docs.oasis-open.org/wss/2004/
      01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
      <wsu:Created>2004-08-22T09:07:58Z</wsu:Created>
    </wsu:Timestamp>
    </wsse:Security>
      </env:Header>
      <env:Body>
        <ns0:getStateTax>
        <double_1 xsi:type="xsd:double">85000.0</double_1>
        <double_2 xsi:type="xsd:double">5000.0</double_2>
        </ns0:getStateTax>
      </env:Body>
</env:Envelope>