160 lines
6.4 KiB
Plaintext
160 lines
6.4 KiB
Plaintext
= Spring Session - Spring Boot
|
|
Rob Winch, Vedran Pavić
|
|
:stylesdir: ../
|
|
:highlightjsdir: ../js/highlight
|
|
:docinfodir: guides
|
|
|
|
This guide describes how to use Spring Session to transparently leverage Redis to back a web application's `HttpSession` when you use Spring Boot.
|
|
|
|
NOTE: You can find the completed guide in the <<boot-sample, boot sample application>>.
|
|
|
|
[#index-link]
|
|
link:../index.html[Index]
|
|
|
|
== Updating Dependencies
|
|
|
|
Before you use Spring Session with Redis, you must ensure that you have the right dependencies.
|
|
We assume you are working with a working Spring Boot web application.
|
|
|
|
====
|
|
.pom.xml
|
|
[source,xml,role="primary"]
|
|
[subs="verbatim,attributes"]
|
|
----
|
|
<dependencies>
|
|
<!-- ... -->
|
|
|
|
<dependency>
|
|
<groupId>org.springframework.session</groupId>
|
|
<artifactId>spring-session-data-redis</artifactId>
|
|
</dependency>
|
|
</dependencies>
|
|
----
|
|
|
|
.build.gradle
|
|
[source,groovy,role="secondary"]
|
|
----
|
|
implementation("org.springframework.session:spring-session-data-redis")
|
|
----
|
|
====
|
|
|
|
Spring Boot provides dependency management for Spring Session modules, so you need not explicitly declare dependency version.
|
|
|
|
[[boot-spring-configuration]]
|
|
== Spring Boot Configuration
|
|
|
|
After adding the required dependencies, we can create our Spring Boot configuration.
|
|
Thanks to first-class auto-configuration support, just by adding the dependency Spring Boot will set up Spring Session backed by Redis for us.
|
|
|
|
Under the hood, Spring Boot applies configuration that is equivalent to manually adding `@EnableRedisHttpSession` annotation.
|
|
This creates a Spring bean with the name of `springSessionRepositoryFilter` that implements `Filter`.
|
|
The filter is in charge of replacing the `HttpSession` implementation to be backed by Spring Session.
|
|
|
|
Further customization is possible by using `application.properties`, as the following listing shows:
|
|
|
|
====
|
|
.src/main/resources/application.properties
|
|
----
|
|
server.servlet.session.timeout= # Session timeout. If a duration suffix is not specified, seconds is used.
|
|
spring.session.redis.flush-mode=on_save # Sessions flush mode.
|
|
spring.session.redis.namespace=spring:session # Namespace for keys used to store sessions.
|
|
----
|
|
====
|
|
|
|
For more information, see the {docs-url}/spring-boot/docs/{spring-boot-version}/reference/htmlsingle/#boot-features-session[Spring Session] portion of the Spring Boot documentation.
|
|
|
|
[[boot-redis-configuration]]
|
|
== Configuring the Redis Connection
|
|
|
|
Spring Boot automatically creates a `RedisConnectionFactory` that connects Spring Session to a Redis Server on localhost on port 6379 (default port).
|
|
In a production environment, you need to update your configuration to point to your Redis server.
|
|
For example, you can include the following in your application.properties:
|
|
|
|
====
|
|
.src/main/resources/application.properties
|
|
----
|
|
spring.data.redis.host=localhost # Redis server host.
|
|
spring.data.redis.password= # Login password of the redis server.
|
|
spring.data.redis.port=6379 # Redis server port.
|
|
----
|
|
====
|
|
|
|
For more information, see the {docs-url}/spring-boot/docs/{spring-boot-version}/reference/htmlsingle/#boot-features-connecting-to-redis[Connecting to Redis] portion of the Spring Boot documentation.
|
|
|
|
[[boot-servlet-configuration]]
|
|
== Servlet Container Initialization
|
|
|
|
Our <<boot-spring-configuration,Spring Boot Configuration>> created a Spring bean named `springSessionRepositoryFilter` that implements `Filter`.
|
|
The `springSessionRepositoryFilter` bean is responsible for replacing the `HttpSession` with a custom implementation that is backed by Spring Session.
|
|
|
|
In order for our `Filter` to do its magic, Spring needs to load our `Config` class.
|
|
Last, we need to ensure that our servlet container (that is, Tomcat) uses our `springSessionRepositoryFilter` for every request.
|
|
Fortunately, Spring Boot takes care of both of these steps for us.
|
|
|
|
[[boot-sample]]
|
|
== Boot Sample Application
|
|
|
|
The Boot Sample Application demonstrates how to use Spring Session to transparently leverage Redis to back a web application's `HttpSession` when you use Spring Boot.
|
|
|
|
[[boot-running]]
|
|
=== Running the Boot Sample Application
|
|
|
|
You can run the sample by obtaining the {download-url}[source code] and invoking the following command:
|
|
|
|
====
|
|
----
|
|
$ ./gradlew :spring-session-sample-boot-redis:bootRun
|
|
----
|
|
====
|
|
|
|
NOTE: For the sample to work, you must https://redis.io/download[install Redis 2.8+] on localhost and run it with the default port (6379).
|
|
Alternatively, you can update the `RedisConnectionFactory` to point to a Redis server.
|
|
Another option is to use https://www.docker.com/[Docker] to run Redis on localhost. See https://hub.docker.com/_/redis/[Docker Redis repository] for detailed instructions.
|
|
|
|
You should now be able to access the application at http://localhost:8080/
|
|
|
|
[[boot-explore]]
|
|
=== Exploring the `security` Sample Application
|
|
|
|
Now you can try using the application. Enter the following to log in:
|
|
|
|
* *Username* _user_
|
|
* *Password* _password_
|
|
|
|
Now click the *Login* button.
|
|
You should now see a message indicating you are logged in with the user entered previously.
|
|
The user's information is stored in Redis rather than Tomcat's `HttpSession` implementation.
|
|
|
|
[[boot-how]]
|
|
=== How Does It Work?
|
|
|
|
Instead of using Tomcat's `HttpSession`, we persist the values in Redis.
|
|
Spring Session replaces the `HttpSession` with an implementation that is backed by Redis.
|
|
When Spring Security's `SecurityContextPersistenceFilter` saves the `SecurityContext` to the `HttpSession`, it is then persisted into Redis.
|
|
|
|
When a new `HttpSession` is created, Spring Session creates a cookie named `SESSION` in your browser.
|
|
That cookie contains the ID of your session.
|
|
You can view the cookies (with https://developers.google.com/web/tools/chrome-devtools/manage-data/cookies[Chrome] or https://developer.mozilla.org/en-US/docs/Tools/Storage_Inspector[Firefox]).
|
|
|
|
You can remove the session by using redis-cli.
|
|
For example, on a Linux based system you can type the following:
|
|
|
|
====
|
|
----
|
|
$ redis-cli keys '*' | xargs redis-cli del
|
|
----
|
|
====
|
|
|
|
TIP: The Redis documentation has instructions for https://redis.io/topics/quickstart[installing redis-cli].
|
|
|
|
Alternatively, you can also delete the explicit key.
|
|
To do so, enter the following into your terminal, being sure to replace `7e8383a4-082c-4ffe-a4bc-c40fd3363c5e` with the value of your `SESSION` cookie:
|
|
|
|
====
|
|
----
|
|
$ redis-cli del spring:session:sessions:7e8383a4-082c-4ffe-a4bc-c40fd3363c5e
|
|
----
|
|
====
|
|
|
|
Now you can visit the application at http://localhost:8080/ and observe that we are no longer authenticated.
|