Spring Session MongoDB provides an API and implementations for managing a user’s session information on MongoDB.


For an introduction to Spring Session as a whole, visit Spring Session itself.

Samples and Guides (Start Here)

If you are looking to get started with Spring Session, the best place to start is our Sample Applications.

Table 1. Sample Applications using Spring Boot
Description Guide

Demonstrates how to use Spring Session to replace the HttpSession with Mongo.

HttpSession with Mongo Guide

HttpSession with Mongo

Using Spring Session with HttpSession is enabled by adding a Servlet Filter before anything that uses the HttpSession.

This section describes how to use Mongo to back HttpSession using Java based configuration.

The HttpSession Mongo Sample provides a working sample on how to integrate Spring Session and HttpSession using Java configuration. You can read the basic steps for integration below, but you are encouraged to follow along with the detailed HttpSession Guide when integrating with your own application.

All you have to do is to add the following Spring Configuration:

Unresolved directive in guides/boot-mongo.adoc - include::https://raw.githubusercontent.com/gregturn/spring-session-data-mongodb-examples/master/spring-session-data-mongodb-traditional-boot/src/main/java/org/springframework/session/mongodb/examples/config/HttpSessionConfig.java[tag=class]
  1. The @EnableMongoHttpSession annotation creates a Spring Bean with the name of springSessionRepositoryFilter that implements Filter. The filter is what is in charge of replacing the HttpSession implementation to be backed by Spring Session. In this instance Spring Session is backed by Mongo.

  2. We explicitly configure JdkMongoSessionConverter since Spring Security’s objects cannot be automatically persisted using Jackson (the default if Jackson is on the classpath).

Session serialization mechanisms

To be able to persist session objects in MongoDB we need to provide the serialization/deserialization mechanism. Depending on your classpath Spring Session will choose one of two build-in converters:

  • JacksonMongoSessionConverter when ObjectMapper class is available, or

  • JdkMongoSessionConverter otherwise.


This mechanism uses Jackson to serialize session objects to/from JSON. JacksonMongoSessionConverter will be the default when Jackson is detected on the classpath and the user has not explicitly registered a AbstractMongoSessionConverter Bean.

If you would like to provide custom Jackson modules you can do it by explicitly registering JacksonMongoSessionConverter:

static class Config extends BaseConfig {

	public AbstractMongoSessionConverter mongoSessionConverter() {
		return new JacksonMongoSessionConverter(Collections.<Module>singletonList(new GeoModule()));


JdkMongoSessionConverter uses standard Java serialization to persist session attributes map to MongoDB in a binary form. However, standard session elements like id, access time, etc are still written as a plain Mongo objects and can be read and queried without additional effort. JdkMongoSessionConverter is used if Jackson is not on the classpath and no explicit AbstractMongoSessionConverter Bean has been defined. You can explicitly register JdkMongoSessionConverter by defining it as a Bean.

static class Config extends BaseConfig {

	public AbstractMongoSessionConverter mongoSessionConverter() {
		return new JdkMongoSessionConverter(Duration.ofMinutes(30));

There is also a constructor taking Serializer and Deserializer objects, allowing you to pass custom implementations, which is especially important when you want to use non-default classloader.

API Documentation

You can browse the complete Javadoc online. The key APIs are described below:

Spring Session Community

We are glad to consider you a part of our community. Please find additional information below.


You can get help by asking questions on StackOverflow with the tag spring-session. Similarly we encourage helping others by answering questions on StackOverflow.

Source Code

Our source code can be found on github at https://github.com/spring-projects/spring-session-data-mongodb/

Issue Tracking


We appreciate Pull Requests.


Spring Session is Open Source software released under the Apache 2.0 license.

Minimum Requirements

The minimum requirements for Spring Session MongoDB are:

  • Java 8

  • If you are running in a Servlet Container (not required), Servlet 2.5+

  • If you are using other Spring libraries (not required), the minimum required version is Spring 5.0