Refine documentation for Jackson 3

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 <[email protected]>

Author: sdeleuze

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]

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[])
 ====

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.