[jboss-svn-commits] JBL Code SVN: r29406 - labs/jbossesb/workspace/dbevenius/saml_support/product/rosetta/src/org/jboss/soa/esb/services/security/auth/ws.

[jboss-svn-commits at lists.jboss.org]

Author: beve
Date: 2009-09-18 10:54:18 -0400 (Fri, 18 Sep 2009)
New Revision: 29406

Modified:
   labs/jbossesb/workspace/dbevenius/saml_support/product/rosetta/src/org/jboss/soa/esb/services/security/auth/ws/JBossSTSSecurityHandler.java
Log:
Added some javadocs. Plus minor clean up.


Modified: labs/jbossesb/workspace/dbevenius/saml_support/product/rosetta/src/org/jboss/soa/esb/services/security/auth/ws/JBossSTSSecurityHandler.java
===================================================================
--- labs/jbossesb/workspace/dbevenius/saml_support/product/rosetta/src/org/jboss/soa/esb/services/security/auth/ws/JBossSTSSecurityHandler.java	2009-09-18 14:30:38 UTC (rev 29405)
+++ labs/jbossesb/workspace/dbevenius/saml_support/product/rosetta/src/org/jboss/soa/esb/services/security/auth/ws/JBossSTSSecurityHandler.java	2009-09-18 14:54:18 UTC (rev 29406)
@@ -43,13 +43,41 @@
 import org.w3c.dom.Element;
 
 /**
- * JBossSTSSecurityHandler is a server side JAXWS SOAP Protocol handler
- * that will extract a Security Token from the SOAP Security Header
- * and validate the token with JBoss Security Token Service (STS)
+ * JBossSTSSecurityHandler is a server-side JAX-WS SOAP Protocol handler that will extract 
+ * a Security Token from the SOAP Security Header and validate the token with JBoss Security 
+ * Token Service (STS)
  * <p/>
  * 
+ * <h3>Concrete implementations</h3>
+ * Subclasses a required to implement two methods:
+ * <ul>
+ * <li> {@link #getSecurityElementQName()} 
+ *    This should return the qualified name of the security header. This lets us support 
+ *    different versions. </li>
+ *    
+ * <li>{@link #getTokenElementQName()}
+ *    This should return the qualified name of the security token element that should exist
+ *    in the security header. This lets us support different tokens that can be validated
+ *    with JBossSTS.</li>
+ * </ul>
+ * <p/>
+ *    
+ * <h3>Configuration</h3>
+ * This class uses {@link WSTrustClient} to interact with JBossSTS. By default the configuration
+ * properties are set in a file named {@link WSTrustClientConfig#DEFAULT_CONFIG_FILE}.
+ * This can be overridden by specifying environment entries in a deployment descriptor. 
+ * 
+ * For example in web.xml:
+ * <pre>{@code
+ * <env-entry>
+ *   <env-entry-name>JBossSTSClientConfig</env-entry-name>
+ *   <env-entry-type>java.lang.String</env-entry-type>
+ *   <env-entry-value>/jboss-sts-client.properties</env-entry-value>
+ * </env-entry>
+ * }</pre>
+ * 
+ * 
  * @author <a href="mailto:dbevenius at jboss.com">Daniel Bevenius</a>
- *
  */
 public abstract class JBossSTSSecurityHandler implements SOAPHandler<SOAPMessageContext>
 {
@@ -92,8 +120,7 @@
             final WSTrustClientConfig config = new WSTrustClientConfig.Builder().build(configFile);
             final WSTrustClient wsTrustClient = createWSTrustClient(config);
 
-            Element securityToken = extractSecurityToken(messageContext, getSecurityElementQName(), getTokenElementQName());
-            // Validate the security token with JBossSTS
+            final Element securityToken = extractSecurityToken(messageContext, getSecurityElementQName(), getTokenElementQName());
             final boolean valid = wsTrustClient.validateToken(securityToken);
             if (valid)
             {
@@ -133,16 +160,12 @@
     private Element extractSecurityToken(final SOAPMessageContext messageContext, final QName securityQName, final QName tokenQName) throws SOAPException
     {
         final SOAPHeader soapHeader = messageContext.getMessage().getSOAPHeader();
-        // Inspect all SOAP Headers
-        final Iterator examineAllHeaderElements = soapHeader.examineAllHeaderElements();
-        while (examineAllHeaderElements.hasNext())
+        final Iterator securityHeaders = soapHeader.getChildElements(securityQName);
+        while (securityHeaders.hasNext())
         {
-            final SOAPHeaderElement elem = (SOAPHeaderElement) examineAllHeaderElements.next();
-            final QName elementQName = elem.getElementQName();
-            if (elementQName.equals(securityQName))
+            final SOAPHeaderElement elem = (SOAPHeaderElement) securityHeaders.next();
+            if (elem.getElementQName().equals(securityQName))
             {
-                // Get all(should only be one) the of the Security Headers
-                // that we are interested in.
                 final Iterator childElements = elem.getChildElements(tokenQName);
                 while (childElements.hasNext())
                 {
@@ -174,14 +197,6 @@
     /**
      * This setter enables the injection of the jboss-sts-client.properties file
      * path.
-     * This can be specified for example in web.xml:
-     * <pre>
-     * <env-entry>
-     *   <env-entry-name>JBossSTSClientConfig</env-entry-name>
-     *   <env-entry-type>java.lang.String</env-entry-type>
-     *   <env-entry-value>/jboss-sts-client.properties</env-entry-value>
-     *  </env-entry>
-     * </pre>
      *  
      * @param configFile
      */