Spring Session Documentation

Spring Session provides an API and implementations for managing user session information. It enables support for clustered sessions without being tied to a specific application container solution.

Key integration features include:

• HttpSession: Replaces the standard HttpSession in application containers (like Tomcat) in a container-neutral way. It supports providing session IDs in headers, which is useful for RESTful APIs.
• WebSocket: Keeps the HttpSession alive when receiving WebSocket messages.
• WebSession: Replaces Spring WebFlux's WebSession in a container-neutral way.

When using Spring Session with WebSockets, the session lifecycle is tied to user activity via messages:

• Keeping the session alive: Sending messages from a user (inbound messages) updates the session's last accessed time, preventing expiration.
• Session expiration: If no messages are sent for the duration of the timeout, the session expires, and the WebSocketRegistryListener will close the associated WebSocket connections.
• Important Limitation: Only messages sent from a user keep the session alive. Received messages (outbound) do not imply user activity and will not renew the session expiration.

Spring Session replaces the standard Servlet Container HttpSession (e.g., Tomcat's implementation) with a custom implementation backed by a data store like Redis.

When Spring Security's SecurityContextPersistenceFilter saves the SecurityContext to the HttpSession, the data is persisted into Redis. On the client side, Spring Session creates a cookie (default name SESSION) containing the session ID. This allows session state to be shared across multiple application instances or survive server restarts.

Spring Session provides transparent integration with the standard HttpSession interface. This allows you to switch from container-managed sessions to Spring Session-backed implementations (like Redis or JDBC) without changing your application code.

Key benefits include:

• Clustered Sessions: Easily support clustered environments using backends like Redis without being tied to a specific application container.
• RESTful APIs: Support providing session IDs via HTTP headers instead of just cookies.

By default, the WebSocket specification (JSR-356) can cause issues with session management. If an HttpSession times out, any WebSocket associated with that session and an authenticated user may be forcibly closed. This leads to poor user experiences, such as being disconnected from a chat application simply because the user was not making active HTTP requests.

Spring Session provides transparent integration with Spring's WebSocket support to prevent these premature disconnections and ensure that active WebSocket communication can help maintain the user's session state.

A Session acts as a simplified Map of name-value pairs. When using a SessionRepository, you should use a generic type S that extends Session to allow the repository to perform implementation-specific optimizations, such as writing only changed attributes.

Key behaviors:

• Saving: You must save the session back to the repository after interacting with it. The repository only allows saving instances created or retrieved by that specific repository instance.
• Expiration: The Session API provides methods to manage expiration. The last accessed time is automatically updated when the session is saved.
• Retrieval: If a session has expired, attempting to retrieve it from the repository will return null.

Spring Session integrates with Spring WebFlux by leveraging the WebSessionStore API.

1. Custom WebSession: Spring Session uses a SpringSessionWebSession implementation that delegates operations to a Spring Session Session object. This implementation handles lifecycle states like NEW and STARTED, and provides methods like changeSessionId().
2. Custom WebSessionStore: A SpringSessionWebSessionStore is created which implements WebSessionStore. It delegates to a ReactiveSessionRepository and wraps the underlying Session into the SpringSessionWebSession implementation.
3. Registration: For Spring WebFlux to detect and use this custom store, the WebSessionStore must be registered in the ApplicationContext as a bean named webSessionManager.

Some SessionRepository implementations (like Redis and JDBC) also implement FindByIndexNameSessionRepository. This allows you to look up all sessions associated with a specific index value, such as a username.

To use this, you must ensure that the session attribute named FindByIndexNameSessionRepository.PRINCIPAL_NAME_INDEX_NAME is populated with the username. Spring Session does not automatically populate this; you must do so based on your authentication mechanism.

Once indexed, you can use the repository to find all sessions for a particular user.

Spring Session achieves transparent integration by wrapping the standard HttpServletRequest and HttpSession interfaces.

1. Request Wrapping: A SessionRepositoryRequestWrapper (extending HttpServletRequestWrapper) is created. This wrapper overrides getSession() and getSession(boolean createNew) to return a custom HttpSession implementation provided by Spring Session.
2. Filter Injection: A SessionRepositoryFilter is placed early in the servlet filter chain. It wraps the original HttpServletRequest with the SessionRepositoryRequestWrapper and passes it down the FilterChain.

Critical Requirement: The SessionRepositoryFilter must be placed before any other component or filter that interacts with the HttpSession to ensure the wrapped request is used.

When using Spring Session with Redis:

1. Session Storage: Instead of storing session attributes in the Servlet Container's memory, they are persisted in Redis.
2. Session Tracking: Spring Session creates a cookie named SESSION in the browser containing the session ID.
3. Transparency: The application interacts with the standard HttpSession API, but the underlying implementation is managed by Spring Session.

To manually clear sessions in Redis, you can use redis-cli to delete keys matching the pattern spring:session:sessions:*.

Spring Session works by replacing the standard HttpSession implementation with a custom one backed by a relational database.

1. Filter Injection: Spring Boot creates a springSessionRepositoryFilter bean (implementing Filter). This filter is responsible for replacing the HttpSession for every request.
2. Persistence: When components like Spring Security's SecurityContextPersistenceFilter save data to the HttpSession, that data is persisted into the configured database (e.g., H2, MySQL, PostgreSQL).
3. Session Tracking: When a new session is created, Spring Session issues a cookie named SESSION to the browser containing the session ID.