Modeling Secure Web Services

To enable security for an Inbound Web Service you need to add a request and a response handler for each web service.

The request security handler processes the incoming SOAP messages and is specified using the IBM Cúram Social Program Management Request_Handlers property in Rational Software Architect. An example of this property's value is shown in Modeling Secure Web Services).

Figure 1. Request Handler for a web service

<handler type=
  \"java:org.apache.ws.axis.security.WSDoAllReceiver\">
  <parameter name=\"passwordCallbackClass\"
             value=\"webservice.ServerPWCallback\"/>
  <parameter name=\"action\"
             value=\"UsernameToken Signature Encrypt\"/>
  <parameter name=\"passwordType\"
             value=\"PasswordText\" />
  <parameter name=\"signaturePropFile\"
             value=\"server-crypto.properties\" />
  <parameter name=\"signatureParts\"
             value=\"{Element}{http://docs.oasis-open.org/wss/
2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd}UsernameToken;
{Content}{}Body\" />
  <parameter name=\"encryptionParts\"
             value=\"{Element}{http://docs.oasis-open.org/wss/
2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd}UsernameToken;
{Content}{}Body\" />
</handler>

The response security handler processes the outgoing SOAP messages and is specified using the IBM Cúram Social Program Management Response_Handlers property in Rational Software Architect. An example of this option's value is shown in Modeling Secure Web Services.

Figure 2. Response Handler for a web service

<handler type=
\"java:org.apache.ws.axis.security.WSDoAllSender\">
  <parameter name=\"passwordCallbackClass\"
             value=\"webservice.ServerPWCallback\"/>
  <parameter name=\"action\"
             value=\"Signature Encrypt\"/>
  <parameter name=\"signaturePropFile\"
             value=\"server-crypto.properties\" />
  <parameter name=\"user\" value=\"curam-sv\"/>
  <parameter name=\"encryptionUser\" value=\"curam\"/>
</handler>

The use of these options results in the addition of the security handler information to the request flow and response flow of handlers in the server-config.wsdd deployment descriptor file for the web service.

In the examples above the action value UsernameToken directs the handler to insert a UsernameToken token, containing the username and password, into the SOAP request. The values Signature and Encrypt define that the SOAP message should be signed and encrypted. This results in the handler first signing and then encrypting the data. The value of encryptionParts and signatureParts specifies to sign and encrypt the SOAP message's security header and body elements.

The value of signaturePropFile specifies the name of the signature crypto property file to use. This file contains the properties used for signing and encrypting the SOAP message. The example of crypto property file is shown in Modeling Secure Web Services:

Figure 3. Example server-crypto.properties File

org.apache.ws.security.crypto.provider=
org.apache.ws.security.components.crypto.Merlin
org.apache.ws.security.crypto.merlin.keystore.type=jks
org.apache.ws.security.crypto.merlin.keystore.password=password
org.apache.ws.security.crypto.merlin.file=server.keystore

When configuring a web service the signature property file and keystore file (server-crypto.properties and server.keystore) must be placed in the %SERVER_DIR%/project/config/wss/ directory. Keystore File Creation describes how to create file server.keystore.

The security handler (passwordCallbackClass), webservice.ServerPWCallback in Modeling Secure Web Services and Modeling Secure Web Services above, provides a password callback mechanism and should be implemented by the developer. The example of an implementation for webservice.ServerPWCallback is shown in Modeling Secure Web Services:

Figure 4. ServerPWCallback.java

package webservice;
import java.io.IOException;
import javax.security.auth.callback.Callback;
import javax.security.auth.callback.CallbackHandler;
import javax.security.auth.callback.UnsupportedCallbackException;
import org.apache.ws.security.WSPasswordCallback;

/**
 * Implementation of password callback class.
 */
public class ServerPWCallback implements CallbackHandler {

  /**
   * Retrieve or display the information requested in the
   * provided Callbacks.
   *
   * @param callbacks an array of Callback objects provided by
   * an underlying security service which contains the
   * information requested to be retrieved or displayed.
   *
   * @throws IOException if an input or output error occurs.
   * @throws UnsupportedCallbackException if the implementation
   * of this method does not support one or more of the Callbacks
   * specified in the callbacks parameter.
   */
  public void handle(final Callback[] callbacks)
    throws IOException, UnsupportedCallbackException {

    for (int i = 0; i < callbacks.length; i++) {
      if (callbacks[i] instanceof WSPasswordCallback) {
        final WSPasswordCallback pc =
          (WSPasswordCallback) callbacks[i];
        /*
         * Here call a method to lookup the password for
         * the given identifier (e.g. a user name or key
         * store alias), e.g. pc.setPassword(
         * passStore.getPassword(pc.getIdentfifier))
         * for testing we supply a fixed name/fixed key here.
         */
        if ("beantester".equals(pc.getIdentifer())) {
            pc.setPassword("password");
        } else if ("curam-sv".equals(pc.getIdentifer())) {
            pc.setPassword("password");
        } else if ("curam".equals(pc.getIdentifer())) {
            pc.setPassword("password");
        }

      } else {
        throw new UnsupportedCallbackException(callbacks[i],
          "Unrecognized Callback");
      }
    }
  }