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 <sdeleuze@users.noreply.github.com>
This commit is contained in:
Sébastien Deleuze
committed by
Rob Winch
Rob Winch
parent
137f8fd670
commit
8f8a25533a
@@ -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]
|
||||
|
||||
@@ -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[])
|
||||
====
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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[])
|
||||
- <<oauth2client, spring-security-oauth2-client>> (javadoc:org.springframework.security.oauth2.client.jackson.OAuth2ClientJacksonModule[])
|
||||
- spring-security-cas (javadoc:org.springframework.security.cas.jackson.CasJacksonModule[])
|
||||
====
|
||||
Reference in New Issue
Block a user