SEC-2135: Document HttpServletRequest.changeSessionId() support

docs/faq/src/docbook/faq.xml

@@ -357,11 +357,14 @@
                             Security?</para>
                     </question>
                     <answer>
-                        <para>With the default configuration, Spring Security invalidates the
-                            existing session when the user authenticates and creates a new one,
-                            transferring the session data to it. The intention is to change the
-                            session identifier to prevent <quote>session-fixation</quote> attacks.
-                            You can find more about this online and in the reference manual. </para>
+                        <para>With the default configuration, Spring Security changes the session ID
+                            when the user authenticates. If you're using a Servlet 3.1 or newer
+                            container, the session ID is simply changed. If you're using an older
+                            container, Spring Security invalidates the existing session, creates a
+                            new session, and transfers the session data to the new session. Changing
+                            the session identifier in this manner prevents
+                            <quote>session-fixation</quote> attacks. You can find more about this
+                            online and in the reference manual. </para>
                     </answer>
                 </qandaentry>
 
@@ -378,12 +381,15 @@
                             be used under HTTP. The browser will not send the cookie back to the
                             server and any session state will be lost (including the security
                             context information). Starting a session in HTTP first should work as
-                            the session cookie won't be marked as secure (you will also have to
-                            disable Spring Security's <link
+                            the session cookie won't be marked as secure. However, Spring
+                            Security's <link
                             xlink:href="http://static.springsource.org/spring-security/site/docs/3.1.x/reference/springsecurity-single.html#ns-session-fixation"
-                            > Session Fixation Protection</link> support to prevent it from creating
-                            a new secure session on login (you can always create a new session
-                            yourself at a later stage). Note that switching between HTTP and HTTPS
+                            >Session Fixation Protection</link> can interfere with this because
+                            it results in a new session ID cookie being sent back to the user's
+                            browser, usually with the secure flag. To get around this, you can
+                            disable session fixation protection, but in newer Servlet containers
+                            you can also configure session cookies to never use the secure flag.
+                            Note that switching between HTTP and HTTPS
                             is not a good idea in general, as any application which uses HTTP at all
                             is vulnerable to man-in-the-middle attacks. To be truly secure, the user
                             should begin accessing your site in HTTPS and continue using it until

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

@@ -1185,11 +1185,14 @@
                 </section>
                 <section xml:id="nsa-session-management-session-fixation-protection">
                     <title><literal>session-fixation-protection</literal></title>
-                    <para> Indicates whether an existing session should be invalidated when a user
-                        authenticates and a new session started. If set to "none" no change will be
-                        made. "newSession" will create a new empty session. "migrateSession" will create
-                        a new session and copy the session attributes to the new session. Defaults to
-                        "migrateSession".</para>
+                    <para>Indicates how session fixation protection will be applied when a user authenticates. If
+                        set to "none", no protection will be applied. "newSession" will create a
+                        new empty session, with only Spring Security-related attributes migrated. "migrateSession" will create
+                        a new session and copy all session attributes to the new session. In Servlet 3.1 (Java EE 7)
+                        and newer containers, specifying "changeSessionId" will keep the existing session and use the
+                        container-supplied session fixation protection (HttpServletRequest#changeSessionId()). Defaults to
+                        "changeSessionId" in Servlet 3.1 and newer containers, "migrateSession" in older containers. Throws an
+                        exception if "changeSessionId" is used in older containers.</para>
                     <para> If session fixation protection is enabled, the
                         <classname>SessionManagementFilter</classname> is injected with an appropriately
                         configured <classname>DefaultSessionAuthenticationStrategy</classname>. See the

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

@@ -525,27 +525,42 @@
                     malicious attacker to create a session by accessing a site, then persuade
                     another user to log in with the same session (by sending them a link containing
                     the session identifier as a parameter, for example). Spring Security protects
-                    against this automatically by creating a new session when a user logs in. If you
-                    don't require this protection, or it conflicts with some other requirement, you
-                    can control the behaviour using the
+                    against this automatically by creating a new session or otherwise changing the
+                    session ID when a user logs in. If you don't require this protection, or it
+                    conflicts with some other requirement, you can control the behavior using the
                     <literal>session-fixation-protection</literal> attribute on
-                    <literal>&lt;session-management&gt;</literal>, which has three options <itemizedlist>
-                    <listitem>
-                        <para><literal>migrateSession</literal> - creates a new session and copies
-                            the existing session attributes to the new session. This is the
-                            default.</para>
-                    </listitem>
+                    <literal>&lt;session-management&gt;</literal>, which has four options <itemizedlist>
                     <listitem>
                         <para><literal>none</literal> - Don't do anything. The original session will
                             be retained.</para>
                     </listitem>
                     <listitem>
                         <para><literal>newSession</literal> - Create a new "clean" session, without
-                            copying the existing session data.</para>
+                            copying the existing session data (Spring Security-related attributes will
+                            still be copied).</para>
+                    </listitem>
+                    <listitem>
+                        <para><literal>migrateSession</literal> - Create a new session and copy
+                            all existing session attributes to the new session. This is the
+                            default in Servlet 3.0 or older containers.</para>
+                    </listitem>
+                    <listitem>
+                        <para><literal>changeSessionId</literal> - Do not create a new session.
+                            Instead, use the session fixation protection provided by the Servlet container
+                            (<literal>HttpServletRequest#changeSessionId()</literal>). This option is only
+                            available in Servlet 3.1 (Java EE 7) and newer containers. Specifying it in
+                            older containers will result in an exception. This is the default in Servlet
+                            3.1 and newer containers.</para>
                     </listitem>
                     </itemizedlist>
-                    See the <link xlink:href="#session-mgmt">Session Management</link> chapter for
-                    additional information.
+                    When session fixation protection occurs, it results in a
+                    <classname>SessionFixationProtectionEvent</classname> being published in the
+                    application context. If you use <literal>changeSessionId</literal>, this protection
+                    will <emphasis>also</emphasis> result in any
+                    <classname>javax.servlet.http.HttpSessionIdListener</classname>s being notified, so
+                    use caution if your code listens for both events. See the
+                    <link xlink:href="#session-mgmt">Session Management</link> chapter for additional
+                    information.
                 </para>
             </section>
         </section>

docs/manual/src/docbook/session-mgmt.xml

@@ -163,7 +163,7 @@
                 which you can use directly within your application, so even if you don't want to restrict the
                 number of sessions a user may have, it may be worth setting up the infrastructure anyway. You can
                 set the <literal>maximumSession</literal> property to -1 to allow unlimited sessions. If
-                 you're using the namespace, you can set an alias for the internally-created 
+                 you're using the namespace, you can set an alias for the internally-created
                 <interfacename>SessionRegistry</interfacename> using the <literal>session-registry-alias</literal>
                 attribute, providing a reference which you can inject into your own beans.</para>
             <para>