SEC-1536: added JAAS API Integration, updated doc, updated jaas sample

docs/manual/src/docbook/appendix-namespace.xml

@@ -70,6 +70,13 @@
                     <classname>SecurityContextHolderAwareRequestFilter</classname> bean to the
                     stack. Defaults to "true".</para>
             </section>
+            <section xml:id="nsa-jaas-api-provision">
+                <title><literal>jaas-api-provision</literal></title>
+                <para>If available, runs the request as the <literal>Subject</literal> acquired from 
+                    the <classname>JaasAuthenticationToken</classname> which is implemented by 
+                    adding a <classname>JaasApiIntegrationFilter</classname> bean to the stack. 
+                    Defaults to "false".</para>
+            </section>
             <section xml:id="nsa-path-type">
                 <title><literal>request-matcher</literal></title>
                 <para> Defines the <interfacename>RequestMatcher</interfacename> strategy used in

docs/manual/src/docbook/jaas-auth-provider.xml

@@ -213,4 +213,20 @@ JAASTest {
 </bean>
 ]]></programlisting></para>
     </section>
+    <section xml:id="jaas-apiprovision">
+        <info>
+            <title xml:id="jaas-api-provision">Running as a Subject</title>
+        </info>
+        <para>If configured, the <classname>JaasApiIntegrationFilter</classname> will attempt to 
+            run as the <literal>Subject</literal> on the 
+            <classname>JaasAuthenticationToken</classname>. This means that the 
+            <literal>Subject</literal> can be accessed using: 
+            <programlisting language="java"><![CDATA[
+            Subject subject = Subject.getSubject(AccessController.getContext());
+]]></programlisting>
+            This integration can easily be configured using the 
+            <link xlink:href="#nsa-jaas-api-provision">jaas-api-provision</link> attribute. This
+            feature is useful when integrating with legacy or external API's that rely on the
+            JAAS Subject being populated.</para>
+    </section>
 </chapter>

docs/manual/src/docbook/namespace-config.xml

@@ -691,6 +691,11 @@ List&lt;OpenIDAttribute> attributes = token.getAttributes();</programlisting>The
                             <entry><literal>SecurityContextHolderAwareFilter</literal></entry>
                             <entry><literal>http/@servlet-api-provision</literal></entry>
                         </row>
+                        <row>
+                            <entry>JAAS_API_SUPPORT_FILTER</entry>
+                            <entry><literal>JaasApiIntegrationFilter</literal></entry>
+                            <entry><literal>http/@jaas-api-provision</literal></entry>
+                        </row>
                         <row>
                             <entry> REMEMBER_ME_FILTER </entry>
                             <entry><classname>RememberMeAuthenticationFilter</classname></entry>

docs/manual/src/docbook/samples.xml

@@ -133,7 +133,8 @@ Success! Your web filters appear to be properly configured!
         <title>JAAS Sample</title>
         <para>The JAAS sample is very simple example of how to use a JAAS LoginModule with Spring Security. The provided LoginModule will
             successfully authenticate a user if the username equals the password otherwise a LoginException is thrown. The AuthorityGranter
-            used in this example always grants the role ROLE_USER.</para>
+            used in this example always grants the role ROLE_USER. The sample application also demonstrates how to run as the JAAS Subject
+            returned by the LoginModule by setting <link xlink:href="#nsa-jaas-api-provision">jaas-api-provision</link> equal to "true".</para>
     </section>
     <section xml:id="preauth-sample">
         <title>Pre-Authentication Sample</title>

docs/manual/src/docbook/security-filter-chain.xml

@@ -151,6 +151,13 @@
                     using it to install a Spring Security aware
                     <literal>HttpServletRequestWrapper</literal> into your servlet container</para>
             </listitem>
+            <listitem>
+                <para>The <classname>JaasApiIntegrationFilter</classname>, if a 
+                    <classname>JaasAuthenticationToken</classname> is in the 
+                    <classname>SecurityContextHolder</classname> this will process the 
+                    <classname>FilterChain</classname> as the <classname>Subject</classname> in the 
+                    <classname>JaasAuthenticationToken</classname></para> 
+            </listitem>
             <listitem>
                 <para><classname>RememberMeAuthenticationFilter</classname>, so that if no earlier
                     authentication processing mechanism updated the