Using Message Security with Java EE

Because message security is not yet a part of the Java EE platform, and because message security is a very important component of web services security, this section presents a brief introduction to using both the Application Server's Web Services Security (WSS) and the Java WSDP's XML and Web Services Security (XWSS) functionality.

Using the Application Server Message Security Implementation

The Sun Java System Application Server uses Web Services Security (WS-Security) to secure messages. WS-Security is a message security mechanism that uses XML Encryption and XML Digital Signature to secure web services messages sent over SOAP. The WS-Security specification defines the use of various security tokens including X.509 certificates, SAML assertions, and username/password tokens to authenticate and encrypt SOAP web services messages.

The Application Server offers integrated support for the WS-Security standard in its web services client and server-side containers. This functionality is integrated such that web services security is enforced by the containers of the Application Server on behalf of applications, and such that it can be applied to protect any web service application without requiring changes to the implementation of the application. The Application Server achieves this effect by providing facilities to bind SOAP layer message security providers and message protection policies to containers and to applications deployed in containers.

There are two ways to enable message security when using the Application Server:

How Does WSS Work in the Application Server

Web services deployed on the Application Server are secured by binding SOAP layer message security providers and message protection policies to the containers in which the applications are deployed or to web service endpoints served by the applications. SOAP layer message security functionality is configured in the client-side containers of the Application Server by binding SOAP layer message security providers and message protection policies to the client containers or to the portable service references declared by client applications.

When the Application Server is installed, SOAP layer message security providers are configured in the client and server-side containers of the Application Server, where they are available for binding for use by the containers, or by individual applications or clients deployed in the containers. During installation, the providers are configured with a simple message protection policy that, if bound to a container, or to an application or client in a container, would cause the source of the content in all request and response messages to be authenticated by XML digital signature.

By default, message layer security is disabled on the Application Server. To configure message layer security at the Application Server level, read Configuring the Application Server for Message Security. To configure message security at the application level, read Configuring Application-Specific Message Security.

Configuring the Application Server for Message Security

The following steps briefly explain how to configure the Application Server for message security. For more detailed information on configuring the Application Server for message security, refer to the Application Server's Administration Guide. For a link to this document, see Further Information.

To configure the SOAP layer message security providers in the client and server-side containers of the Application Server, follow these steps:

  1. Start the Application Server as described in Starting and Stopping the Application Server (page 28).
  2. Start the Admin Console, as described in Starting the Admin Console (page 29).
  3. In the Admin Console tree component, expand the Configuration node.
  4. Expand the Security node.
  5. Expand the Message Security node.
  6. Select the SOAP node.
  7. Select the Message Security tab.
  8. On the Edit Message Security Configuration page, specify a provider to be used on the server side and/or a provider to be used on the client side for all applications for which a specific provider has not been bound. For more description of each of the fields on this page, select Help from the Admin Console.
  9. Select Save.
  10. To modify the message protection policies of the enabled providers, select the Providers tab.
  11. Select a provider for which to modify message protection policies. For more description on each of the fields on the Edit Provider Configuration page, select Help from the Admin Console.
  12. Click Save and restart the Application Server if so indicated.

Configuring Application-Specific Message Security

Application-specific web services message security functionality is configured (at application assembly) by adding message-security-binding elements to the web service endpoint. The message-security-binding elements are added to the runtime deployment descriptors of the application (sun-ejb-jar.xml, sun-web.xml, or sun-application-client.xml). These message-security-binding elements are used to associate a specific provider or message protection policy with a web services endpoint or service reference, and may be qualified so that they apply to a specific port or method of the corresponding endpoint or referenced service.

The following is an example of a sun-ejb-jar.xml deployment descriptor file to which a message-security-binding element has been added. You need a corresponding configuration on the client side, too. 

<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>ejbTaxCalc</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>

In this example, the message-security-binding element has been added to a web service endpoint for an enterprise bean. The elements highlighted in bold above are described briefly below and in more detail in the Application Server's Application Deployment Guide. A link to this document is provided in Further Information.

For more detailed information on configuring application-specific web services security, refer to the Application Server's Developer's Guide. For more detailed information on the elements used for message security binding, read the Application Server's Application Deployment Guide. For a link to these documents, see Further Information.

Example: Using Application Server WS-Security

The Application Server ships with sample applications named xms and xms_apl_lvl. Both applications features a simple web service that is implemented by both a Java EE EJB endpoint and a Java Servlet endpoint. Both endpoints share the same service endpoint interface. The service endpoint interface defines a single operation, sayHello, which takes a String argument, and returns a String composed by pre-pending Hello to the invocation argument.

The instructions which accompany the sample describe how to enable the WS-Security functionality of the Application Server such that it is used to secure the xms application. The sample also demonstrates the binding of WS-Security functionality directly to the application. (The /samples/ directory will only exist if you install the samples from the Java EE 5 SDK.)

The sample applications are installed in the following directories:

For information on compiling, packaging, and running the sample applications, refer to the sample file at <INSTALL>/samples/webservices/security/docs/common.html or to the Securing Applications chapter of the Application Server Developers' Guide (see Further Information, for a link to this document).

Debugging Message Security in the Application Server

To debug the web service message security providers for an application client, set the debug property to true in the sun-acc.xml file. Detailed information on this topic is included in the Securing Applications chapter of the Application Server Developers' Guide (see Further Information, for a link to this document).

Using the Java WSDP XWSS Security Implementation

The Java Web Services Developer Pack (Java WSDP) includes XML and Web Services Security (XWSS), a framework for securing JAX-RPC, JAX-WS, and SAAJ applications and message attachments.

XWS-Security includes the following features:

XWSS supports deployment onto any of the following containers:

Samples for using XWS-Security are included with Java WSDP in the directory <JWSDP_HOME>/xws-security/samples/ or can be viewed online at http://java.sun.com/webservices/docs/2.0/xws-security/samples.html.

Configuring Message Security Using XWSS

The Application Server contains all of the JAR files necessary to use XWS-Security for securing JAX-WS applications, however, in order to view the sample applications, you must download and install the standalone Java WSDP bundle. You can download the Java WSDP from http://java.sun.com/webservices/downloads/webservicespack.html.

To add message security to an existing JAX-WS application using XWSS, follow these steps on the client side:

  1. Create a client security configuration. The client security configuration file specifies the order and type of message security operations that will be used for the client application. For example, a simple security configuration to perform a digital signature operation looks like this:

    2.   <?xml version="1.0" encoding="UTF-8"?><xwss:JAXRPCSecurity
      xmlns:xwss="http://java.sun.com/xml/ns/xwss/config">
      <xwss:Service conformance= "bsp">
        <xwss:SecurityConfiguration dumpMessages="true" >

          <xwss:Sign id="s" includeTimestamp="true">
            <xwss:X509Token encodingType="http://docs.oasis-open.org/wss/2004/01/
              oasis-200401-wss-soap-message-security-1.0#Base64Binary"
              valueType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
              x509-token-profile-1.0#X509SubjectKeyIdentifier"
              certificateAlias="xws-security-client" keyReferenceType="Identifier"/>
          </xwss:Sign>

        </xwss:SecurityConfiguration>
      </xwss:Service>

      <xwss:SecurityEnvironmentHandler>
        simple.client.SecurityEnvironmentHandler
      </xwss:SecurityEnvironmentHandler>
      </xwss:JAXRPCSecurity>

    For more information on writing and understanding security configurations and setting up SecurityEnvironmentHandlers, please see the Java Web Services Developer Pack Tutorial at http://java.sun.com/webservices/docs/1.6/tutorial/doc/index.html.

    Information about running the example application is included in <JWSDP_HOME>/xws-security/samples/jaxws2.0/simple-doclit/README.txt and in the Java Web Services Tutorial.

  2. In your client code, create an XWSSecurityConfiguration object initialized with the security configuration generated. Here is an example of the code that you would use in your client file. For an example of a complete file that uses this code, look at the example client in the jaxws2.0/simple-doclit/src/simple/client directory.

    3.     FileInputStream f = new FileInputStream("./etc/client_security_config.xml");
        XWSSecurityConfiguration config =
          SecurityConfigurationFactory.newXWSSecurityConfiguration(f);

  3. Set security configuration information on the RequestContext by using the XWSSecurityConfiguration.MESSAGE_SECURITY_CONFIGURATION property. For an example of a complete file that uses this code, look at the example client in the jaxws2.0/simple-doclit/src/simple/client directory.

    4.     // put the security config info
        ((BindingProvider)stub).getRequestContext().
          put(XWSSecurityConfiguration.MESSAGE_SECURITY_CONFIGURATION,
            config);

  4. Invoke the method on the stub as you would if you were writing the client without regard to adding XWS-Security. The example for the application from the jaxws2.0/simple-doclit/src/simple/client directory is as shown below:

    5.     Holder<String> hold = new Holder("Hello !");
        stub.ping(ticket, hold);

To add message security to an existing JAX-RPC, JAX-WS, or SAAJ application using XWSS, follow these steps on the server side:

  1. Create a server security configuration file and give it the name:

    2. serviceName + "_" + "security_config.xml

    An example of a server security configuration file can be found in jaxws2.0/simple-doclit/etc/server_security_config.xml.

  2. No other changes need to be made to the server-side JAX-WS code.

For more information on XWSS,