Security

Introduction

Security in OMII-BPEL is about to secure and authorize (or to be authorized) communication to (and from) the BPEL engine. OMII container comes with implementations of a chain of Axis handlers that intercept SOAP messages that contain WS-Security headers to perform signature verification or, outbound message signing. In addition to security support based on WS-Security and X.509 certificate, transport level security protocol is also supported, adding more confidence on secure communication. (For more security information about OMII, please refer the online document.) OMII-BPEL release is fully integrated into the OMII security infrastructure. Security features can be easily configured and this document is to show how it is done.

WS-Security

ActiveBPEL

Given the fact that ActiveBPEL is designed and built with Axis, Axis handlers and the principle apply to it too, which means we need to declaratively add these security handlers into ActiveBPEL's message chains. If you are familiar with Axis already, you know these handlers should go into the <requestFlow> or <responseFlow>. What is worth mentioning, although, is the ActiveBPEL's playing both the role of a server and a client. In the scenario of a client's (for example, Web Service Explorer in BPEL Designer) calling a BPEL process deployed in ActiveBPEL, the engine is no doubt a server role, as a service provider. Security check needs to be enforced whenever a request message is being sent to the engine. Then at the time when a part of the process is calling an external service, ActiveBPEL plays the role of a client to that service. Therefore messages that originate from ActiveBPEL will in turn need all credential added prior to being sent. In both cases, the right handlers of choice need to be placed in the message chains properly.

ActiveBPEL puts the following two configuration files in $CATALINA_HOME/shared/classes/, with which we can add the handlers for its role of either a server or a client accordingly.

ae-server-config.wsdd
ae-client-config.wsdd

ae-server-config.wsdd
Under the <requestFlow> and <responseFlow> tags inside <globalConfiguration>, the handlers have been inserted in the following way.

      …
      <globalConfiguration>

         <requestFlow>
                 …
                 <handler name="SecurityContextInitHandler" type="java:uk.ac.omii.security.wss4j.handler.PolicyEnforcementHandler">
                       <parameter name="action" value="Timestamp Signature"/>
                       <parameter name="signaturePropFile" value="crypto.properties"/>
                       <parameter name="signatureKeyIdentifier" value="DirectReference" />
                       <parameter name="passwordCallbackClass" value="uk.ac.omii.security.utils.PWCallback"/>
                       <parameter name="signatureParts" value= "{}{http://schemas.xmlsoap.org/soap/envelope/}Body;{}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp"/>
      </handler>

                
         </requestFlow>

         <responseFlow>
                …
                <handler name="IntegrityEnforcementHandler" type="java:uk.ac.omii.security.wss4j.handler.WSOutboundHandler">
                      <parameter name="action" value="Timestamp Signature"/>
                      <parameter name="signaturePropFile" value="crypto.properties"/>
                      <parameter name="signatureKeyIdentifier" value="DirectReference" />
                      <parameter name="passwordCallbackClass" value="uk.ac.omii.security.utils.PWCallback"/>
                      <parameter name="signatureParts" value="{}{http://schemas.xmlsoap.org/soap/envelope/}Body;{}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp;"/>
                </handler>

                
         </responseFlow>

      </globalConfiguration>
      …

ae-client-config.wsdd
      Under the <requestFlow> and <responseFlow> tags inside <globalConfiguration>, handlers have been inserted in the following way:
      …
      <globalConfiguration>

         <requestFlow>
                 …
                <handler type="java:uk.ac.omii.security.wss4j.handler.WSOutboundHandler" >
                   <parameter name="action" value="Timestamp Signature"/>
                   <parameter name="signaturePropFile" value="crypto.properties" />
                   <parameter name="signatureKeyIdentifier" value="DirectReference" />
                   <parameter name="signatureParts" value="{}{http://schemas.xmlsoap.org/soap/envelope/}Body;{}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp"/>
                   <parameter name="passwordCallbackClass"
                     value="uk.ac.omii.security.utils.PWCallback"/>
                </handler>

                
         </requestFlow>

         <responseFlow>
                …

                <handler type="java:uk.ac.omii.security.wss4j.handler.PolicyEnforcementHandler">
                   <parameter name="action" value="Timestamp Signature"/>
                   <parameter name="signaturePropFile" value="crypto.properties" />
                   <parameter name="signatureKeyIdentifier" value="DirectReference" />
                   <parameter name="passwordCallbackClass" value="uk.ac.omii.security.utils.PWCallback"/>
                   <parameter name="signatureParts" value="{}{http://schemas.xmlsoap.org/soap/envelope/}Body;{}{http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd}Timestamp"/>
                   <parameter name="ignoreEndpointCNmismatch" value="true" />
                </handler>

                

         </responseFlow>

      </globalConfiguration>

      …

BPEL Designer
On the client side, request message sent with WSE is by default signed. To toggle this option, simply check or uncheck the feature on the invocation page, i.e. where you initialize the request message in the web form. (Refer to user guide for screen shot.)

Transport Level Security

SSL protocol can be easily switched on in OMII container. This can be done by setting up the HTTPs connector for Tomcat. Details can also be found out in OMII's security document. Because of the same reason that ActiveBPEL engine plays also the client role when a BPEL process has to invoke some external services, ActiveBPEL should be informed beforehand whether the attempt of SSL's setting up a secure channel between ActiveBPEL and the other service should be authorized. i.e. whether ActiveBPEL should trust the service. ActiveBPEL depends on the Java Runtime to tell it who it should trust. (Please also see ActiveBPEL's online document for more details.)

Tomcat
Locate $CATALINA_HOME/conf/server.xml.
Comment out the default <Connector> with port number 18080, but uncomment the one with port number 18443.

ActiveBPEL
As explained earlier, the server certificate must be imported into Java Runtime before starting the server.

    keytool –import –alias omii_server –file ${OMII_HOME}/omii.crt –keystore $JAVA_HOME/jre/lib/security/cacerts

Default password: changeit

You might need to gain write permission first to the file.

To delete an previously added (probably expires by now) certificate, use the following command.

    keytool -delete -alias omii_server -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit

Once imported, use the following command to see omii_server is stored in the list.

keytool -list -v -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit

Note you will need to restart the server to take this into effect.

Protocol
Another word about SSL is all instances of "http" that going to be used to access the server must be replaced with "https" after the changes, and all port number of "18080" are substituted by "18443". Make sure these changes are consistent across your project.