Skip to main content

WSIT Security Configuration  Demystified

Last Updated :  01 November 2007


WSIT (or Project Tango ) stands for the next generation WebServices  Interoperability Technology from Sun.  The Programming model for WebServices with WSIT is the same old  JAXWS Programming model.  If you know how to write a JAXWS WebService then you are all set to use WSIT. So what does WSIT Provide ?.  WSIT allows a developer to enable various  QOS (quality of service)  features for a JAXWS Webservice.  The mechanism for achieveing this is to supply configuration.

WSIT is actually a SubProject of  Project GlassFish (Sun's  OpenSource Application Server) and all the WSIT Technologies can be directly accessed from GlassFish (no download of additional jars is required).  WSIT builds are  periodically integrated into GlassFish.

WSIT implements the WS-* specifications and most notably WS-Policy  that provides for an interoperable way to configure the QOS attributes of the WebService.  The Security Requirements of a  WebService are specified using WS-Policy assertions defined by WS-SecurityPolicy (a domain specific Binding of  WS-Policy).

While the developer can know more about WS-SecurityPolicy from : http://www.oasis-open.org/committees/download.php/15979/oasis-wssx-ws-securitypolicy-1.0.pdf,  Briefly WS-SecurityPolicy defines assertions that can be used to describe the security capabilities and requirement of  the WebService. The capabilities and requirements can be published as part of the WSDL. The capabilities and requirements pertain primarily to Message Layer Security and also to Transport Security.  A security requirement specified in the WSDL of a service forces a communicating party trying to acess the service to secure the message in a certain way. Some of the things that a requirement can state are, 

1.  Use of  a Certificate and Private Key pair or a valid Username/Password  in order to authenticate to the service etc.
2. The type of  Key and Key Sizes  and Algorithms that need to be used etc.

The assertion(s) in  WS-SecurityPolicy which relate to Key's, Certificates, Username/Password etc  are abstract and need additional configuration (which is out of the scope of the WS-SecurityPolicy specification) to enable an implementation to acquire the keys from the underlying Security infrastructure. This article  is all about  explaining the details of  this additional configuration  (which is out of scope of WS-SecurityPolicy specification).

There has been some questions on the WSIT forums  about what are validators, which callbacks are to be specified, and whether or not a keystore needs to be configured for a particular Security Mechanism. This article intends to clarify some of these questions... Specifically this article would deal with the following WSIT Security Configuration elements :

1.  Validator(s)
2.  RealmAuthenticator (for username-password validation)
3.  CallbackHandler(s)
4.  Keystore and Truststore configuration
5.  Certstore Configuration
6.  Security Configuration for Mechanisms that use an "STS"
7.  Summary of  WSIT Security Configuration on GlassFish

Readers of this article are advised to test out any of the features mentioned in this article by downloading the latest WSIT build from the WSIT Trunk.  Feedback is solicited from the readers on any Bugs or Issues found.

Security Mechanism(s) in WSIT

While a developer can very well specify the detailed security capabilities and requirements of  a WebService using WS-SecurityPolicy, writing WS-SecurityPolicy assertion(s) is a very tedious task. Secondly configuring Security for a Webservice becomes an up-hill task for the developer when one has to learn the Syntax and Semantics of  WS-SecurityPolicy. 

As stated earlier the goal of  WSIT is to make sure that the Programming Model is still JAX-WS and that any QOS goals are achieved by simplified Configuration dialogs Aided by a Development Environment such as NetBeans.

Based on the above, WSIT Security in NetBeans defines a set of  11 Security Mechanisms.  Each of the Security Mechanisms were defined to cover a specific form of Authentication of the client with the Server.  Depending on the requirements of the application and the support provided by the Implementing Infrastructure, developers are expected to just select one of the Mechanisms for securing their Application.  The SecurityPolicy corresponding to the Mechanism is then automatically generated into the Service WSDL by the NetBeans WSIT Plugin.  As stated above there is a need to augment the abstract Token assertions in WS-SecurityPolicy with some additional configuration the details of which is the topic of this article.

Note that the list of Mechanisms currently supported is expected to grow in future (as WSIT Security continues to support more and more Tokens Types and Specifications) .  In future there would also be a Generic Security Mechanism supported by the NetBeans WSIT Module. The Generic Security Mechanism would have its details composable  by selecting various options in the  NetBeans WSIT User-Interface.

We will not be discussing the SecurityMechanisms in detail in this article. Please refer to the WSIT Tutorial Security Chapter for more details on this.

How is WSIT Security Configuration Different or Similar to XWSS 2.0 ?

The XWSS 2.0 SecurityConfiguration mainly consisted of specifying a  SecurityEnvironmentHandler (which is basically a CallbackHandler implementing javax.security.auth.callback.CallbackHandler interface). The SecurityEnvironmentHandler was expected to handle  all or some of  the XWSS defined Callbacks (present in com.sun.xml.wss.impl.callback package) as required by the specific scenario defined by the security policy (under <JAXRPCSecurityConfiguration/>).

While this model of  configuration could be have been carried over into WSIT, there were two things that had to be considered.

1.  Developing a SecurityEnvironmentHandler is difficult  and complex task given all the Callbacks defined in XWSS 2.0 and we wanted to simplify the Security Configuration in WSIT. The Callbacks were also not standard (not based on Standard J2SE or any other JSR) and so there was a desire to move WSIT Security in the direction of an Emerging Standard (JSR 196: JavaTM Authentication Service Provider Interface for Containers). Some of the Callbacks supported in XWSS could simply have been handled by a Default Implementation provided with the product and/or Container. Some examples are TimestampValidation, CertificateValidation etc. In additional not all Callbacks needed to be handled by all Applications (SecurityEvironmentHandler(s)) and finding out which callbacks are really required by an Application was a difficult task.

2.  XWSS 2.0 did not have User-Interface support and so in WSIT we wanted  NetBeans to provide  First Class Support for WSIT Security. So when we talk about  User-Interface the simplest  thing to do was to just ask the developer to supply small fragements  of code (in the form of stripped down CallbackHandler(s) that handle a single standard Callback, eg. javax.security.auth.callback.NameCallback to retrieve a Username) to perform a single task.

So while JSR 196 is still a  Proposed-Final Draft, WSIT Security Configuration had to take a Middle Ground with a Mix of  mechanism(s) from XWSS 2.0 and from JSR 196 (Supported Only in the Context of the GlassFish Application Server).

So one can imagine that the WSIT Security Runtime has a Default CallbackHandler (SecurityEnvironmentHandler in XWSS 2.0 sense) which handles most of the callbacks made by WSIT Security at Runtime. However there are some configuration points where developer supplied  Callbacks and Validators are invoked to perform Specific Tasks such as Username/Password retrieval etc.  Where Applicable (especially in the Context of GlassFish Application Server) the JSR 196 callbacks and Default CallbackHandler (defined by GlassFish Container) are also given preference causing WSIT Security to ignore developer supplied Callback(s) and Validator(s). The end result  of this is that WSIT Security developers  who are using GlassFish need not bother about a lot of  things such as  validators and callbackhandlers. Configuring Security for a WSIT application deployed on GlassFish gets simplified.

The rest of this article describes the WSIT Security Configuration in detail and we hope the reader would be able to understand the present and future direction of  WSIT Security Configuration.

Service Security Configuration

The  WSIT Configuration Tab(panel) for a WebService  would appear when one right clicks on the WebService Node inside NetBeans and would appear as shown in the Snapshot below :


wsit server side configuration



As you can see from the snapshot above, the  Validators button indicates optional.  The Keystore and Truststore buttons  not indicated as optional need to used to configure the keystore and truststore depending on the Security Mechanism selected above.  For example the Keystore and Truststore need not be configured for a  Plain Transport Security Mechanism.  Or if you intend to use a Username/Password over SSL, then again you do not require the Keystore and Truststore.

NOTE: It would have been best if the UI would have asked for exactly those things that are needed for a Particular Security Mechanism selected, but this is not the case right now. A Future revision of the  NetBeans WSIT Plugin might have this kind of more intelligent UI.

NOTE:  You would almost never need to identify an Alias when you do the Truststore configuration of a service. Because the certifcate of the client or an  identifier would always be present in the incoming request to the Service. This also allows the Service to  serve multiple clients as long  as it can trust the  certificate of the client.

What are Validator(s) ?

Validator(s) like CallbackHandler(s) are developer supplied code that is invoked by the WSIT Security runtime to validate a particular aspect of the Incoming SOAP Message. For example the developer can supply a PasswordValidator that validates the  username/password in the incoming message.  Developer's can also supply a Certificate Validator, or a Validator for Timestamp(s) in the incoming messages.  A Validator implementation would generally implement an interface defined in the WSIT Security API.

NOTE: The WSIT security implementation has default implementations for most of these validators and hence validators are marked as optional in the NetBeans UI.

So When are the Validator(s) Used by WSIT Runtime ?

The Validators are present for following reasons

1.   When a developer writes a Plain JAXWS WebService (one that has a sun-jaxws.xml)  as opposed to a  JSR 109 Compliant  JAVA EE5 WebService, then the integration of such a webservice with the JAVA EE Container is not well defined. And such an application would really run  by just making use of the JAXWS runtime of the Container. In this case since the container can be any of  GlassFish or TOMCAT or someother server, the  WSIT Security Runtime would make use of  Validator(s) if any are configured to do things such as Password Validation, Certificate Validation, Timestamp Validation etc on incoming SOAP Messages.

2.  When the application developed is a  J2SE WebService Client then again the Validator(s) are invoked on the client side.

3.  They are present for Historical Reasons : XWSS 2.0  had the notion of  Validators as pluggable user code inside the  SecurityEnvironmentHandler (CallbackHandler) and so we thought it would be a familiar notion for XWSS 3.0 (WSIT Security) users to begin with.

Configuring a Validator can be some work, in terms of  writing an extra class that extends a proprietary WSIT/XWSS API Interface, packaging the class in the WAR and specifying the classname in the WSIT Configuration UI Panel. So to promote ease of  use, the WSIT runtime has reasonable defaults for all Validators and it would use them.  So one really does not need to configure a validator unless there is a need to override the default implementation.

Of particular interest to developer(s) would be the default Username/Password Validator. The default would work only in case of  GlassFish and TOMCAT containers.
  •  In case of  GlassFish the default Password validator would validate the  incoming  Username/Password against the configured realm of the  Application (WebService).
  •  In case of  TOMCAT the default password validator would validate the incoming Username/Password against the tomcat-users.xml file.
NOTE:  Tomcat also has the notion of  Realm(s), but making use of the Realm Authentication interfaces would make WSIT Security to depend on TOMCAT specific interfaces which we did not want to do.

Instead, RealmAuthentication on Tomcat can be performed by the developers either inside the PasswordValidator or more preferably they can make use of  the RealmAuthenticationAdapter Interface.   This new interface which did not exist in  XWSS 2.0 has been introduced in WSIT Security (XWSS 3.0)  to overcome a limitation of the PasswordValidator interface.  The RealmAuthentication typically updates a javax.security.auth.Subject object with the client principals, but the PasswordValidator.validate() interface does not supply the Subject.  The updation of the Subject with Principals can be container specific and hence there was a need for this new interface.

Note:  There is no support in  NetBeans WSIT Plugin Today for configuring a RealmAuthenticationAdapter (it may be added in a future release).

What are the Steps for Configuring a RealmAuthenticationAdapter  ?

Most Containers support Realms and RealmAuthentication, so when you are using WSIT on GlassFish WSIT Security automatically authenticates the user against the configured Realm. This is important since we want to minimize the proliferation of pluggable authentication abstractions, and to standardize the use of the ones that exist, in addition RealmAuthentication allows the Container to set its representation of the Principal into the Subject (contrast this with the case of PasswordValidator above, where WSIT would set the Principal in its own proprietary way).

So for RealmAuthentication on Containers other than GlassFish we have this SPI called com.sun.xml.wss.RealmAuthenticationAdapter.

It has an abstract method :

public abstract boolean authenticate(Subject callerSubject, String username, String password) throws XWSSecurityException;

So what does the developer need to do :

1. Implement your own RealmAuthentication class that extends the com.sun.xml.wss.RealmAuthenticationAdapter.
2. Package the implementation class inside your WAR File
3. Create a META-INF/services entry (inside the WAR) for your RealmAuthenticator. The services file should be named as : com.sun.xml.xwss.RealmAuthenticator and the contents of the file should be the fully qualified package name of your RealmAuthenticator class.

Since the clientSubject is passed as an argument, the Autheticator could also update the Subject with the Containers representation of the Principal.

When are Validator(s) Ignored by WSIT Runtime ?

When the  application developed is a JAVA EE 5 compliant  JSR 109 WebService and the Container is GlassFish in this case the Validator(s) are completely ignored even if they are specified inside the NetBeans WSIT Plugin UI.

NOTE:  We have a WSIT Issue filed (https://wsit.dev.java.net/issues/show_bug.cgi?id=504), fixing which might result in Validator(s) to be ignored in all cases (be it a plain JAXWS WebService or a JSR 109 Compliant WebService) for applications running on GlassFish Container.

So the question that may come to mind is how then would someone be able to configure custom code to handle validations. The answer to it is that GlassFish now supports JSR 196 (which is now in Pre Final Draft Stage) and it defines standard Callbacks that an Application needs to handle. So  developers would be able to configure a complete CallbackHandler that only handles the standard  JSR 196 defined callbacks and forget about all other configuration that they currently see in the  NetBeans WSIT Plugin today.  This is important since we want to minimize the proliferation of pluggable authentication abstractions, and to standardize the use of the ones that exist.

For Container(s) other than GlassFish, the  WSIT Security runtime will continue to call the Validator(s)  for some time. Eventually the Goal is to have the developers configure  a CallbackHandler which handles a  Standard  set of  JSR defined Callback(s) and not require any of the proprietary callbacks and validators to be specified by WSIT Security users (irrespective of what the container is).

Abstract Schema for specifying Validator(s) in WSIT Configuration

So while the use of validators is discouraged, for the sake of completeness, the listing below describes  the set of all validator's that can be defined and the interfaces they need to implement (the description below is in the form of an abstract schema) .  Validators can be specified on both the client and server side however as one may note the  usernameValidator is only applicable on the server side. 

Note: In the Abstract schema notation  a  "?" character at the end indicates the attribute/element is optional.
<sc:ValidatorConfiguration
maxClockSkew="{
The assumed maximum skew (milliseconds) between the local times of any two systems,
runtime defaults used when not specified}" ?

timestampFreshnessLimit="{The period (milliseconds) for which a Timestamp is considered
fresh, runtime defaults used when not specified }?

maxNonceAge="{The length of time (milliseconds) a previously received Nonce value in a
UsernameToken will be stored, runtime defaults used when not specified}"?
revocationEnabled="{If this flag is true, the default certificate revocation checking mechanism
of the underlying PKIX service provider will be used. If this flag is false,
the default revocation checking mechanism will be disabled (not used).}"?
>
    <sc:Validator name= "usernameValidator"  classname={class name of a usernameToken Validator,
    should implement com.sun.xml.wss.impl.callback.PasswordValidationCallback.PasswordValidator,
    a sample validator available here }/> 
    <sc:Validator  name="timestampValidator" classname ={class name of a Timestamp Validator,
    should implement com.sun.xml.wss.impl.callback.TimestampValidationCallback.TimestampValidator,
    a default Timestamp validator from XWSS runtime used when not supplied} />?

    <sc:Validator  name="certificateValidator" classname ={class name of a certificate Validator,
    should implement
    com.sun.xml.wss.impl.callback.CertificateValidationCallback.CertificateValidator,
    default Certificate validator from XWSS runtime used when not supplied} /> ?

    <sc:Validator name="samlAssertionValidator" classname = {class name of a SAML Assertion
    Validator, should implement com.sun.xml.wss.impl.callback.SAMLAssertionValidator,
    Partial validation (in the form of verifying enveloped signature) occurs on SAML
    Assertion within  the WSIT/XWSS 3.0 Runtime even if the validator is not specified} /> ?
</sc:ValidatorConfiguration>?


Note that a CertificateValidator is only called when the Actual Certificate of the requester is included in the Request/Response Message  from the other party. This is because in cases where the request/response message only has a reference to the Certificate (as per OASIS WSS specifications) rather than the Certificate itself,  it means that the receiving system already trusts the requester Certificate and so it has stored the server certificate in it's local TrustStore/CertStore.

So while we discourage the use of  usernameValidator, timestampValidator, certificateValidator and samlAssertionValidator and also mention that they may not be called in certain scenarios, you may note that there  are some attributes on the ValidatorConfiguration element and  WSIT will continue to support them.

The first  two attributes,  maxClockSkew and  timestampFreshnessLimit have been described more elaborately with an example in the following blog from ashutosh :  http://blogs.sun.com/ashutosh/entry/setting_custom_values_for_timestamp

The thrid attribute called  maxNonceAge is not yet supported and has been there for future use when WSIT Security upgrades to the latest WS-SecurityPolicy Specification.

The last attribute revocationEnabled  controls the use of  default revocation checking mechanism of the underlying provider when we are doing CertificateValidation. 

 NOTE:  If the application is a  Non-109 App and the user has configured the CertificateValidator of his own then this flag has no effect on the validation.

This setting reflects the most common strategy for checking revocation, since each service provider must support revocation checking to be PKIX compliant. Sophisticated applications should set this flag to false when it is not practical to use a PKIX service provider's default revocation checking mechanism or when an alternative revocation checking mechanism is to be substituted. (See Also : http://java.sun.com/j2se/1.4.2/docs/api/java/security/cert/PKIXParameters.html#setRevocationEnabled(boolean))

Also when the  Certificates that are to be validated contain CRL Distribution Points that point to a URL for downloading the CRLs via LDAP or HTTP.  Then  you need to set the system property com.sun.security.enableCRLDP to true.  In a future release this may be set to true by default in JDK.

NOTE:  When NetBeans is used the ValidatorConfiguration and it's sub-elements are actually generated automatically by the NetBeans WSIT Plugin. But the developer can also write the validator configuration manually. Some of the attributes that appear on ValidatorConfiguration element are not supported by the NetBeans UI currently.  Also one can write an empty ValidatorConfiguration element with just the attributes and not specify any of the Validator sub-elements.

<sc:ValidatorConfiguration maxClockSkew="60000" />

The Validator Invocation Matrix


Type of  WebService VS. Validator Invocation
TimestampValidator
PasswordValidator
SAMLValidator
CertificateValidator
GlassFish  (JAVA EE 109 WebService/Client,  Plain JAX-WS WebService/Client)
Not Called
Not Called
Not Called
Not Called
Non-GlassFish Container (TOMCAT)
Called
Called (applicable only for a WebService and not a WebService Client)
Called(applicable only for a WebService and not a WebService Client) Called
J2SE Client
Called
Not Applicable
Not Applicable
Called


NOTE:  In cases where the table indicates "Not Called"   it actually implies that there are defaults provided by the container and they cannot be overriden. However the ValidatorConfiguration Element provides attributes to control the default implementation in certain ways. For example one can control the clock-skew to be used by the default timestamp validator.

As mentioned earlier Validator(s) are completely optional and if specified  they would called whenever applicable.

What Are CallbackHandler(s) ?

CallbackHandler(s) are client side entities. A CallbackHandler is a class that implements a javax.security.auth.callback.CallbackHandler interface. The  WSIT security runtime makes use of  CallbackHandler(s) that handle the following callbacks  :

1. javax.security.auth.callback.NameCallback :  A CallbackHandler handling the NameCallback is required when the Security Mechanism requires the client to supply a Username and a Password. The NameCallback is used to collect the Username. The CallbackHandler invocation as we can understand is only meaningful when the client is a Plain J2SE WebService Client.

2. javax.security.auth.callback.PasswordCallback :  A CallbackHandler handling the PasswordCallback is required when the Security Mechanism requires the client to supply a Username and a Password. The PasswordCallback is used to collect the Password. The CallbackHandler invocation as we can understand is only meaningful when the client is a Plain J2SE WebService Client.
3. com.sun.xml.wss.impl.callback.SAMLCallback : A CallbackHandler handling the SAMLCallback is required when the Security Mechanism requires the client to supply a  SAMLAssertion (either a Sender-Vouches or a Holder-of-Key assertion as per the SAML Token Profile 1.1).

The CallbackHandler configuration element  in WSIT client side security configuration  has the following abstract schema. The configuration can either be written by hand or can be produced by specifying the required CallbackHandler class names inside the NetBeans  WSITConfiguration on the client side.

Note: In the Abstract schema notation  a  "?" character at the end indicates the attribute/element is optional.

<!-- required only on the client side  when Username/Password or a SAML Token is involved in the Security Mechanism -->
<sc:CallbackHandlerConfiguration
        timestampTimeout="{Timeout value in Second(s) : This value is used to compute the Expiry time of the WSU:Timestamp being sent in the message, value specified should be greater than zero}" ?
 >
       <sc:CallbackHandler  name="usernameHandler" classname="{a callbackhandler classname that
        handles javax.security.auth.callback.NameCallback}"
        default="{the default username value as a string, to be provided incase classname is
        not provided}"
       />
       <sc:CallbackHandler  name="passwordHandler"  classname="{a callbackhandler  classname that
        handles javax.security.auth.callback.PasswordCallback}"
        default="{the default password value as a string, to be provided incase classname
        is not provided}"
       />
       <sc:CallbackHandler  name="samlHandler"  classname="{a callbackhandler  classname that
        handles com.sun.xml.wss.impl.callback.SAMLCallback}"
       />
</sc:CallbackHandlerConfiguration>?

Note : We have not marked the individual usernameHandler, passwordHandler and samlHandler elements with a trailing "?". This does not mean they are always required, but that depending on the SecurityPolicy of the Service they may or may not be  REQUIRED.

Note : While we mention that the CallbackHandler is a client side entity, the CallbackHandlerConfiguration element with the timestampTimeout attribute on it can be specified on the server side as well, to control the expiry time. Similarly the configuration of  jmacCallbackHandler and xwssCallbackHandler under CallbackHandlerConfiguration is applicable on both the client and server side.

One can specify just the empty CallbackHandlerConfiguration with a Timestmap Timeout of 15 seconds as follows on the server and client side configuration respectively :

<sc:CallbackHandlerConfiguration  xmlns:sc="http://schemas.sun.com/2006/03/wss/server"
wspp:visibility="private" timestampTimeout="15"/>
OR
<sc:CallbackHandlerConfiguration  xmlns:sc="http://schemas.sun.com/2006/03/wss/client"
wspp:visibility="private" timestampTimeout="15"/>



The WSIT Client Side Security Configuration in NetBeans looks as shown below :

client security configuration




Note the DropBox named "Authentication Credentials"  shows Dynamic. If the selection was "static" instead then the  configuration accepted would look as follows :

static client conf

In a static configuration one can specify the Default username and password  instead of supplying a  CallbackHandler as described in the Dynamic case above. This option is mostly for quick and dirty configuration. Note that  there is risk of  exposing the Password in this case since the plain text password is stored in the WSIT client side configuration (in a file imported by wsit-client.xml).

However when used in the context of  GlassFish this static option has a special utility for Embedded WebService Clients (Example: A servlet  or an EJB acting as a WebService Client). The Password in these cases can be specified as a PlaceHolder by making the password string start with a "$" character. The WSIT security runtime would then make a  SecretKeyCallback passing the password placeholder (minus the "$" character). The actual password is then obtained as a result of the  SecretKeyCallback.    I will describe a complete sample on how this option can be used in GlassFish in a later Article/Blog (stay tuned).

The CallbackHandler Invocation Matrix

As stated above,  CallbackHandler configuration is only  relevant for a WebServiceClient  and not for a  WebService.
NOTE: There is an exception to the above statement as explained in the last section.

Type of  WebService VS. CallbackHandler  Invocation
usernameHandler
passwordHandler
samlHandler
GlassFish  (JAVA EE 109 WebService Client,  Plain JAX-WS WebService Client,  JAVA EE Application-Client-Container Client)
Not Called
Not Called
Called
Non-GlassFish Container (TOMCAT)
Called
Called
Called
J2SE Client
Called
Called
Called

The only exception noted in RED color is that although the usernameHandler and passwordHandler attributes are ignored on GlassFish, the samlHandler if specified is honored and used by WSIT Security Runtime on GlassFish Container. This is because Traditionally XWSS 2.0 had made use of a Callback to inject a SAML assertion into the XWSS runtime (when the Scenario is not explicitly defined as a WS-Trust based scenario). WSIT Security supports this notion in addition to supporting the WS-Trust model, however JSR 196 has no notion of Callbacks to inject a SAML Assertion. So WSIT security takes a Middle Ground here by invoking any configured samlHandler even if the environment is GlassFish just to support the Security Mechanisms that do not explicitly call for the use of WS-Trust.

The NetBeans Snapshot below shows the SAML Mechanisms that make use of the samlHandler :

saml mechanisms


In the Sanpshot above the Mechanisms that being with the Keyword  SAML are the ones that would require/user the "samlHandler"  specified in the CallbackHandlerConfiguration. On the other hand the Mechanisms that begin with the  Keyword  STS (Security Token Service) indicate  the explicit use of  WS-Trust Protocols.

How are Username Password Gathered by WSIT Runtime in GlassFish ?

When WSIT is used on GlassFish,  the default GlassFish callbackhandler (which is based on JSR 196 defined Callbacks)  is used and this CallbackHandler would handle the JSR 196 defined Namecallback and Password Callbacks.  This is the reason why the  usernameHandler and passwordHandler configured under the CallbackHandlerConfiguration are not used under GlassFish.  This applies for GlassFish Application Client(s)  (i.e ACC based Clients) Only. If the WebService Client is embedded inside a Servlet or an EJB then no callbackhandler can acutally be invoked and so if the default values are configured as described above they would be used else a Null value is returned for username/password.

What is the algorithm used by WSIT runtime to Gather the  Username and Password ?

The WSIT Runtime looks for the username and password from the following sources in the order listed below :
1.  If the default attribute  under  usernameHandler/passwordHandler is set then the username/password is picked up from the value of the default attribute
2.  If the default attribute is absent but the developer has set  BindingProvider.USERNAME_PROPERTY and BindingProvider.PASSWORD_PROPERTY on the RequestContext() of the  Client Stub (BindingProvider) then the Username and Password are picked up from the value of those properties
3.  If the USERNAME_PROPERTY and PASSWORD_PROPERTY is not set then the callbackHandler class configured under usernameHandler/passwordHandler will be invoked to retrieve the username and password respectively. OfCourse as described above these callbackHandler(s) are ignored when running on GlassFish. So in case of a GlassFish Application Client (a.k.a ACC Client) the GlassFish default CallbackHandler would make a  NameCallback and PasswordCallback respectively to gather the username and password. And for Servlet and EJB Clients on GlassFish a  Null value is returned since No Username/Password Callbacks can be made in case of  such clients.
4.  If none of the above 3 mechanisms are configured  then an Exception is Thrown by the WSIT Security Runtime (stating that a required usernameHandler/passwordHandler is missing)

Can I Specify My Own Overiding CallbackHandler  for Handling Callbacks, Keystores and Validators ?

So while we have described the presence of  Default CallbackHandler code with WSIT /GlassFish-Container to handle the Callbacks and Validations, there is always that special case that developers find themselves in and in such situations they desire to have their own Self  defined CallbackHandler to be used (on the lines of the SecurityEnvironmentHandler in XWSS 2.0).  This gives the developers complete control over where to retrieve the Keys,  Username and password etc.

WSIT security allows developers to do this. Specifically one can do the following

 1. Override the WSIT  DefaultCallbackHandler  which is used for Non-GlassFish Containers.

      On the Client Side :

      <sc:CallbackHandlerConfiguration xmlns:sc="http://schemas.sun.com/2006/03/wss/client" >
       <sc:CallbackHandler  name="xwssCallbackHandler"  classname="fully qualified classname" />
   </sc:CallbackHandlerConfiguration>

      On the Server Side :

      <sc:CallbackHandlerConfiguration xmlns:sc="http://schemas.sun.com/2006/03/wss/server" >
       <sc:CallbackHandler  name="xwssCallbackHandler"  classname="fully qualified classname" />
   </sc:CallbackHandlerConfiguration>


Note:  When one overrides the WSIT DefaultCallbackHandler (option 1 above) none of the other configuration elements described in this article/supported by the NetBeans WSIT Plugin will be relevant anymore. This is because the developer has chosen to handle all the Callbacks and Validations on his/her own.  Infact overriding the WSIT DefaultCallbackHandler is not supported through NetBeans today and the developer would instead have to manually copy the above configuration into his client and server side configuration files respectively.
   
 2. Override the  GlassFish DefaultCallbackHandler that handles JSR 196 defined Callbacks when running on GlassFish.

      On the Client Side :

      <sc:CallbackHandlerConfiguration xmlns:sc="http://schemas.sun.com/2006/03/wss/client" >
       <sc:CallbackHandler  name="jmacCallbackHandler"  classname="fully qualified classname" />
   </sc:CallbackHandlerConfiguration>

      On the Server Side :

      <sc:CallbackHandlerConfiguration xmlns:sc="http://schemas.sun.com/2006/03/wss/server" >
       <sc:CallbackHandler  name="jmacCallbackHandler"  classname="fully qualified classname" />
   </sc:CallbackHandlerConfiguration>



Note: When one overrides the GlassFish Default CallbackHandler, there are still certain things which are handled by Default WSIT code. In other words the JSR 196 defined callbacks are only a SubSet of the total set of  Callbacks made by the WSIT Runtime. In such cases the configuration(s) that are mutually exclusive will continue to be relevant even if the developer has overridden the default  GlassFish CallbackHandler. The configurations(s) in NetBeans WSIT Plugin that overlap in functionality with Callbacks defined in JSR 196 would be ignored.  Overriding the GlassFish DefaultCallbackHandler is not supported through NetBeans today and the developer would instead have to manually copy the above configuration into his client and server side configuration files respectively.

So what is a jmacCallbackHandler ?

A jmacCallbackHandler is a callbackhandler that handles ther callbacks defined in the JSR 196 specification.

Which  WSIT Configurations are Ignored when one specifies a "jmacCallbackHandler" ?

  1. The  Client Side CallbackHandler configuration in WSIT (with the exception of  samlHandler and timestampTimeout attribute) are ignored
  2.  The entire Validator Configuration on both client and server (with the exception of  attributes defined on the ValidatorConfiguration element) are ignored.
  3.  All but alias attribute in the  WSIT Keystore configuration are ignored by a jmacCallbackHandler. The Alias information is passed onto the user supplied jmacCallbackHandler.
  4.  All but alias (peeralias) attribute in the WSIT Truststore configuration are ignored by a jmacCallbackHandler.
  5.  The callbackHandler in the CertStore configuration element is ignored by the jmacCallbackHandler because JSR 196 defines its own CertStoreCallback which the developer supplied CallbackHandler is expected to handle. The certSelector supplied is still used with the developer supplies jmacCallbackHandler.

Note:  As is obvious, overriding the GlassFish Default CallbackHandler is applicable only for WebService and WebService Client applications  running under GlassFish Container. This description is not applicable for a J2SE client for example.

Note :  the phrase JMAC stands for Java Message Authentication SPI for Container(s).

Note :  As of publishing this article support for overriding the GlassFish default callbackhandler  via the  "jmacCallbackHandler" attribute is still being implemented and should be  has been implemented and will be available on the WSIT Trunk in a week's time earliest by May 11 2007.

Keystore and Truststore Configuration in WSIT

As mentioned in the begining of this article the WSIT security rutime has a DefaultCallbackHandler which can be configured to make use of developer supplied code/configuration to perform certain tasks (such as locating keys, certificates etc). The Keystore and  Truststore are one such REQUIRED Configuration elements which are  to be specified for any WSIT Security Mechanism that makes use of  X.509 Certificates.

The configuration for Keystore and Truststore have the following abstract schema :


<sc:Keystore
   location={absolute path to keystore file}
   type={type of the keystore (default is JKS)}?
   storepass={the password of the keystore as a string, OR a fully qualified classname of a
   class implementing javax.security.auth.callback.CallbackHandler and that handles
   the javax.security.auth.callback.PasswordCallback}
   alias={the certificate alias from the  keystore to be used for Signatures}
   aliasSelector={the fully qualified classname of a class implementing
   com.sun.xml.wss.AliasSelector interface}?
   keypass={the password for the key, OR 
a fully qualified classname of a
   class implementing javax.security.auth.callback.CallbackHandler and that
   handles the javax.security.auth.callback.PasswordCallback
}?
/>

<sc:Truststore
      location={absolute path to truststore file}
      type={type of the keystore (default is JKS)}? 
      storepass={the password of the truststore as a string,
OR a fully qualified classname of a
      class implementing javax.security.auth.callback.CallbackHandler and that handles
      the javax.security.auth.callback.PasswordCallback
}
      peeralias={the alias of the peer entity involved in secure communication,
      not required if no encryption is involved}?
      certSelector={
the fully qualified classname of a class
      implementing java.security.cert.CertSelector interface}?

/>

NOTE:  in certain scenarios Mutual Certificates are not required, especially the first Security Mechanism in WSIT makes use of  Symmetric Keys and does not require the communicating Client Application to identify it's Certificate and Private-Key. So depending the Application one or both of  Keystore and Truststore will be REQUIRED. For example the truststore peeralias of a WebService is almost never required because the WebService would be contacted by multiple clients during its lifetime and hence one cannot statically configure the peeralias (instead the client ceritificate is learnt by the Service dynamically when the incoming request arrives).

When the keystore "alias" attribute  is specified it takes preference over the "aliasSelector".  An  "aliasSelector" allows the developer to select the  "alias" to use for identifying the self-certificate and privatekey at runtime.

 When a truststore "peeralias" attribute is specified it takes preference over the "certSelector".  A  "certSelector" allows the developer to select the Certificate of the Peer Entity dynamically at runtime.

NOTE:  There is no NetBeans UI support for aliasSelector and certSelector today. This will be incorporated in a future revision. One can however manually edit the WSIT configuration files to specify this information.

Issues with specifying Keystore Location and Password in Keystore/Truststore assertion(s)

The Keystore and Truststore assertions were introduced in WSIT to provide a way to configure the DefaultCallbackHandler in WSIT. However asking developer(s) to specify the keystore location as an absolute URL has some undesirable effects. For example when the Application archive has to be taken to another system the URL will have to reconfigured using NetBeans UI or manually.   The URL approach was mainly provided to allow developers to quickly configure security without having to write any extra code that would need to be packaged with their application.

Another issue is that of specifying the password of the  Keystore/Truststore and the Key Password (if different from the Keystore password).  This mechanism was again introduced for quick and dirty prototyping where developer does not need to write extra code for configuring the application security. The  downside of this is that the password appears in the WSIT configuration files in Plain Text (which can be a risk).  One alternative that has been provided is for the developer to configure a fully qualified classname of a  CallbackHandler class that handles the javax.security.auth.callback.PasswordCallback.
 
NOTE:  When using WSIT on GlassFish (the DefaultCallbackHandler on GlassFish is used and it  is based on the JSR 196 model),  the need to specify the Keystore Location and Keystore Password and  Keystore Type is eliminated. The Only thing one ever needs to specify in case of  GlassFish is the alias information.  Note that this feature has been enabled recently and hence you should pick up the latest WSIT builds to use this feature. 
So the Keystore assertion for an Application deployed on GlassFish could look as follows :

<sc:Keystore alias="my-certificate" />
  

Since the Keystore location and type are not specified in the assertion they can actually point to any thing not necessarily a JKS keystore. In case of  GlassFish the key corresponding to the alias "my-certificate" could as well be located in the GlassFish NSS Keystores and the runtime would be able to find it.

For more information on  Key Management in GlassFish please look at the following technical article :
http://developers.sun.com/appserver/reference/techart/keymgmt.html


The Keystore Type specification can still be used in case of  Non-GlassFish environments to point to Non JKS keystores.

What Runtime Information is avaliable to an  aliasSelector or a certSelector ?

The classes implementing  CertSelector interface can have a constructor which takes a Map as an argument.  WSIT Security runtime would instantiate the class passing it a  Map of Runtime Properties. And the select Method of AliasSelector is passed a Map of Runtime Properties.  The properties inside the Map would be what JAX-WS exposes such as PROPERTY_END_POINT etc.

Properties set by the developer on the BindingProvider RequestContext will be available inside the MAP, and we consider the ability to access the BindingProvider RequestContext properties as very useful. Developers can then set some properties from their client code and then use those properties inside the AliasSelector or CertSelector to dynamically select the  Alias/Certificate.

The API Javadocs for  WSIT Security (a.k.a XWSS 3.0),  including the newly defined AliasSelector can be downloaded from the XWSS java.net page. Download the file xwss-3.0.zip from the link :  https://xwss.dev.java.net/servlets/ProjectDocumentList?folderID=6645&expandFolder=6645&folderID=5501
and look for xwss-api.zip inside.  Unzip xwss-api.zip and look for the file api/index.html

CertStore Configuration in  WSIT

In the previous section we described  Keystore and Truststore configuration. So far in WSIT the Truststore has been used as a place where both Trusted CA certificates as  well  as   trusted other party certificates are to be stored.   While this mechanism works it has it's limitation(s). Firstly in a real world environment certificates of  other parties might  actually be located in an LDAP repository.  So asking developer's to import those certificates from an LDAP repository to  a JKS Truststore is both tedious and undesirable.

 So Secure WSIT  applications can now provide a CertStore configuration as part of their security configuration assertions (See Also : http://java.sun.com/j2se/1.4.2/docs/api/java/security/cert/CertStore.html).

Unlike a KeyStore, which provides access to a cache of private keys and trusted certificates, a CertStore is designed to provide access to a potentially vast repository of untrusted certificates and CRLs. For example, an LDAP implementation of CertStore provides access to certificates and CRLs stored in one or more directories using the LDAP protocol.

        The configuration that a developer needs to specify for using CertStore(s) in his application is as follows :

 <sc:CertStore 
    callbackHandler="{fully qualified ClassName of a class that implements
    javax.security.auth.callback.CallbackHandler interface and handles
    the com.sun.xml.wss.impl.callback.CertStoreCallback}"  
    certSelector="{fully qualified ClassName of a class that implements
    the java.security.cert.CertSelector interface}" 
/>?

       
The use of  CertStore is optional and when using it on GlassFish, specifying the callbackHandler attribute has no effect, becuase the GlassFish Default CallbackHandler  provides its own CertStore (via a JSR 196 defined CertStoreCallback) which cannot be overridden.

When a CertStore is specified it is imperative to specify the certSelector attribute if the  client/server developer wishes to control the process of selecting the  certificate of the other party  which has to be used for Encrypting the request. The Implementation may randomly pick a certificate if the certSelector is not specified and this can lead to incorrect behaviour.  Typically developers may want to dynamically select the certificate of the other party based on the Endpoint or some other runtime properties.  So the WSIT Runtime would do the following :

1.  If the  certSelector class that was supplied above contains a  Constructor that takes a  java.util.Map as an argument then the WSIT runtime would create a new instance of the CertSelector everytime it needs to use the CertSelector and would pass it a  Map of  Runtime Properties (which among other things would contain the EndPoint in case of a  Client side CertSelector and the ClientSubject in case of a Server Side CertSelector), obtained from the underlying JAXWS Runtime.  For a list of properties available refer to JAXWS documentation. The only extra property that is available for Server Side CertSelector(s) is a property Named AUTH_SUBJECT,  whose value is a javax.security.auth.Subject containing Principals/Credentials of the Sender/Client.

2. If the certSelector class does not have a Constructor that takes a Map then WSIT runtime would instantiate the CertSelector using a Default Constructor.

NOTE:  If a certSelector is not specified then it is not an ERROR, but the  WSIT runtime would not look inside the CertStore for a Certificate to use for encrypting the request to the other party.  This however DOES NOT imply that the CertStore is rendered useless, because the runtime still looks for certificates inside the CertStore in cases where it has to locate a Certificate for verifying Signatures of incoming client requests.

NOTE: Similar to Keystore and TrustStore  assertion, the CertStore assertion is applicable on both the client and server side with appropriate Namespace.

NOTE:  With the use of  CertStore(s) one may no longer need to keep Non-CA certificates inside the  Truststore(s) ( For example the  GlassFish Truststore cacerts.jks may no longer need to contain the Non-CA certificates. Up until  WSIT Milestone 3 we were doing this, now the developer may make use of a Certstore and manage things on his own).   Developer's may still need to configure the TrustStore because the TrustStore would be used to access the CA (Certificate Authority )  certificates which are used during Certificate Validation.

NOTE:  GlassFish currently does not have a Mechanism to Configure a CertStore for an Application. So when running  Applications on GlassFish today  the GlassFish CallbackHandler  implicitly returns the TrustStore as a  CertStore.  We are working to make this configurable in a future release of  GlassFish. Developers who configure their own "jmacCallbackHandler" as described earlier in this article will  not have this limitation since they can actually locate the certstore using their own mechanisms.

NOTE:  There is no NetBeans Support for specifying CertStore's today. A future release of  NetBeans will include this support. Until then developers can configure CertStore's manually by editing the  WSIT configuration files on the Client and Server side.

Configuring WSIT Security For an Application Deployed on GlassFish (A Summary)

To reduce any confusion this section summarizes the simplification that WSIT security developers on GlassFish can experience with all that was described above.

  1. WSIT Security Runtime makes use of a JSR 196 based DefaultCallbackHandler for applications running on GlassFish.
  2.  The GlassFish  DefaultCallbackHandler can be overridden by developers on both client and server side by specifying a jmacCallbackHandler.

 Note: Overriding the GlassFish DefaultCallbackHandler is only necessary when the Default one is unable to satisfy some requirement of the application. Otherwise the DefaultCallbackHandler provides a lot of value of developer in terms of  being aware of  :
          1.  the KeyManagement infrastructure of  glassfish. It can locate certificates located either in the default JKS stores or the NSS stores etc.
          2.  the  Realms of Glassfish
          3.  Constructing the authenticated principals in a way that is understood by the GlassFish Container.

 So what is the configuration required  on the client and server side for WSIT Security Applications deployed on GlassFish.

  WebService Client Application Deployed on GlassFish

      1. If the scenario requires username and password then one can use the Default username and password options for  Embedded Clients. If the client is an ACC client then if the GlassFish DefaultCallbackHandler is being used then it automatically makes a NameCallback and PasswordCallback for gathering the username and password.

     2.  If the scenario requires certificates then if  the application is using the  GlassFish DefaultCallbackHandler (instead of an overridden jamcCallbackHandler), it  only needs to specify the keystore alias and truststore  alias (peeralias). No other information is necessary.  Note the truststore alias is required only if Encryption involved in the scenario. If  a developer supplied jmacCallbackHandler is being used then even the alias information may not be necessary depending on how the handler is written. If  specified however the alias information is passed  to the  appropriate callback in the jmacCallbackHandler.

     3.  If the client wishes to control any of the attributes defined on ValidatorConfiguration or CallbackHandlerConfiguration they may be optionally specified.

     4.  If any of the Netbeans SAML Mechanism(s) are selected then a samlHandler needs to be specified.

    WebService Application Deployed on GlassFish

      1. If the scenario requires the client to send a username and password then if the default GlassFish CallbackHandler is being used then the developer just needs to make sure the that the user is registered with the GlassFish Realms.

      2.  If the scenario requires certificates then if the application is using the  GlassFish DefaultCallbackHandler (instead of an overridden jamcCallbackHandler), it  only needs to specify the keystore alias. No other information is necessary. If  a developer supplied jmacCallbackHandler is being used then even the keystore alias information may not be necessary depending on how the handler is written. If  specified however the alias information is passed  to the  appropriate callback in the jmacCallbackHandler.

      3.  If the  WebService wishes to control any of the attributes defined on ValidatorConfiguration or CallbackHandlerConfiguration they may be optionally specified.
     

Security Configuration for Mechanism that use an  "STS "

  The Security Configuration for  Security Mechanisms in WSIT NetBeans UI that start with "STS"  would follow a similar procedure as far as configuring Keystore, TrustStore, Username/Password etc are concerned. The additional configuration required on the Server side for an STS and on the Client side are discussed in the following places :

  1. https://wsit-docs.dev.java.net/releases/m3/ClientSecurity7.html#wp131166
  2. https://wsit-docs.dev.java.net/releases/m3/SecurityProfiles13.html#wp142952
  3. https://wsit-docs.dev.java.net/releases/m3/SecurityProfiles8.html#wp142879
  4. http://blogs.sun.com/shyamrao/
  5. http://blogs.sun.com/trustjdg
  6. http://blogs.sun.com/harsha/

Note: An STS stands for a Security Token Service.

Your Feedback is Important for Us

Please provide all feedback on this article to  dev@wsit.dev.java.net OR users@xwss.dev.java.net

NOTE:  When writing the Security Configuration assertions manually make sure the namespace prefix "sc"  is bound to the proper namespace URI. Specifically  on the server side the  prefix "sc" should be bound as follows : xmlns:sc="http://schemas.sun.com/2006/03/wss/server"
 and on the client side the namespace prefix "sc"  should be bound as follows : xmlns:sc="http://schemas.sun.com/2006/03/wss/client"


 
 
Close
loading
Please Confirm
Close