From b262c198d8cc1f374ee93081ff5859e5a8a9ef9e Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Fri, 20 Mar 2015 14:14:55 -0500 Subject: [PATCH] SEC-2782: Polish Migrating from 3 to 4 Guide --- .../asciidoc/_includes/migrate-3-to-4.adoc | 1476 ----------------- docs/manual/src/docs/asciidoc/index.adoc | 15 +- 2 files changed, 14 insertions(+), 1477 deletions(-) delete mode 100644 docs/manual/src/docs/asciidoc/_includes/migrate-3-to-4.adoc diff --git a/docs/manual/src/docs/asciidoc/_includes/migrate-3-to-4.adoc b/docs/manual/src/docs/asciidoc/_includes/migrate-3-to-4.adoc deleted file mode 100644 index 1ac4dd8d69..0000000000 --- a/docs/manual/src/docs/asciidoc/_includes/migrate-3-to-4.adoc +++ /dev/null @@ -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-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 - -The <> 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] ----- - - - - ... - ----- - -<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] ----- - - - - ... - ----- - -<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] ----- - - - - ... - ----- - -[[m3to4-xmlnamespace-form-login]] -=== Migrating - -If the `` 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 <> attribute default value changed from j_username to username. If an application explicitly provides the attribute, no action is required for the migration. -* The <> attribute default value changed from j_password to password. If an application explicitly provides the attribute, no action is required for the migration. -* The <> 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 <> 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] ----- - - ... - - ----- - -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] ----- - - ... - - password-parameter="j_password" - login-processing-url="/j_spring_security_check" - authentication-failure-url="/login?login_error=1" - /> - ----- - -<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] ----- - -

Invalid username / password

- - -
-

- - -

- - -
- -
-
----- - -<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 - -The <> 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] ----- - - - ... - ----- - -<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] ----- - - - ... - ----- - -<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] ----- - -
- -
- - -
-
----- - -<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 - -As Spring Security 4.0+ <> is now enabled by default. -This means if an application did not provide the <> 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] ----- - - ... - - ----- - -The application will need updated. -The quickest, but not ideal, solution is to explicitly disable the headers protection using <>. -For example: - -.Migration to Spring Security 4 Configuration -[source,xml] ----- - - ... - - ----- - -*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 <> for details on using this feature. - -[[m3to4-xmlnamespace-csrf]] -=== Migrating - -As Spring Security 4.0+ <> is now enabled by default. -This means if an application did not provide the <> 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] ----- - - ... - - ----- - -The application will need updated. -The quickest, but not ideal, solution is to explicitly disable the csrf protection using <>. -For example: - -.Migration to Spring Security 4 Configuration -[source,xml] ----- - - ... - - ----- - -*Alternatively*, the application would enable CSRF. -For more details refer to <>. - -[[m3to4-xmlnamespace-remember-me]] -=== Migrating - -If the `` 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 <> 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 <> 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] ----- - - ... - - ----- - -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] ----- - - ... - - remember-me-cookie="SPRING_SECURITY_REMEMBER_ME_COOKIE" - /> - ----- - -<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] ----- - -
- ... - -

- - -
- -
-
----- - -<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] ----- - - - ----- - -The configuration will need to be updated to something similar to the following when Spring Security 4.x: - -[source,xml] ----- - - - - ----- - -*Alternatively*, the `ServiceProperties` can be updated to use the new default: - -[source,xml] ----- - - - ----- - -[[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] ----- - - - - ----- - -The configuration will need to be updated to something similar to the following when Spring Security 4.x: - -[source,xml] ----- - - - - - - - ----- - -*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 <>. -Below we highlight the changes in configuring the Security HTTP Response Headers between 3.x and 4.x. - -* <> -* <> - -[[m3to4-header-xml]] -=== XML Namespace HTTP Response Header Samples - -In Spring Security 3.x, the following configuration - -[source,xml] ----- - - - - - - ... - ----- - -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] ----- - - ... - - - ----- - -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 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 <>. -This means if you have something like this: - -[source,xml] ----- - - ... - ----- - -it needs to be replaced with: - -[source,xml] ----- - - ... - ----- - -[[m3to4-deprecations-config-http-adp]] -==== http@access-denied-page -The XML attribute `http@access-denied-page` was removed in favor of <>. -This means if you have something like this: - - -[source,xml] ----- - - ... - ----- - -it needs to be replaced with: - -[source,xml] ----- - - - ----- - -[[m3to4-deprecations-config-http-pt]] -==== http@path-type -The XML attribute `http@path-type` was removed in favor of <>. -This means if you have something like this: - - -[source,xml] ----- - - ... - ----- - -it needs to be replaced with: - -[source,xml] ----- - - ... - ----- - -[[m3to4-deprecations-config-fcm-pt]] -==== filter-chain-map@path-type -The XML attribute `filter-chain-map@path-type` was removed in favor of <>. -This means if you have something like this: - - -[source,xml] ----- - - ... - ----- - -it needs to be replaced with: - -[source,xml] ----- - - ... - ----- - -[[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 <>. -This means if you have something like this: - - -[source,xml] ----- - - ... - ----- - -it needs to be replaced with: - -[source,xml] ----- - - ... - ----- - -[[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 attrs = - SecurityConfig.createSingleAttributeList("ROLE_USER"); ----- - -needs to be replaced with: - -[source,java] ----- -List 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] ----- - - - - - - - - - - - - - ROLE_ADMIN > ROLE_USER - - - ----- - -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 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] ----- - - - ----- - -then it needs to be migrated to: - -[source,xml] ----- - - - ----- - -[[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 { - - 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` have been removed in favor of using an `AxFetchListFactory`. -For example: - -[source,java] ----- -new OpenIDJavaConsumer(attributes); ----- - -should be replaced with: - -[source,java] ----- -Map> regexMap = new HashMap>(); -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] ----- - - Must have ROLE_A and ROLE_B - - - Must have ROLE_A or ROLE_B - - - Must not have ROLE_A - ----- - -can be replaced with: - -[source,xml] ----- - - Must have ROLE_A and ROLE_B - - - Must have ROLE_A or ROLE_B - - - Must not have ROLE_A - ----- - -[[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> mappings = filter.getFilterChainMap(); ----- - -should be replaced with - - -[source,java] ----- -FilterChainProxy filter = ... -List 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 delegates = new ArrayList(); -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`. - -This means if you are using: - -[source,java] ----- -WebSecurityExpressionHandler handler = ... ----- - -it needs to be updated to - -[source,java] ----- -SecurityExpressionHandler 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. diff --git a/docs/manual/src/docs/asciidoc/index.adoc b/docs/manual/src/docs/asciidoc/index.adoc index d1b1e7a905..90db9744c8 100644 --- a/docs/manual/src/docs/asciidoc/index.adoc +++ b/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