SEC-2782: Polish Migrating from 3 to 4 Guide

docs/manual/src/docs/asciidoc/_includes/migrate-3-to-4.adoc

@@ -1,1476 +0,0 @@
-[[m3to4]]
-= Migrating from 3.x to 4.x
-
-As exploits against applications evolve, so must Spring Security.
-As a major release version, the Spring Security team took the opportunity to make some non-passive changes which focus on:
-
-* Ensuring Spring Security is more secure by default
-* Minimizing https://www.owasp.org/index.php/Information_Leakage[Information Leakage]
-* Removing deprecated APIs
-
-A complete listing of non-passive changes between 3.x and 4.x can be found in https://jira.spring.io/issues/?jql=project%20%3D%20SEC%20AND%20status%20in%20(Resolved%2C%20Closed)%20AND%20fixVersion%20in%20(4.0.0%2C%204.0.0.M1%2C%204.0.0.M2%2C%204.0.0.RC1%2C%204.0.0.RC2)%20AND%20labels%20%3D%20passivity[JIRA]
-This guide is intended to help users migrate from Spring Security 3.x to Spring Security 4.x.
-
-NOTE: It is expected that users will be able to easily perform a successful migration within an hour.
-
-[[m3to4-xmlnamespace-defaults]]
-== Migrate XML Namespace Defaults
-
-We updated the default values for many of the Spring Security XML Namespace Elements.
-You can find a detailed list of changes and how to address them below.
-
-NOTE: If you do not use XML based configuration, you may safely skip this section and proceed to <<m3to4-filter-urls>>
-
-[[m3to4-xmlnamespace-related]]
-=== Related Links
-
-For thoroughness we have include the related links in the table below.
-
-|====
-| JIRA | Commits
-
-| https://jira.spring.io/browse/SEC-2783[SEC-2783]
-| https://github.com/spring-projects/spring-security/commit/c67ff42b8abe124b7956896c78e9aac896fd79d9[c67ff42]
-
-| https://jira.spring.io/browse/SEC-2347[SEC-2347]
-| https://github.com/spring-projects/spring-security/commit/4392205f63e49b9675b06e584f571a48b017d0b6[4392205]
-
-| https://jira.spring.io/browse/SEC-2348[SEC-2348]
-| https://github.com/spring-projects/spring-security/commit/eedbf442359f9a99e367f2fdef61deea1cef46c9[eedbf44]
-
-| https://jira.spring.io/browse/SEC-2781[SEC-2781]
-| https://github.com/spring-projects/spring-security/commit/6e204fff72b80196a83245cbc3bd0cd401feda00[6e204ff]
-
-| https://jira.spring.io/browse/SEC-2873[SEC-2873]
-| https://github.com/spring-projects/spring-security/commit/5f57e5b0c3726466db4f5d0521ac26423f0d9cd4[5f57e5b]
-|====
-
-[[m3to4-xmlnamespace-http]]
-=== Migrate <http>
-
-The <<nsa-http-use-expressions,http@use-expressions>> attribute's default value changed from false to true.
-This means if the use-expression attribute is not explicitly configured, then the configuration will need updated.
-For example, if an application using Spring Security 3.2.x contains a configuration similar to the following:
-
-.Spring Security 3.2.x Sample Configuration
-[source,xml]
-----
-<http> <!--1-->
-    <intercept-url pattern="/login" access="ROLE_ANONYMOUS"/>
-    <intercept-url pattern="/**" access="ROLE_USER"/>
-    ...
-</http>
-----
-
-<1> Observe that the use-expressions attribute is not provided. If it were provided, then nothing needs to be done.
-
-The configuration will need to be updated to something similar to the following when Spring Security 4.x:
-
-.Migration to Spring Security 4 Configuration
-[source,xml]
-----
-<http use-expressions="false"> <!--1-->
-    <intercept-url pattern="/login" access="ROLE_ANONYMOUS"/>
-    <intercept-url pattern="/**" access="ROLE_USER"/>
-    ...
-</http>
-----
-
-<1> We explicitly provide the use-expressions attribute. Again, if the attribute was already provided, then nothing needs to be done.
-
-*Alternatively*, the application can omit the the use-expressions attribute and switch to using expressions.
-For example, something similar to the following:
-
-
-.Alternative Migration to Spring Security 4 Configuration
-[source,xml]
-----
-<http>
-    <intercept-url pattern="/login" access="permitAll"/>
-    <intercept-url pattern="/**" access="hasRole('USER')"/>
-    ...
-</http>
-----
-
-[[m3to4-xmlnamespace-form-login]]
-=== Migrating <form-login>
-
-If the `<form-login>` is being used within an application, then some of the default attributes have changed.
-Below are detailed description of the changes and how to migrate:
-
-* The <<nsa-form-login-username-parameter,form-login@username-parameter>> attribute default value changed from j_username to username. If an application explicitly provides the attribute, no action is required for the migration.
-* The <<nsa-form-login-password-parameter,form-login@password-parameter>> attribute default value changed from j_password to password. If an application explicitly provides the attribute, no action is required for the migration.
-* The <<nsa-form-login-login-processing-url,form-login@login-processing-url>> attribute default value changed from /j_spring_security_check to POST /login. If an application explicitly provides the attribute, no action is required for the migration.
-* The <<nsa-form-login-authentication-failure-url,form-login@authentication-failure-url>> attribute default value changed from appending ?login_error to the login-page to appending ?error to the login-page. If an application explicitly provides the attribute, no action is required for the migration.
-
-These changes mean if you have the following configuration within your XML configuration when using Spring Security 3.2.x:
-
-
-.Spring Security 3.2.x Sample Configuration
-[source,xml]
-----
-<http>
-    ...
-    <form-login login-page="/login"/>
-</http>
-----
-
-You will need to migrate by explicitly configuring the attributes that have new default values when migrating to Spring Security 4.x:
-
-NOTE: Any attribute that is already explicitly provided will not be impacted and requires no action.
-
-.Migration to Spring Security 4 Configuration
-[source,xml]
-----
-<http>
-    ...
-    <form-login login-page="/login"
-                username-parameter="j_username" <!--1-->
-                password-parameter="j_password" <!--2-->
-                login-processing-url="/j_spring_security_check" <!--3-->
-                authentication-failure-url="/login?login_error=1" <!--4-->
-    />
-</http>
-----
-
-<1> If the configuration does not specify the username-parameter, then it should be explicitly stated
-<2> If the configuration does not specify the password-parameter, then it should be explicitly stated
-<3> If the configuration does not specify the login-processing-url, then it should be explicitly stated
-<4> If the configuration does not specify the authentication-failure-url, then it should be explicitly stated
-
-**Alternatively**, the application can be updated to use the new defaults.
-For example, one might update their log in form to look like the following:
-
-.Alternative Migration to Spring Security 4.x (i.e. login.jsp)
-[source,xml]
-----
-<c:if test="${param.error != null}"> <!--1-->
-  <p>Invalid username / password</p>
-</c:if>
-<c:url var="loginUrl" value="/login"/> <!--2-->
-<form action="${loginUrl}" method="post">
-    <p><label for="username">User:</label></p>
-    <input type="text" id="username" name="username"/> <!--3-->
-
-    <p><label for="password">Password:</label></p>
-    <input type="password" id="password" name="password"> <!--4-->
-
-    <div>
-        <input name="submit" type="submit"/>
-    </div>
-</form>
-----
-
-<1> If the configuration does not specify the authentication-failure-url, then detect that an invalid log in check to see if the HTTP parameter error is not null.
-<2> If the configuration does not specify the login-processing-url, then modify the URL to submit to be "/login"
-<3> If the configuration does not specify the username-parameter, then modify the username HTTP parameter to be "username"
-<4> If the configuration does not specify the password-parameter, then modify the password HTTP parameter to be "password"
-
-[[m3to4-xmlnamespace-openid-login]]
-=== Migrating <openid-login>
-
-The <<nsa-openid-login-login-processing-url,openid-login@login-processing-url>> attribute default value changed from /j_spring_openid_security_login to /login/openid.
-
-This means if the login-processing-url attribute is not explicitly configured, then the configuration will need updated.
-For example, if an application using Spring Security 3.2.x contains a configuration similar to the following:
-
-.Spring Security 3.2.x Sample Configuration
-[source,xml]
-----
-<http>
-    <openid-login /> <!--1-->
-    ...
-</http>
-----
-
-<1> Observe that the login-processing-url attribute is not provided. If it were provided, then nothing needs to be done.
-
-The configuration will need to be updated to something similar to the following when Spring Security 4.x:
-
-.Migration to Spring Security 4 Configuration
-[source,xml]
-----
-<http>
-    <openid-login login-processing-url="/j_spring_openid_security_check"/> <!--1-->
-    ...
-</http>
-----
-
-<1> We explicitly provide the login-processing-url attribute. Again, if the attribute was already provided, then nothing needs to be done.
-
-*Alternatively*, the application can omit the the login-processing-url attribute and update the log in form.
-For example, something similar to the following:
-
-.Alternative Migration to Spring Security 4.x (i.e. login.jsp)
-[source,xml]
-----
-<c:url var="openidLoginUrl" value="/login/openid"/> <!--1-->
-<form action="${openidLoginUrl}" method="post">
-
-<div>
-    <input name="openid_identifier" type="text" value="http://" />
-    <input type="submit" value="Sign-In"/>
-</div>
-</form>
-----
-
-<1> If the configuration does not specify the login-processing-url attribute, then update the log in action to "/login/openid".
-
-[[m3to4-xmlnamespace-headers]]
-=== Migrating <headers>
-
-As Spring Security 4.0+ <<headers,Security HTTP Response Headers>> is now enabled by default.
-This means if an application did not provide the <<nsa-headers,headers>> element, then the configuration will need updated.
-For example, if an application using Spring Security 3.2.x contains a configuration similar to the following:
-
-.Spring Security 3.2.x Sample Configuration
-[source,xml]
-----
-<http>
-    ...
-    <!-- no headers element -->
-</http>
-----
-
-The application will need updated.
-The quickest, but not ideal, solution is to explicitly disable the headers protection using <<nsa-headers-disabled,headers@disabled>>.
-For example:
-
-.Migration to Spring Security 4 Configuration
-[source,xml]
-----
-<http>
-    ...
-    <headers disabled="true"/>
-</http>
-----
-
-*Alternatively*, the application would enable Security HTTP Response Headers.
-In many instances, leaving the Security HTTP Response Headers enabled will not have a negative impact on an application.
-
-Developers are encouraged to read <<headers,Security HTTP Response Headers>> for details on using this feature.
-
-[[m3to4-xmlnamespace-csrf]]
-=== Migrating <csrf>
-
-As Spring Security 4.0+ <<csrf,CSRF Protection>> is now enabled by default.
-This means if an application did not provide the <<nsa-csrf,csrf>> element, then the configuration will need updated.
-For example, if an application using Spring Security 3.2.x contains a configuration similar to the following:
-
-[source,xml]
-----
-<http>
-    ...
-    <!-- no csrf element -->
-</http>
-----
-
-The application will need updated.
-The quickest, but not ideal, solution is to explicitly disable the csrf protection using <<nsa-csrf-disabled,csrf@disabled>>.
-For example:
-
-.Migration to Spring Security 4 Configuration
-[source,xml]
-----
-<http>
-    ...
-    <csrf disabled="true"/>
-</http>
-----
-
-*Alternatively*, the application would enable CSRF.
-For more details refer to <<csrf-using,Using Spring Security CSRF Protection>>.
-
-[[m3to4-xmlnamespace-remember-me]]
-=== Migrating <remember-me>
-
-If the `<remember-me>` element is being used within an application, then some of the default attributes have changed.
-Below are detailed description of the changes and how to migrate:
-
-* The <<nsa-remember-me-remember-me-parameter,remember-me@remember-me-parameter>> attribute default value changed from "_spring_security_remember_me" to "remember-me". If an application explicitly provides the attribute, no action is required for the migration.
-* The <<nsa-remember-me-remember-me-cookie,remember-me@remember-me-cookie>> attribute default value changed from "_spring_security_remember_me" to "SPRING_SECURITY_REMEMBER_ME_COOKIE". If an application explicitly provides the attribute, no action is required for the migration.
-
-These changes mean if you have the following configuration within your XML configuration when using Spring Security 3.2.x:
-
-[source,xml]
-----
-<http>
-    ...
-    <remember-me />
-</http>
-----
-
-You will need to migrate by explicitly configuring the attributes that have new default values when migrating to Spring Security 4.x:
-
-NOTE: Any attribute that is already explicitly provided will not be impacted and requires no action.
-
-[source,xml]
-----
-<http>
-    ...
-    <remember-me
-                remember-me-parameter="_spring_security_remember_me" <!--1-->
-                remember-me-cookie="SPRING_SECURITY_REMEMBER_ME_COOKIE" <!--2-->
-    />
-</http>
-----
-
-<1> If the configuration does not specify the remember-me-parameter, then it should be explicitly stated
-<2> If the configuration does not specify the remember-me-cookie, then it should be explicitly stated
-
-**Alternatively**, the application can be updated to use the new defaults.
-For example, one might update their log in form to look like the following:
-
-.login.html
-[source,xml]
-----
-<c:url var="loginUrl" value="/login"/> <!--2-->
-<form action="${loginUrl}" method="post">
-    ...
-
-    <p><label for="remember-me">Remember Me</label></p>
-    <input type="checkbox" id="remember-me" name="remember-me"/> <!--1-->
-
-    <div>
-        <input name="submit" type="submit"/>
-    </div>
-</form>
-----
-
-<1> If the configuration does not specify the remember-me-parameter, then update the HTTP parameter name to be remember-me
-
-NOTE: This approach means that previously remembered users will be forgotten since the remember me cookie name will change.
-If you are fine with users needing to authenticate again, then nothing is required.
-If you do not want users to authenticate, then the cookie name must be set to SPRING_SECURITY_REMEMBER_ME_COOKIE as illustrated above.
-
-[[m3to4-filter-urls]]
-== Migrate Default Filter URLs
-
-A number of servlet Filter's had their default URLs switched to help guard against information leakage.
-
-[[m3to4-filter-urls-cas]]
-=== CasAuthenticationFilter
-
-The `CasAuthenticationFilter` filterProcessesUrl property default value changed from "/j_spring_cas_security_check" to "/login/cas".
-This means if the filterProcessesUrl property is not explicitly specified, then the configuration will need updated.
-For example, if an application using Spring Security 3.2.x contains a configuration similar to the following:
-
-[source,xml]
-----
-<b:bean id="casFilter"
-            class="org.springframework.security.cas.web.CasAuthenticationFilter">
-    <b:property name="authenticationManager" ref="authenticationManager"/>
-</b:bean>
-----
-
-The configuration will need to be updated to something similar to the following when Spring Security 4.x:
-
-[source,xml]
-----
-<b:bean id="casFilter"
-            class="org.springframework.security.cas.web.CasAuthenticationFilter">
-    <b:property name="authenticationManager" ref="authenticationManager"/>
-    <b:property name="filterProcessesUrl" value="/j_spring_cas_security_check"/>
-</b:bean>
-----
-
-*Alternatively*, the `ServiceProperties` can be updated to use the new default:
-
-[source,xml]
-----
-<bean id="serviceProperties"
-      class="org.springframework.security.cas.ServiceProperties">
-  <property name="service"
-      value="https://example.com/cas-sample/login/cas"/>
-</bean>
-----
-
-[[m3to4-filter-urls-switchuser]]
-=== SwitchUserFilter
-
-* The `SwitchUserFilter` switchUserUrl property default value changed from "/j_spring_security_switch_user" to "/login/impersonate".
-This means if the switchUserUrl property is not explicitly specified, then the configuration will need updated.
-* The `SwitchUserFilter` exitUserUrl property default value changed from "/j_spring_security_exit_user" to "/logout/impersonate".
-This means if the exitUserUrl property is not explicitly specified, then the configuration will need updated.
-
-For example, if an application using Spring Security 3.2.x contains a configuration similar to the following:
-
-[source,xml]
-----
-<b:bean id="switchUserProcessingFilter" class="org.springframework.security.web.authentication.switchuser.SwitchUserFilter">
-    <b:property name="userDetailsService" ref="userDetailsService" />
-    <b:property name="targetUrl" value="/" />
-</b:bean>
-----
-
-The configuration will need to be updated to something similar to the following when Spring Security 4.x:
-
-[source,xml]
-----
-<bean id="switchUserProcessingFilter" class="org.springframework.security.web.authentication.switchuser.SwitchUserFilter">
-    <property name="switchUserUrl" value="/j_spring_security_switch_user" />
-    <property name="exitUserUrl" value="/j_spring_security_exit_user" />
-
-    <property name="userDetailsService" ref="userDetailsService" />
-    <property name="targetUrl" value="/" />
- </bean>
-----
-
-*Alternatively*, the URL's within the application can be updated from:
-
-* "/j_spring_security_switch_user" to "/login/impersonate"
-* "/j_spring_security_exit_user" to "/logout/impersonate"
-
-[[m3to4-header]]
-== HTTP Response Header Configuration Changes
-
-In Spring Security 3.x the HTTP Response Header configuration was difficult to customize.
-If an application overrode a single default, then all of the other defaults would be disabled.
-This was unintuitive, error prone, and most importantly not very secure.
-
-Spring Security 4.x has changed both the Java Configuration and XML Configuration to require explicit disabling of defaults.
-Additionally, it has made customizing a single default much easier.
-
-If an application has customized the HTTP Response Header Configuration in any way, they are impacted by this change.
-If the application used the defaults, then they are not impacted by this change.
-
-A detailed description of how to configure Security HTTP Response Headers can be found in the <<headers,reference>>.
-Below we highlight the changes in configuring the Security HTTP Response Headers between 3.x and 4.x.
-
-* <<m3to4-header-xml,Migrating XML Based Configuration>>
-* <<m3to4-header-jc,Migrating Java Based Configuration>>
-
-[[m3to4-header-xml]]
-=== XML Namespace HTTP Response Header Samples
-
-In Spring Security 3.x, the following configuration
-
-[source,xml]
-----
-<http>
-   <headers>
-       <frame-options policy="SAMEORIGIN"/>
-   </headers>
-
-   ...
-</http>
-----
-
-would add the following header:
-
-[source,http]
-----
-X-Frame-Options: SAMEORIGIN
-----
-
-In Spring Security 4.x, the same configuration would add
-
-[source,http]
-----
-Cache-Control: no-cache, no-store, max-age=0, must-revalidate
-Pragma: no-cache
-Expires: 0
-X-Content-Type-Options: nosniff
-Strict-Transport-Security: max-age=31536000 ; includeSubDomains
-X-Frame-Options: SAMEORIGIN
-X-XSS-Protection: 1; mode=block
-----
-
-If we want to the configuration the same, we must explicitly disable the other defaults.
-
-[source,xml]
-----
-<http>
-   ...
-   <headers defaults-disabled="true">
-       <frame-options policy="SAMEORIGIN"/>
-   </headers>
-----
-
-would add the following header:
-
-[source,http]
-----
-X-Frame-Options: SAMEORIGIN
-----
-
-[[m3to4-header-jc]]
-=== Java Configuration HTTP Response Header Samples
-
-[[m3to4-header-jc-defaults-preserved]]
-==== Migrate Headers Java Config Defaults Preserved
-
-In Spring Security 3.x, the following configuration
-
-[source,java]
-----
-http
-  // ...
-  .headers()
-    .addHeaderWriter(new XFrameOptionsHeaderWriter(XFrameOptionsMode.SAMEORIGIN));
-----
-
-would add the following header:
-
-[source,http]
-----
-X-Frame-Options: SAMEORIGIN
-----
-
-In Spring Security 4.x, the same configuration would add
-
-[source,http]
-----
-Cache-Control: no-cache, no-store, max-age=0, must-revalidate
-Pragma: no-cache
-Expires: 0
-X-Content-Type-Options: nosniff
-Strict-Transport-Security: max-age=31536000 ; includeSubDomains
-X-Frame-Options: SAMEORIGIN
-X-XSS-Protection: 1; mode=block
-----
-
-If we want to the configuration the same, we must explicitly disable the other defaults.
-
-[source,java]
-----
-http
-  // ...
-  .headers()
-     // do not use any default headers unless explicitly listed
-    .defaultsDisabled()
-    .frameOptions()
-        .sameOrigin();
-----
-
-would add the following header:
-
-[source,http]
-----
-X-Frame-Options: SAMEORIGIN
-----
-
-
-[[m3to4-header-jc-]]
-==== Migrate Headers Java Config Method Chaining
-
-In Spring Security 3.x, the following configuration
-
-[source,java]
-----
-http
-  // ...
-  .headers()
-    .cacheControl()
-    .frameOptions();
-----
-
-would compile succesfully.
-However, Spring Security 4.x it will not compile.
-This is due to the fact that additional options needed to be added to support customizing the configuration.
-Instead, we must chain the headers customizations with `.and()`.
-For example:
-
-[source,java]
-----
-http
-  // ...
-  .headers()
-     // do not use any default headers unless explicitly listed
-    .defaultsDisabled()
-    .cacheControl().and()
-    .frameOptions();
-----
-
-[[m3to4-deprecations]]
-== Deprecations
-
-A number of deprecations were removed in Spring Security 4.
-The following section describes how to migrate the removal of all deprecations.
-
-[[m3to4-deprecations-acl]]
-=== spring-security-acl
-
-[[m3to4-deprecations-acl-aclimpl]]
-==== AclImpl
-
-AclImpl had a deprecated constructor removed. Specifically, the constructor that defaults the `PermissionGrantingStrategy` was removed:
-
-[source,java]
-----
-@Deprecated
-public AclImpl(ObjectIdentity objectIdentity, Serializable id, AclAuthorizationStrategy aclAuthorizationStrategy,
-               AuditLogger auditLogger, Acl parentAcl, List<Sid> loadedSids, boolean entriesInheriting, Sid owner) {
-    ...
-}
-----
-
-This means that an AclImpl was being created with this constructor:
-
-[source,java]
-----
-new AclImpl(objectIdentity, id, aclAuthorizationStrategy, auditLogger,
-            parentAcl, loadedSids, entriesInheriting, owner);
-----
-
-it needs to be updated to pass in the `PermissionGrantingStrategy` instead of the `AuditLogger`
-
-
-[source,java]
-----
-PermissionGrantingStrategy permissionGrantingStrategy =
-   new DefaultPermissionGrantingStrategy(auditLogger);
-new AclImpl(objectIdentity, id, aclAuthorizationStrategy, permissionGrantingStrategy,
-            parentAcl, loadedSids, entriesInheriting, owner);
-----
-
-[[m3to4-deprecations-acl-ehcachebasedaclcache]]
-==== EhCacheBasedAclCache
-
-`EhCacheBasedAclCache` had a deprecated constructor removed. Specifically, the constructor that defaults the `PermissionGrantingStrategy` was removed:
-
-[source,java]
-----
-@Deprecated
-public EhCacheBasedAclCache(Ehcache cache) {
-    ...
-}
-----
-
-This means that an `EhCacheBasedAclCache` was being created with this constructor:
-
-[source,java]
-----
-new EhCacheBasedAclCache(ehCache);
-----
-
-it needs to be updated to pass in the `PermissionGrantingStrategy` too:
-
-
-[source,java]
-----
-PermissionGrantingStrategy permissionGrantingStrategy =
-   new DefaultPermissionGrantingStrategy(auditLogger);
-new EhCacheBasedAclCache(ehCache, permissionGrantingStrategy);
-----
-
-[[m3to4-deprecations-cas]]
-=== spring-security-cas
-
-[[m3to4-deprecations-cas-serviceauthenticationdetailssource]]
-==== ServiceAuthenticationDetailsSource
-
-`ServiceAuthenticationDetailsSource` removed the deprecated construtors that defaulted the `ServiceProperties`.
-
-[source,java]
-----
-@Deprecated
-public ServiceAuthenticationDetailsSource() {
-    ...
-}
-
-@Deprecated
-public ServiceAuthenticationDetailsSource(final String artifactParameterName) {
-    ...
-}
-----
-
-This means that an `ServiceAuthenticationDetailsSource` was being created with these constructors:
-
-[source,java]
-----
-new ServiceAuthenticationDetailsSource();
-
-new ServiceAuthenticationDetailsSource(artifactId);
-----
-
-it needs to be updated to pass in the `ServiceProperties` as shown below:
-
-
-[source,java]
-----
-new ServiceAuthenticationDetailsSource(serviceProperties);
-
-new ServiceAuthenticationDetailsSource(serviceProperties, artifactId);
-----
-
-[[m3to4-deprecations-config]]
-=== spring-security-config
-
-
-[[m3to4-deprecations-config-fids]]
-==== filter-invocation-definition-source
-
-The XML element `filter-invocation-definition-source` was removed in favor of <<nsa-filter-security-metadata-source,filter-security-metadata-source>>.
-This means if you have something like this:
-
-[source,xml]
-----
-<filter-invocation-definition-source ...>
-    ...
-</filter-invocation-definition-source>
-----
-
-it needs to be replaced with:
-
-[source,xml]
-----
-<filter-security-metadata-source ...>
-    ...
-</filter-security-metadata-source>
-----
-
-[[m3to4-deprecations-config-http-adp]]
-==== http@access-denied-page
-The XML attribute `http@access-denied-page` was removed in favor of <<nsa-access-denied-handler-error-page,access-denied-handler@error-page>>.
-This means if you have something like this:
-
-
-[source,xml]
-----
-<http ... access-denied-page="/denied">
-    ...
-</http>
-----
-
-it needs to be replaced with:
-
-[source,xml]
-----
-<http ...>
-    <access-denied-handler error-page="/denied"/>
-</http>
-----
-
-[[m3to4-deprecations-config-http-pt]]
-==== http@path-type
-The XML attribute `http@path-type` was removed in favor of <<nsa-http-request-matcher,http@request-matcher>>.
-This means if you have something like this:
-
-
-[source,xml]
-----
-<http ... path-type="regex">
-    ...
-</http>
-----
-
-it needs to be replaced with:
-
-[source,xml]
-----
-<http ... request-matcher="regex">
-    ...
-</http>
-----
-
-[[m3to4-deprecations-config-fcm-pt]]
-==== filter-chain-map@path-type
-The XML attribute `filter-chain-map@path-type` was removed in favor of <<nsa-filter-chain-map-request-matcher,filter-chain-map@request-matcher>>.
-This means if you have something like this:
-
-
-[source,xml]
-----
-<filter-chain-map ... path-type="regex">
-    ...
-</filter-chain-map>
-----
-
-it needs to be replaced with:
-
-[source,xml]
-----
-<filter-chain-map ... request-matcher="regex">
-    ...
-</filter-chain-map>
-----
-
-[[m3to4-deprecations-config-sms-pt]]
-==== filter-security-metadata-source@path-type
-The XML attribute `filter-security-metadata-source@path-type` was removed in favor of <<nsa-filter-security-metadata-source-request-matcher,filter-security-metadata-source@request-matcher>>.
-This means if you have something like this:
-
-
-[source,xml]
-----
-<filter-security-metadata-source ... path-type="regex">
-    ...
-</filter-security-metadata-source>
-----
-
-it needs to be replaced with:
-
-[source,xml]
-----
-<filter-security-metadata-source ... request-matcher="regex">
-    ...
-</filter-security-metadata-source>
-----
-
-[[m3to4-deprecations-core]]
-=== spring-security-core
-
-[[m3to4-deprecations-core-securityconfig]]
-==== SecurityConfig
-
-`SecurityConfig.createSingleAttributeList(String)` was removed in favor of using `SecurityConfig.createList(String...)`.
-This means if you have something like this:
-
-[source,java]
-----
-List<ConfigAttribute> attrs =
-    SecurityConfig.createSingleAttributeList("ROLE_USER");
-----
-
-needs to be replaced with:
-
-[source,java]
-----
-List<ConfigAttribute> attrs =
-    SecurityConfig.createList("ROLE_USER");
-----
-
-[[m3to4-deprecations-core-udsw]]
-==== UserDetailsServiceWrapper
-
-`UserDetailsServiceWrapper` was deprecated in favor of using `RoleHierarchyAuthoritiesMapper`.
-For example, if you have something like this:
-
-[source,xml]
-----
-<authentication-manager>
-    <authentication-provider user-service-ref="userDetailsServiceWrapper"/>
-</authentication-manager>
-
-<b:bean id="userDetailsServiceWrapper" class="org.springframework.security.access.hierarchicalroles.UserDetailsServiceWrapper">
-    <b:property name="userDetailsService" ref="userDetailsService"/>
-    <b:property name="roleHierarchy" ref="roleHierarchy"/>
-</b:bean>
-
-<b:bean id="roleHierarchy" class="org.springframework.security.access.hierarchicalroles.RoleHierarchyImpl">
-    <b:property name="hierarchy">
-        <b:value>
-            ROLE_ADMIN > ROLE_USER
-        </b:value>
-    </b:property>
-</b:bean>
-----
-
-then it needs to be migrated with something like this:
-
-TBD
-
-
-[[m3to4-deprecations-core-udw]]
-==== UserDetailsWrapper
-`UserDetailsWrapper` was deprecated in favor of using `RoleHierarchyAuthoritiesMapper`.
-Typically users would not use the `UserDetailsWrapper` directly. However, if they are they can use `RoleHierarchyAuthoritiesMapper`
-For example, if the following code is present:
-
-[source,java]
-----
-UserDetailsWrapper authenticate = new UserDetailsWrapper(userDetails, roleHiearchy);
-----
-
-then it needs to be replaced by:
-
-[source,java]
-----
-Collection<GrantedAuthority> allAuthorities =
-    roleHiearchy.getReachableGrantedAuthorities(userDetails.getAuthorities());
-UserDetails authenticate =
-    new User(userDetails.getUsername(), userDetails.getPassword(), allAuthorities);
-----
-
-[[m3to4-deprecations-core-aadm]]
-==== AbstractAccessDecisionManager
-
-The default constructor for `AbstractAccessDecisionManager` has been deprecated along with the `setDecisionVoters` method.
-Naturally, this impacts the subclasses `AffirmativeBased`, `ConsensusBased`, and `UnanimousBased`.
-For example, this means that if you are using the following:
-
-[source,java]
-----
-AffirmativeBased affirm = new AffirmativeBased();
-affirm.setDecisionVoters(voters);
-----
-
-it needs to be migrated to:
-
-[source,java]
-----
-AffirmativeBased affirm = new AffirmativeBased(voters);
-----
-
-This type of migration also applies to XML based configuration.
-For example, if you are using the following:
-
-[source,xml]
-----
-<b:bean class="org.springframework.security.access.vote.UnanimousBased">
-    <b:property name="decisionVoters" ref="voters"/>
-</b:bean>
-----
-
-then it needs to be migrated to:
-
-[source,xml]
-----
-<b:bean class="org.springframework.security.access.vote.UnanimousBased">
-    <b:constructor-arg ref="voters"/>
-</b:bean>
-----
-
-[[m3to4-deprecations-core-ae]]
-==== AuthenticationException
-
-The constructor that accepts extraInformation within `AuthenticationException` was removed to prevent accidental leaking of the `UserDetails`.
-Specifically, the following we removed.
-
-[source,java]
-----
-public AccountExpiredException(String msg, Object extraInformation) {
-...
-}
-----
-
-This impacts the subclasses `AccountStatusException`, `AccountExpiredException`, `BadCredentialsException`, `CredentialsExpiredException`, `DisabledException`, `LockedException`, and `UsernameNotFoundException`.
-If use are using any of these constructors, simply remove the additional argument.
-For example, the following is changed from:
-
-[source,java]
-----
-new LockedException("Message", userDetails);
-----
-
-to:
-
-[source,java]
-----
-new LockedException("Message");
-----
-
-
-[[m3to4-deprecations-core-aap]]
-==== AnonymousAuthenticationProvider
-
-`AnonymousAuthenticationProvider` default constructor and `setKey` method was deprecated in favor of using constructor injection.
-For example, if you have the following:
-
-[source,java]
-----
-AnonymousAuthenticationProvider provider = new AnonymousAuthenticationProvider();
-provider.setKey(key);
-----
-
-it should be changed to:
-
-[source,java]
-----
-AnonymousAuthenticationProvider provider = new AnonymousAuthenticationProvider(key);
-----
-
-[[m3to4-deprecations-core-adsi]]
-==== AuthenticationDetailsSourceImpl
-
-`AuthenticationDetailsSourceImpl` was deprecated in favor of writing a custom `AuthenticationDetailsSource`.
-For example, if you have the following:
-
-[source,java]
-----
-AuthenticationDetailsSourceImpl source = AuthenticationDetailsSourceImpl();
-source.setClazz(CustomSource.class);
-----
-
-You should implement `AuthenticationDetailsSource` directly to return `CustomSource`:
-
-[source,java]
-----
-public CustomSourceAuthenticationDetailsSource implements AuthenticationDetailsSource<Object, Object> {
-
-    public Object buildDetails(Object context) {
-        return new CustomSource(context);
-    }
-}
-----
-
-[[m3to4-deprecations-core-pm]]
-==== ProviderManager
-
-`ProviderManager` has removed the deprecated default constructor and the correspdonding setter methods in favor of using constructor injection.
-It has also removed the clearExtraInformation property since the `AuthenticationException` had the extra information property removed.
-
-For example, if you have something like the following:
-
-[source,java]
-----
-ProviderManager provider = new ProviderManager();
-provider.setParent(parent);
-provider.setProviders(providers);
-provider.setClearExtraInformation(true);
-----
-
-then it should be changed to:
-
-[source,java]
-----
-ProviderManager provider = new ProviderManager(parent, providers);
-----
-
-[[m3to4-deprecations-core-rmap]]
-==== RememberMeAuthenticationProvider
-`RememberMeAuthenticationProvider` had the default constructor and the `setKey` method removed in favor of constructor injection.
-For example:
-
-[source,java]
-----
-RememberMeAuthenticationProvider provider = new RememberMeAuthenticationProvider();
-provider.setProvider(key);
-----
-
-should be migrated to:
-
-[source,java]
-----
-RememberMeAuthenticationProvider provider = new RememberMeAuthenticationProvider(key);
-----
-
-[[m3to4-deprecations-core-gai]]
-==== GrantedAuthorityImpl
-
-`GrantedAuthorityImpl` was removed in favor of `SimpleGrantedAuthority` or implementing your own.
-For example:
-
-[source,java]
-----
-new GrantedAuthorityImpl(role);
-----
-
-should be replaced with
-
-[source,java]
-----
-new SimpleGrantedAuthority(role);
-----
-
-[[m3to4-deprecations-core-imdi]]
-==== InMemoryDaoImpl
-
-`InMemoryDaoImpl` was replaced in favor of `InMemoryUserDetailsManager`
-
-[[m3to4-deprecations-openid]]
-==== spring-security-openid
-
-[[m3to4-deprecations-openid-oi4jc]]
-==== OpenID4JavaConsumer
-
-The `OpenID4JavaConsumer` constructors that accept `List<OpenIDAttribute>` have been removed in favor of using an `AxFetchListFactory`.
-For example:
-
-[source,java]
-----
-new OpenIDJavaConsumer(attributes);
-----
-
-should be replaced with:
-
-[source,java]
-----
-Map<String, List<OpenIDAttribute>> regexMap = new HashMap<String,List<OpenIDAttribute>>();
-regexMap.put(".*", attributes);
-RegexBasedAxFetchListFactory factory = new RegexBasedAxFetchListFactory(regexMap);
-new OpenIDJavaConsumer(factory);
-----
-
-[[m3to4-deprecations-taglibs]]
-=== spring-security-taglibs
-
-Spring Security's authorize JSP tag deprecated the properties `ifAllGranted`, `ifAnyGranted`, and `ifNotGranted` in favor of using expressions.
-
-For example:
-
-[source,xml]
-----
-<sec:authorize ifAllGranted="ROLE_A,ROLE_B">
-  Must have ROLE_A and ROLE_B
-</sec:authorize>
-<sec:authorize ifAnyGranted="ROLE_A,ROLE_B">
-  Must have ROLE_A or ROLE_B
-</sec:authorize>
-<sec:authorize ifNotGranted="ROLE_A,ROLE_B">
-  Must not have ROLE_A
-</sec:authorize>
-----
-
-can be replaced with:
-
-[source,xml]
-----
-<sec:authorize access="hasRole('ROLE_A') and hasRole('ROLE_B')">
-  Must have ROLE_A and ROLE_B
-</sec:authorize>
-<sec:authorize access="hasAnyRole('ROLE_A','ROLE_B')">
-  Must have ROLE_A or ROLE_B
-</sec:authorize>
-<sec:authorize ifNotGranted="!hasRole('ROLE_A')">
-  Must not have ROLE_A
-</sec:authorize>
-----
-
-[[m3to4-deprecations-web]]
-=== spring-security-web
-
-[[m3to4-deprecations-web-fcp]]
-==== FilterChainProxy
-
-`FilterChainProxy` removed the `setFilterChainMap` method in favor of constructor injection.
-For example, if you have the following:
-
-[source,java]
-----
-FilterChainProxy filter = new FilterChainProxy();
-filter.setFilterChainMap(filterChainMap);
-----
-
-it should be replaced with:
-
-[source,java]
-----
-FilterChainProxy filter = new FilterChainProxy(filterChainMap);
-----
-
-`FilterChainProxy` also removed `getFilterChainMap` in favor of using `getFilterChains` for example:
-
-[source,java]
-----
-FilterChainProxy filter = ...
-Map<RequestMatcher,List<Filter>> mappings = filter.getFilterChainMap();
-----
-
-should be replaced with
-
-
-[source,java]
-----
-FilterChainProxy filter = ...
-List<SecurityFilterChain> mappings = filter.getFilterChains();
-----
-
-[[m3to4-deprecations-web-etf]]
-==== ExceptionTranslationFilter
-
-The default constructor for `ExceptionTranslationFilter` and the `setAuthenticationEntryPoint` method was removed in favor of using constructor injection.
-
-[source,java]
-----
-ExceptionTranslationFilter filter = new ExceptionTranslationFilter();
-filter.setAuthenticationEntryPoint(entryPoint);
-filter.setRequestCache(requestCache);
-----
-
-can be replaced with
-
-[source,java]
-----
-ExceptionTranslationFilter filter = new ExceptionTranslationFilter(entryPoint, requestCache);
-----
-
-[[m3to4-deprecations-web-aapf]]
-==== AbstractAuthenticationProcessingFilter
-
-`AbstractAuthenticationProcessingFilter` had its `successfulAuthentication(HttpServletRequest,HttpServletResponse,Authentication)` method removed.
-So if your application overrides the following method:
-
-[source,java]
-----
-protected void successfulAuthentication(HttpServletRequest request, HttpServletResponse response,
-             Authentication authResult) throws IOException, ServletException {
-}
-----
-
-it should be replaced with:
-
-[source,java]
-----
-protected void successfulAuthentication(HttpServletRequest request, HttpServletResponse response,
-             FilterChain chain, Authentication authResult) throws IOException, ServletException {
-}
-----
-
-[[m3to4-deprecations-web-aaf]]
-==== AnonymousAuthenticationFilter
-
-`AnonymousAuthenticationFilter` had the default constructor and the `setKey` and `setPrincipal` methods removed in favor of constructor injection.
-For example:
-
-[source,java]
-----
-AnonymousAuthenticationFilter filter = new AnonymousAuthenticationFilter();
-filter.setKey(key);
-filter.setUserAttribute(attrs);
-----
-
-should be replaced with:
-
-[source,java]
-----
-AnonymousAuthenticationFilter filter =
-    new AnonymousAuthenticationFilter(key,attrs.getPassword(),attrs.getAuthorities());
-----
-
-[[m3to4-deprecations-web-luaep]]
-==== LoginUrlAuthenticationEntryPoint
-
-The `LoginUrlAuthenticationEntryPoint` default constructor and the `setLoginFormUrl` method was removed in favor of constructor injection.
-For example:
-
-[source,java]
-----
-LoginUrlAuthenticationEntryPoint entryPoint = new LoginUrlAuthenticationEntryPoint();
-entryPoint.setLoginFormUrl(loginFormUrl);
-----
-should be replaced with
-
-[source,java]
-----
-LoginUrlAuthenticationEntryPoint entryPoint = new LoginUrlAuthenticationEntryPoint(loginFormUrl);
-----
-
-[[m3to4-deprecations-web-pagauds]]
-==== PreAuthenticatedGrantedAuthoritiesUserDetailsService
-
-`PreAuthenticatedGrantedAuthoritiesUserDetailsService` removed `createuserDetails` in favor of `createUserDetails`.
-
-[[m3to4-deprecations-web-arms]]
-==== AbstractRememberMeServices
-
-`AbstractRememberMeServices` and its subclasses `PersistentTokenBasedRememberMeServices` and `TokenBasedRememberMeServices` removed the default constructor and the `setKey` and `setUserDetailsService` methods in favor of constructor injection.
-For example:
-
-[source,java]
-----
-PersistentTokenBasedRememberMeServices services = new PersistentTokenBasedRememberMeServices();
-services.setKey(key);
-services.setUserDetailService(userDetailsService);
-services.setTokenRepository(tokenRepository);
-----
-
-should be replaced with
-
-[source,java]
-----
-PersistentTokenBasedRememberMeServices services =
-    new PersistentTokenBasedRememberMeServices(key, userDetailsService, tokenRepository);
-----
-
-[[m3to4-deprecations-web-rmaf]]
-==== RememberMeAuthenticationFilter
-
-`RememberMeAuthenticationFilter` default constructor and the `setAuthenticationManager` and `setRememberMeServices` methods were removed in favor of constructor injection.
-
-[source,java]
-----
-RememberMeAuthenticationFilter filter = new RememberMeAuthenticationFilter();
-filter.setAuthenticationManager(authenticationManager);
-filter.setRememberServices(rememberMeServices);
-----
-
-should be replaced with
-
-[source,java]
-----
-RememberMeAuthenticationFilter filter =
-    new RememberMeAuthenticationFilter(authenticationManager,rememberMeServices);
-----
-
-[[m3to4-deprecations-web-tbrms]]
-==== TokenBasedRememberMeServices
-
-`TokenBasedRememberMeServices` default constructor and the `setKey` and `setUserDetailsService` methods were removed in favor of constructor injection.
-
-[source,java]
-----
-TokenBasedRememberMeServices services = new TokenBasedRememberMeServices();
-services.setKey(key);
-services.setUserDetailsService(userDetailsService);
-----
-
-should be replaced with
-
-[source,java]
-----
-TokenBasedRememberMeServices services =
-    new TokenBasedRememberMeServices(key,userDetailsService);
-----
-
-[[m3to4-deprecations-web-cscs]]
-==== ConcurrentSessionControlStrategy
-
-`ConcurrentSessionControlStrategy` was replaced with `ConcurrentSessionControlAuthenticationStrategy`.
-Previously `ConcurrentSessionControlStrategy` could not be decoupled from `SessionFixationProtectionStrategy`.
-Now it is completely decoupled.
-For example, the following:
-
-[source,java]
-----
-ConcurrentSessionControlStrategy strategy = new ConcurrentSessionControlStrategy(sessionRegistry);
-----
-
-can be replaced with
-
-[source,java]
-----
-List<SessionAuthenticationStrategy> delegates = new ArrayList<SessionAuthenticationStrategy>();
-delegates.add(new ConcurrentSessionControlAuthenticationStrategy(sessionRegistry));
-delegates.add(new SessionFixationProtectionStrategy());
-delegates.add(new RegisterSessionAuthenticationStrategy(sessionRegistry));
-CompositeSessionAuthenticationStrategy strategy = new CompositeSessionAuthenticationStrategy(delegates);
-----
-
-[[m3to4-deprecations-web-sfps]]
-==== SessionFixationProtectionStrategy
-
-`SessionFixationProtectionStrategy` removed `setRetainedAttributes` method in favor of users subclassing `SessionFixationProtectionStrategy` and overriding `extractAttributes` method.
-
-[[m3to4-deprecations-web-baf]]
-==== BasicAuthenticationFilter
-
-`BasicAuthenticationFilter` default constructor and the `setAuthenticationManager` and `setRememberMeServices` methods were removed in favor of constructor injection.
-
-[source,java]
-----
-BasicAuthenticationFilter filter = new BasicAuthenticationFilter();
-filter.setAuthenticationManager(authenticationManager);
-filter.setAuthenticationEntryPoint(entryPoint);
-filter.setIgnoreFailure(ignoreFailure);
-----
-
-should be replaced with
-
-[source,java]
-----
-BasicAuthenticationFilter filter =
-    new BasicAuthenticationFilter(authenticationManager,entryPoint, ignoreFailure);
-----
-
-[[m3to4-deprecations-web-scpf]]
-==== SecurityContextPersistenceFilter
-
-`SecurityContextPersistenceFilter` removed the `setSecurityContextRepository` in favor of constructor injection.
-For example:
-
-[source,java]
-----
-SecurityContextPersistenceFilter filter = new SecurityContextPersistenceFilter();
-filter.setSecurityContextRepository(securityContextRepository);
-----
-
-should be replaced with
-
-[source,java]
-----
-SecurityContextPersistenceFilter filter = new SecurityContextPersistenceFilter(securityContextRepository);
-----
-
-[[m3to4-deprecations-web-rcaf]]
-==== RequestCacheAwareFilter
-
-`RequestCacheAwareFilter` removed the `setRequestCache` in favor of constructor injection.
-For example:
-
-[source,java]
-----
-RequestCacheAwareFilter filter = new RequestCacheAwareFilter();
-filter.setRequestCache(requestCache);
-----
-
-should be replaced with
-
-[source,java]
-----
-RequestCacheAwareFilter filter = new RequestCacheAwareFilter(requestCache);
-----
-
-[[m3to4-deprecations-web-csf]]
-==== ConcurrentSessionFilter
-
-`ConcurrentSessionFilter` removed the default constructor and the `setExpiredUrl` and `setSessionRegistry` methods in favor of constructor injection.
-For example:
-
-[source,java]
-----
-ConcurrentSessionFilter filter = new ConcurrentSessionFilter();
-filter.setSessionRegistry(sessionRegistry);
-filter.setExpiredUrl(expiredUrl);
-----
-
-should be replaced with
-
-[source,java]
-----
-ConcurrentSessionFilter filter = new ConcurrentSessionFilter(sessionRegistry,expiredUrl);
-----
-
-[[m3to4-deprecations-web-smf]]
-==== SessionManagementFilter
-
-`SessionManagementFilter` removed the `setSessionAuthenticationStrategy` method in favor of constructor injection.
-For example:
-
-[source,java]
-----
-SessionManagementFilter filter = new SessionManagementFilter(securityContextRepository);
-filter.setSessionAuthenticationStrategy(sessionAuthenticationStrategy);
-----
-
-should be replaced with
-
-[source,java]
-----
-SessionManagementFilter filter = new SessionManagementFilter(securityContextRepository, sessionAuthenticationStrategy);
-----
-
-[[m3to4-deprecations-web-rm]]
-==== RequestMatcher
-
-The `RequestMatcher` and its implementations have moved from the package `org.springframework.security.web.util` to `org.springframework.security.web.util.matcher`.
-Specifically
-
-* `org.springframework.security.web.util.RequestMatcher` -> `org.springframework.security.web.util.matcher.RequestMatcher`
-* `org.springframework.security.web.util.AntPathRequestMatcher` -> `org.springframework.security.web.util.matcher.AntPathRequestMatcher`
-* `org.springframework.security.web.util.AnyRequestMatcher` -> `org.springframework.security.web.util.matcher.AnyRequestMatcher.INSTANCE`
-* `org.springframework.security.web.util.ELRequestMatcher` -> `org.springframework.security.web.util.matcher.ELRequestMatcher`
-* `org.springframework.security.web.util.IpAddressMatcher` -> `org.springframework.security.web.util.matcher.IpAddressMatcher`
-* `org.springframework.security.web.util.RequestMatcherEditor` -> `org.springframework.security.web.util.matcher.RequestMatcherEditor`
-* `org.springframework.security.web.util.RegexRequestMatcher` -> `org.springframework.security.web.util.matcher.RegexRequestMatcher`
-
-[[m3to4-deprecations-web-wseh]]
-==== WebSecurityExpressionHandler
-
-`WebSecurityExpressionHandler` was removed in favor of using `SecurityExpressionHandler<FilterInvocation>`.
-
-This means if you are using:
-
-[source,java]
-----
-WebSecurityExpressionHandler handler = ...
-----
-
-it needs to be updated to
-
-[source,java]
-----
-SecurityExpressionHandler<FilterInvocation> handler = ...
-----
-
-[[m3to4-role-prefixing]]
-== Automatic ROLE_ prefixing
-
-Spring Security 4 made the use of ROLE_ consistent.
-
-Not everyone is impacted by this change.
-You are impacted if user's roles are *not* prefixed with ROLE_.
-If all of your user's roles are prefixed with ROLE_ you are NOT impacted.
-
-For details on this change and how to migrate, refer to the https://jira.spring.io/browse/SEC-2758[SEC-2758] description.

docs/manual/src/docs/asciidoc/index.adoc

@@ -428,7 +428,20 @@ is the same as this more concise configuration:
 * https://jira.spring.io/browse/SEC-2790[Deprecate @EnableWebMvcSecurity] - by updating the minimum Spring Version, we can now allow defaulting MVC integration with `@EnableWebSecurity` but still allow it to be overridden
 
 
-include::{include-dir}/migrate-3-to-4.adoc[leveloffset=+2]
+[[m3to4]]
+=== Migrating from 3.x to 4.x
+
+As exploits against applications evolve, so must Spring Security.
+As a major release version, the Spring Security team took the opportunity to make some non-passive changes which focus on:
+
+* Ensuring Spring Security is more https://www.owasp.org/index.php/Establish_secure_defaults[secure by default]
+* Minimizing https://www.owasp.org/index.php/Information_Leakage[Information Leakage]
+* Removing deprecated APIs
+
+For complete details on migrating from Spring Security 3 to Spring Security 4 refer to one of the guides below:
+
+* http://docs.spring.io/spring-security/site/migrate/3-to-4/html5/migrate-3-to-4-xml.html[Migrating from Spring Security 3.x to 4.x (XML Configuration)]
+* http://docs.spring.io/spring-security/site/migrate/3-to-4/html5/migrate-3-to-4-jc.html[Migrating from Spring Security 3.x to 4.x (Java Configuration)]
 
 [[jc]]
 == Java Configuration