Dynamic Policy Sample Application

The dynamic-policy sample application demonstrates how to specify (or change) the request and/or response security policy at runtime using the XWS-Security APIs. Another sample that demonstrates using the XWS-Security APIs is api-sample, which is discussed in XWS-Security APIs Sample Application.

You would want to dynamically set the security policy for an application at runtime when one of these conditions is present:

Response policy: When you don't know who the requester may be, you want to be able to specify the response security policy after you determine the identity of the requester.

Request policy: When you don't know what the runtime parameters will be, you want to discover these parameters, such as whether SSL is enabled at the transport layer, before you specify your request policy.

The application prints out both the client and server request and response SOAP messages. The output from the server may be viewed in the appropriate container's log file. The output from the client is sent to stdout or to whichever stream is used by the configured log handler. Messages are logged at the INFO level.

In this example, server-side code is found in the /dynamic-policy/server/src/sample/ directory. Client-side code is found in the /dynamic-policy/client/src/sample/ directory. The asant (or ant) targets build objects under the /build/server/ and /build/client/ directories.

Security Configuration Files for Enabling Dynamic Policy

To specify the request and/or response security policy dynamically at runtime, you need to enable DynamicPolicyCallback by setting the enableDynamicPolicy flag on the <xwss:SecurityConfiguration> element. The application-defined runtime parameters can then be set by the application and passed into the ProcessingContext, which is made available to the CallbackHandler as a DynamicApplicationContext. The CallbackHandler can then modify an existing policy or set a completely new policy into the Callback.

As you can see, the security configuration files for this example are very simple, because the actual security policy that will be applied at runtime is being decided by SecurityEnvironmentHandler. The SecurityEnvironmentHandler is discussed in Setting Security Policies at Runtime. The security configuration file for the client, dynamic-client.xml, looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>
        <!-- the exact policy to apply will be decided by the 
               SecurityEnvironmentHandler at runtime -->
        <xwss:SecurityConfiguration dumpMessages="true" enable-
DynamicPolicy="true">
        </xwss:SecurityConfiguration>
   </xwss:Service>

    <xwss:SecurityEnvironmentHandler>
        com.sun.xml.wss.sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity>

The security configuration file for the server, dynamic-server.xml, looks like this:

<xwss:JAXRPCSecurity xmlns:xwss="http://java.sun.com/xml/ns/
xwss/config">

    <xwss:Service>
         <!-- the exact policy to apply will be decided by the 
                SecurityEnvironmentHandler at runtime -->
        <xwss:SecurityConfiguration dumpMessages="true" enable-
DynamicPolicy="true">
        </xwss:SecurityConfiguration>
   </xwss:Service>

    <xwss:SecurityEnvironmentHandler>
        com.sun.xml.wss.sample.SecurityEnvironmentHandler
    </xwss:SecurityEnvironmentHandler>

</xwss:JAXRPCSecurity>

Setting Security Policies at Runtime

The dynamic-policy sample application demonstrates how the request and response security policies can be set at runtime from the SecurityEnvironmentHandler callback.

In this sample, the SecurityEnvironmentHandler inserts a SignaturePolicy at runtime. The SignaturePolicy asks for a signature over the body of the message. For the requesting side, this is equivalent to using an <xwss:Sign> element in the configuration file. For the receiving side, this is equivalent to using an <xwss:RequireSignature> element in the configuration file. Both the request and response contain a signature over the body.

Note: The APIs used in this sample by the SecurityEnvironmentHandler callback are evolving and hence are subject to modification prior to the release of XWS Security FCS 2.0.

The full code for the SecurityEnvironmentHandler is located in the /dynamic-policy/src/com/sun/xml/wss/sample directory. The SecurityEnvironmentHandler file is a sample implementation of a CallbackHandler. The following snippet of that file demonstrates how to handle a DynamicPolicyCallback:

} else if (callbacks[i] instanceof DynamicPolicyCallback) {
                DynamicPolicyCallback dpCallback = 
(DynamicPolicyCallback) callbacks[i];
                SecurityPolicy policy = 
dpCallback.getSecurityPolicy();
                                                                                                                                              
                if (policy instanceof WSSPolicy) {
                    try {
                         handleWSSPolicy (dpCallback);
                    } catch (PolicyGenerationException pge) {
                         throw new IOException (pge.getMessage());
                    }
                } else if (policy instanceof DynamicSecurityPolicy) 
{
                    try {
                         handleDynamicSecurityPolicy (dpCallback);
                    } catch (PolicyGenerationException pge) {
                         throw new IOException (pge.getMessage());
                    }
                } else {
                    throw unsupported;
                }

Running the Dynamic Policy Sample Application

Complete the tasks defined in the following sections of this addendum:

Setting System Properties

Configuring a JCE Provider

Setting Build Properties

Start the selected container and make sure the server is running. To start the Application Server,

From a Unix machine, enter the following command from a terminal window: asadmin start-domain domain1

From a Windows machine, choose Start Right Arrow

Programs

Sun Microsystems Right Arrow

J2EE 1.4

Start Default Server.

Build and run the application from a terminal window or command prompt.

On the Application Server, the command to build and run the application is: asant run-sample

On the other containers, the command to build and run the application is: ant run-sample

Note: To run the sample against a remote server containing the deployed endpoint, use the run-remote-sample target in place of the run-sample target. In this situation, make sure that the endpoint.host, endpoint.port, http.proxyHost, http.proxyPort, and service.url properties are set correctly in the build.properties file (as discussed in Setting Build Properties) before running the sample.

If the application runs successfully, you will see a message similar to the following:

[echo] Running the client program....
[java] ==== Sending Message Start ====
...
[java] ==== Sending Message End ====
[java] ==== Received Message Start ====
...
[java] ==== Received Message End ====

<SJSAS_HOME>/domains/<domain-name>/logs/server.log 
<TOMCAT_HOME>/logs/launcher.server.log 
<SJSWS_HOME>/<Virtual-Server-Dir>/logs/errors