Metro Security has a pluggable architecture and it makes use of JSR 196  (SOAP Profile) to achieve this pluggability.   The use of JSR-196 provides a standard way to integrate Metro with the Authentication and Authorization Infrastructure of the underlying container.  Though not all containers  on which metro can run today support JSR 196, the idea is that as more and more containers adopt JSR-196, integrating the metro webservices stack with those container would become easy. The use of JSR-196 in metro is also based on the principle of  re-using what is already a standard inorder to avoid proliferation of proprietary API's.

  In the absence of JSR-196, when Metro is used on a Non-GlassFish container then developers of  Secure WebServices today are forced to configure a whole lot of things such as CallbackHandler's, Validator's, Keystore's, CertStore's etc, some of which can be non-trivial.  All of these configurations would not be necessary if  the container supported a publicly callable JSR-196 CallbackHandler that metro could use. 

When a Metro Secure WebService runs on GlassFish it automatically leverages  the Container's Authentication and Authorization Mechanisms by way of invoking the GlassFish JSR-196 CallbackHandler, so user's of metro on GlassFish would generally not have to configure  additional things inside the metro configuration file w.r.t security. Metro runtime would invoke the GlassFish JSR-196 CallbackHandler. The GlassFish CallbackHandler would use the container configured mechanisms to authenticate let's say the username-password and finally establish the container's representation of the caller principal in the Subject. This Subject would then be used during the Authorization process.

Metro bundles the JSR-196 API along with it so that one can use  Metro with JSR-196 enabled on any Container (not just GlassFish). So here are  some of the pluggability points that are enabled in metro due to the use of JSR 196 underneath.

1.  At the lowest level one can specify  a JSR 196 CallbackHandler on the client and server side to be used by the metro configuration. A JSR 196 Callbackhandler is a callbackhandler that handles the callbacks defined by the JSR-196 specification. More details on how end-users can specify a JSR-196 callbackhandler  can be found in this post here (look for section : JMACCallbackHandler). This facility can be used only when running on GlassFish.  When specified it overrides the GlassFish default Callbackhandler.
   
2.  By default only JSR-109 WebServices on GlassFish make use of the JSR-196 path but one can enable the use of JSR-196 for Plain-JAXWS applications as well by placing the following (gf-196-hook.jar) into GlassFish lib directory. This maybe fixed in near future such that all webservices on glassfish would use JSR-196 path. However we get bitten by the same old backward-compatibility bug that prevents us from eagerly doing it.
   
3. The Metro WS-* implementation makes use of the  JAXWS Tubes SPI . This  allows composing different Tubes in a Tubeline in a certain order to make the different WS-* implementations work together and produce the desired transformation on the WebService Messages.  The Security Tube in Metro in turn uses JSR-196 and thereby allows someone to replace the default JSR-196 AuthConfigProvider in Metro with something of their own. This feature is used by the OpenSSO stack when it replaces the WS-Security Implementation in Metro with it's own implementation for a few product specific reasons. The use of JSR-196 decouples the Security Tube from the Specifics of the WS-Security Implementation thereby allowing a different WS-Security implementation to be plugged in (complete with its own configuration definitions etc).   This feature is available when Metro Stack in running on any container including GlasssFish. Again for backward-compatibility reasons this feature is currently not enabled by default in Metro, but can be enabled by placing (wsit-196-hook.jar) in the containers classpath (for example the lib directory in GlassFish V2). There is a META-INF/services entry inside  wsit-196-hook.jar named javax.security.auth.message.config.AuthConfigProvider  whose contents point to the default Metro AuthConfigProvider (ACP).  If someone needs to plugin their own ACP then they would need to update this entry with the classname of their ACP implementation classs.

When using Pluggability Option 3 above one has to be aware of (and handle) three Container/Environment specific issues.

1. The Keying Infrastructure and Container's Representation of caller Principal/Groups differ from container to container and so the JSR-196 CallbackHandler comes to the rescue here.  There are a few limitations when it comes to the set of Callbacks defined in the JSR-196 standard versus those required in a typical WS-Security scenario (for example the JSR-196 callbacks do not have any callback to handle CertificateValidation which is generally an important thing in a Mutual Certificates Scenario). However the JSR-196 standard does not prevent CallbackHandlers to handle other proprietary callbacks. So metro defines a few extension callbacks to deal with this.   There is a  META-INF/services entry inside wsit-196-hook.jar named javax.security.auth.message.callback.CallbackHandler  whose contents by default point to the correct classname of the JSR-196 CallbackHandler for GlassFish V2. When running on a different container one would need to update this services entry with the right classname of the JSR-196 CallbackHandler to be used on that container.
   

    2.  The place where the Metro Security-Tube needs to finally place the JSR-196 javax.security.auth.Subject object such that it gets used for Authorization decisions on the Container is again not defined in any standard. For example on GlassFish this subject is to be set into a  GlassFish specific SecurityContext object .  For other containers it maybe something else. So there is a META-INF/services entry inside wsit-196-hook.jar named com.sun.xml.ws.security.spi.SecurityContext.  The default value of this entry points to an implementation of the following SecurityContext interface that does the correct thing for GlassFish V2.

package com.sun.xml.ws.security.spi;
import javax.security.auth.Subject;

/**
 * Provides
 * 1. a way to obtain credentials from an
 * encompassing runtime into the Metro Pipeline runtime
 * 2. API to set the credentials after authentication as understood
 * by the container
 *
 */
public interface SecurityContext {
    /**
     * @return the subject containing credentials from the encompassing runtime, null if none is available
     */
    public Subject getSubject();
   
    /**
     * Set the subject after message authentication as understood by the container
     * @param subject
     */
    public void setSubject(Subject subject);
}

     3. Another thing which is again handled by appropriately defining  the META-INF/services entry for the above defined SecurityContext is the fact that when there are credentials established by the encompassing runtime under which the SOAP layer webservice interaction is happening  (for example an authetication at the transport layer or an SSO Token) then one needs to make the SecurityContext established by the encompassing runtime available to the SOAP layer interaction. Again there is no standard that defines how to obtain this information from the encompassing runtime and hence the mechanism differs from Container to Container (For example, in GlassFish it is again the same SecurityContext object that needs to be retrieved).

  As stated above the JSR-196 path is not enabled by default for Non-GlassFish containers, and i mentioned backward-compatibility as the reason. There is some work involved to package the Non-196 path as a JSR-196 Authentication module and once that is done then pluggability option 3 above can be made the default in metro. We may do this in the near future.