SEC-1544: Added CookieClearingLogoutHandler and 'delete-cookies' attribute to the 'logout' namespace element.

When the user logs out, the handler will attempt to delete the named cookies (which it is constructor-injected with) by expiring them in the response.

Also added documentation on the feature and a suggestion for deleting JSESSIONID through an Apache proxy server, if the servlet container doesn't allow clearing the session cookie.

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

@@ -496,11 +496,22 @@
                 <para> The destination URL which the user will be taken to after logging out.
                     Defaults to "/". </para>
             </section>
+            <section>
+                <title>The <literal>success-handler-ref</literal> attribute</title>
+                <para>May be used to supply an instance of <interfacename>LogoutSuccessHandler</interfacename>
+                    which will be invoked to control the navigation after logging out.
+                </para>
+            </section>
             <section>
                 <title>The <literal>invalidate-session</literal> attribute</title>
                 <para> Maps to the <literal>invalidateHttpSession</literal> of the
                     <classname>SecurityContextLogoutHandler</classname>. Defaults to "true", so the
-                    session will be invalidated on logout. </para>
+                    session will be invalidated on logout.</para>
+            </section>
+            <section>
+                <title>The <literal>delete-cookies</literal> attribute</title>
+                <para>A comma-separated list of the names of cookies which should be deleted when the user logs out.
+                </para>
             </section>
         </section>
         <section>

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

@@ -338,6 +338,14 @@
                     information on how to customize the flow when authentication fails. </para>
             </section>
         </section>
+        <section xml:id="ns-logout">
+            <title>Logout Handling</title>
+            <para>The <literal>logout</literal> element adds support for logging out by navigating
+                to a particular URL. The default logout URL is <literal>/j_spring_security_logout</literal>,
+                but you can set it to something else using the <literal>logout-url</literal> attribute.
+                More information on other available attributes may be found in the namespace appendix.
+            </para>
+        </section>
         <section xml:id="ns-auth-providers">
             <title>Using other Authentication Providers</title>
             <para> In practice you will need a more scalable source of user information than a few
@@ -465,8 +473,28 @@
                     the <literal>session-management</literal> element: <programlisting language="xml"><![CDATA[
   <http>
     ...
-    <session-management invalid-session-url="/sessionTimeout.htm" />
-  </http>]]></programlisting></para>
+    <session-management invalid-session-url="/invalidSession.htm" />
+    </http>]]></programlisting>Note that if you use this mechanism to detect session timeouts, it
+                    may falsely report an error if the user logs out and then logs back in without
+                    closing the browser. This is because the session cookie is not cleared when you
+                    invalidate the session and will be resubmitted even if the user has logged out.
+                    You may be able to explicitly delete the JSESSIONID cookie on logging out, for
+                    example by using the following syntax in the logout handler: <programlisting language="xml"><![CDATA[
+  <http>
+    <logout delete-cookies="JSESSIONID" />
+  </http>
+  ]]></programlisting> Unfortunately this can't be guaranteed to work with every servlet container,
+                    so you will need to test it in your environment<footnote>
+                    <para>If you are running your application behind a proxy, you may also be able
+                        to remove the session cookie by configuring the proxy server. For example,
+                        using Apache HTTPD's mod_headers, the following directive would delete the
+                        <literal>JSESSIONID</literal> cookie by expiring it in the response to a
+                        logout request (assuming the application is deployed under the path
+                        <literal>/tutorial</literal>):
+                        <programlisting> &lt;LocationMatch "/tutorial/j_spring_security_logout">
+  Header always set Set-Cookie "JSESSIONID=;Path=/tutorial;Expires=Thu, 01 Jan 1970 00:00:00 GMT"
+ &lt;/LocationMatch></programlisting></para>
+                    </footnote>. </para>
             </section>
             <section xml:id="ns-concurrent-sessions">
                 <title>Concurrent Session Control</title>