Home | Download | PDF | API | FAQ | Search | Feedback | History

> ## 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
> - Using the Java WSDP XWSS Security Implementation

> ### 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:

> - Configure the Application Server so that web services security will be applied to all web services applications deployed on the Application Server. For more information, read How Does WSS Work in the Application Server.
> - Configure application-specific web services security by annotating the server-specific deployment descriptor. For more information, read Configuring Application-Specific Message Security.

> #### 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.

> - `message-security-binding`: This element specifies a custom authentication provider binding for a parent `webservice-endpoint` or `port-info` element by binding to a specific provider and/or by specifying the message security requirements enforced by the provider. It contains the attributes `auth-layer` and `provider-id` (optional).
> - `auth-layer`: This element specifies the message layer at which authentication is performed. The value must be `SOAP`.
> - `provider-id`: This element is optional and specifies the authentication provider used to satisfy application-specific message security requirements. If this attribute is not specified, a default provider is used, if there is one defined for the message layer. If no default provider is defined, authentication requirements defined in the `message-security-binding` element are not enforced.
> - `message-security`: This element specifies message security requirements. If the grandparent element is `webservice-endpoint`, these requirements pertain to request and response messages of the endpoint. If the grandparent element is `port-info`, these requirements pertain to the port of the referenced service.
> - `message`: This element includes the methods (`java-method`) and operations (`method-name`) to which message security requirements apply. If this element is not included, message protection applies to all methods.
> - `request-protection`: This element defines the authentication policy requirements of the application's request processing. It has attributes of `auth-source` and `auth-recipient` to define what type of protection is applied and when it is applied.
> - `response-protection`: This element defines the authentication policy requirements of the application's response processing. It has attributes of `auth-source` and `auth-recipient` to define what type of protection is applied and when it is applied.
> - `auth-source`: This attribute specifies the type of required authentication, either `sender` (user name and password) or `content` (digital signature). This is an attribute of the `request-protection` and `response-protection` elements.
> - `auth-recipient`: This attribute specifies whether recipient authentication occurs before or after content authentication. Allowed values are `before-content` and `after-content`. This is an attribute of the `request-protection` and `response-protection` elements.

> 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 `xms` application shows how to enable message layer security at the Application Server level by enabling the Application Server's default message security providers. In this case, web services are protected using default configuration files and default WSS providers.
> - The `xms_apl_lvl` application shows how to enable message layer security at the application level by modifying the runtime deployment descriptor (`sun-ejb-jar.xml` or `sun-web.xml`). In this case, you can selectively specify when/how message layer security can be applied to a specific method (or for all methods) in a web service.

> 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:

> - `<``INSTALL``>/samples/webservices/security/ejb/apps/xms/`
> - `<``INSTALL``>/samples/webservices/security/ejb/apps/xms_apl_lvl`

> 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:

> - Support for securing JAX-RPC and JAX-WS applications at the service, port, and operation levels.
> - XWS-Security APIs for securing both JAX-RPC and JAX-WS applications and stand-alone applications that make use of SAAJ APIs only for their SOAP messaging.
> - A sample security framework within which a JAX-RPC application developer will be able to secure applications by signing, verifying, encrypting, and/or decrypting parts of SOAP messages and attachments.

> The message sender can also make claims about the security properties by associating security tokens with the message. An example of a security claim is the identity of the sender, identified by a user name and password.

> - Support for SAML Tokens and the WSS SAML Token Profile (partial).
> - Support for securing attachments based on the WSS SwA Profile Draft.
> - Partial support for sending and receiving WS-I Basic Security Profile (BSP) 1.0 compliant messages.
> - Sample programs that demonstrate using the framework.

> XWSS supports deployment onto any of the following containers:

> - Sun Java System Application Server
> - Sun Java System Web Server
> - Apache Tomcat servlet container

> 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:

> `<?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.

> `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.

> `// 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:

> `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:

> `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,

> - Read the Java Web Services Developer Pack Tutorial. The tutorial can be accessed from`http://java.sun.com/webservices/docs/1.6/tutorial/doc/index.html`.
> - Read the XWSS samples documentation, which is located in the `<``JWSDP_HOME``>/xws-security/samples/` directory of your Java WSDP installation or at `http://java.sun.com/webservices/docs/2.0/xws-security/samples.html` online.
> - Visit the XWSS home page at `http://java.sun.com/webservices/xwss/`.
> - Take the Sun training class titled Developing Secure Java Web Services. To sign up, go to `https://www.sun.com/training/catalog/java/web_services.html`.