[[jackson]]
= Jackson Support

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).

[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]
======
Java::
+
[source,java,role="primary"]
----
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);
----

Kotlin::
+
[source,kotlin,role="secondary"]
----
val loader = javaClass.classLoader
val mapper = JsonMapper.builder()
    .addModules(SecurityJacksonModules.getModules(loader))
    .build()

// ... use JsonMapper as normally ...
val context: SecurityContext = SecurityContextImpl()
// ...
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 (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-oauth2-authorization-server (javadoc:org.springframework.security.oauth2.server.authorization.jackson.OAuth2AuthorizationServerJacksonModule[])
- 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[])
====
