From 8f8a25533ab52d462f4fcd82133bc102a875cd0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Deleuze?= Date: Fri, 17 Oct 2025 11:24:48 +0200 Subject: [PATCH] Refine documentation for Jackson 3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit refines the documentation by: - Updating Jackson documentation for Jackson 3 - Removing the outdated documentation in servlet - Adding migration guidelines Closes gh-17832 Signed-off-by: Sébastien Deleuze --- docs/modules/ROOT/nav.adoc | 1 - .../pages/features/integrations/jackson.adoc | 54 ++++++++++++++++--- docs/modules/ROOT/pages/migration/index.adoc | 18 +++++++ .../pages/servlet/integrations/jackson.adoc | 30 ----------- 4 files changed, 66 insertions(+), 37 deletions(-) delete mode 100644 docs/modules/ROOT/pages/servlet/integrations/jackson.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 186b024a23..ad2a966ffb 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -110,7 +110,6 @@ *** xref:servlet/exploits/firewall.adoc[] ** xref:servlet/integrations/index.adoc[Integrations] *** xref:servlet/integrations/concurrency.adoc[Concurrency] -*** xref:servlet/integrations/jackson.adoc[Jackson] *** xref:servlet/integrations/localization.adoc[Localization] *** xref:servlet/integrations/servlet-api.adoc[Servlet APIs] *** xref:servlet/integrations/data.adoc[Spring Data] diff --git a/docs/modules/ROOT/pages/features/integrations/jackson.adoc b/docs/modules/ROOT/pages/features/integrations/jackson.adoc index d9cfbe6e75..1e2cd49fc2 100644 --- a/docs/modules/ROOT/pages/features/integrations/jackson.adoc +++ b/docs/modules/ROOT/pages/features/integrations/jackson.adoc @@ -1,10 +1,15 @@ [[jackson]] = Jackson Support -Spring Security provides Jackson support for persisting Spring Security related classes. +Spring Security provides Jackson 3 support for persisting Spring Security related classes. This can improve the performance of serializing Spring Security related classes when working with distributed sessions (i.e. session replication, Spring Session, etc). -To use it, register the `SecurityJacksonModules.getModules(ClassLoader)` with `JsonMapper.Builder` (https://github.com/FasterXML/jackson-databind[jackson-databind]): +[NOTE] +==== +Jackson 2 support is still available but deprecated for removal, so you are encouraged to migrate to Jackson 3. +==== + +To use it, register `SecurityJacksonModules.getModules(ClassLoader)` with `JsonMapper.Builder` (https://github.com/FasterXML/jackson-databind[jackson-databind]): [tabs] ====== @@ -39,12 +44,49 @@ val json: String = mapper.writeValueAsString(context) ---- ====== +[NOTE] +==== +Using `SecurityJacksonModules` as above enables automatic inclusion of type information and configure a +`PolymorphicTypeValidator` that handles the validation of class names. +==== + +If needed, you can add custom classes to the validation handling. + +[tabs] +====== +Java:: ++ +[source,java,role="primary"] +---- +ClassLoader loader = getClass().getClassLoader(); +BasicPolymorphicTypeValidator.Builder builder = BasicPolymorphicTypeValidator.builder() + .allowIfSubType(MyCustomType.class); +JsonMapper mapper = JsonMapper.builder() + .addModules(SecurityJacksonModules.getModules(loader, builder)) + .build(); +---- + +Kotlin:: ++ +[source,kotlin,role="secondary"] +---- +val loader = javaClass.classLoader +val builder = BasicPolymorphicTypeValidator.builder() + .allowIfSubType(MyCustomType::class) +val mapper = JsonMapper.builder() + .addModules(SecurityJacksonModules.getModules(loader, builder)) + .build() +---- +====== + [NOTE] ==== The following Spring Security modules provide Jackson support: -- spring-security-core (`CoreJacksonModule`) -- spring-security-web (`WebJacksonModule`, `WebServletJacksonModule`, `WebServerJacksonModule`) -- xref:servlet/oauth2/client/index.adoc#oauth2client[ spring-security-oauth2-client] (`OAuth2ClientJacksonModule`) -- spring-security-cas (`CasJacksonModule`) +- spring-security-core (javadoc:org.springframework.security.jackson.CoreJacksonModule[]) +- spring-security-web (javadoc:org.springframework.security.web.jackson.WebJacksonModule[], javadoc:org.springframework.security.web.jackson.WebServletJacksonModule[], javadoc:org.springframework.security.web.server.jackson.WebServerJacksonModule[]) +- spring-security-oauth2-client (javadoc:org.springframework.security.oauth2.client.jackson.OAuth2ClientJacksonModule[]) +- spring-security-cas (javadoc:org.springframework.security.cas.jackson.CasJacksonModule[]) +- spring-security-ldap (javadoc:org.springframework.security.ldap.jackson.LdapJacksonModule[]) +- spring-security-saml2 (javadoc:org.springframework.security.saml2.jackson.Saml2JacksonModule[]) ==== diff --git a/docs/modules/ROOT/pages/migration/index.adoc b/docs/modules/ROOT/pages/migration/index.adoc index 4ad6c991df..fee59f5f43 100644 --- a/docs/modules/ROOT/pages/migration/index.adoc +++ b/docs/modules/ROOT/pages/migration/index.adoc @@ -16,6 +16,24 @@ The first step is to ensure you are the latest patch release of Spring Boot 4.0. Next, you should ensure you are on the latest patch release of Spring Security 7. For directions, on how to update to Spring Security 7 visit the xref:getting-spring-security.adoc[] section of the reference guide. +=== Migrate from Jackson 2 to Jackson 3 + +The configuration of Jackson 2 `ObjectMapper` with `SecurityJackson2Modules` should be replaced by the configuration of +Jackson 3 `JsonMapper.Builder` with `SecurityJacksonModules`. See the +https://github.com/FasterXML/jackson/blob/main/jackson3/MIGRATING_TO_JACKSON_3.md[Jackson 3 Migration Guide] for more details. + +It is recommended to replace the configuration of +individual modules like `CoreJacksonModule` by the module detection from `SecurityJacksonModules` as it enables +automatic inclusion of type information and configure a `PolymorphicTypeValidator` that handles the validation of class +names. + +The Jackson 3 support uses the same format than the now deprecated Jackson 2 one, so class instances serialized with +Jackson 2 should be deserializable with the Jackson 3 support. + +`spring-security-oauth2-authorization-server` now uses Jackson 3 by default. If you want to continue +to use the deprecated Jackson 2 support, the transitive dependency on Jackson 3 (`tools.jackson.core:jackson-databind`) +should be excluded and a dependency on Jackson 2 (`com.fasterxml.jackson.core:jackson-databind`) should be added. + == Perform Application-Specific Steps Next, there are steps you need to perform based on whether it is a xref:migration/servlet/index.adoc[Servlet] or xref:migration/reactive.adoc[Reactive] application. diff --git a/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc b/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc deleted file mode 100644 index dc7016edc0..0000000000 --- a/docs/modules/ROOT/pages/servlet/integrations/jackson.adoc +++ /dev/null @@ -1,30 +0,0 @@ -[[jackson]] -= Jackson Support - -Spring Security provides Jackson support for persisting Spring Security-related classes. -This can improve the performance of serializing Spring Security-related classes when working with distributed sessions (session replication, Spring Session, and so on). - -To use it, register the `SecurityJacksonModules.getModules(ClassLoader)` with `JsonMapper.Builder` (https://github.com/FasterXML/jackson-databind[jackson-databind]): - -[source,java] ----- -ClassLoader loader = getClass().getClassLoader(); -JsonMapper mapper = JsonMapper.builder() - .addModules(SecurityJacksonModules.getModules(loader)) - .build(); - -// ... use JsonMapper as normally ... -SecurityContext context = new SecurityContextImpl(); -// ... -String json = mapper.writeValueAsString(context); ----- - -[NOTE] -==== -The following Spring Security modules provide Jackson support: - -- spring-security-core (javadoc:org.springframework.security.jackson.CoreJacksonModule[]) -- spring-security-web (javadoc:org.springframework.security.web.jackson.WebJacksonModule[], javadoc:org.springframework.security.web.jackson.WebServletJacksonModule[], javadoc:org.springframework.security.web.server.jackson.WebServerJacksonModule[]) -- <> (javadoc:org.springframework.security.oauth2.client.jackson.OAuth2ClientJacksonModule[]) -- spring-security-cas (javadoc:org.springframework.security.cas.jackson.CasJacksonModule[]) -====