tessl/maven-spring-security-core

Core authentication and authorization framework for Spring applications with comprehensive user management and security context handling

Overview

Eval results

Files

Session Management

Name: tessl/maven-spring-security-core
Author: tessl

Session management provides comprehensive tracking and control of user sessions, enabling features like concurrent session control, session fixation protection, and session lifecycle monitoring.

Key Information for Agents

Core Capabilities:

SessionRegistry tracks active user sessions
SessionInformation contains session details (principal, session ID, last request, expired status)
Session events: SessionCreationEvent, SessionDestroyedEvent, SessionIdChangedEvent
Reactive support via ReactiveSessionRegistry and ReactiveSessionInformation
In-memory implementation: SessionRegistryImpl (single instance, not clustered)
Session expiration: Manual expiration via expireNow() method

Key Interfaces and Classes:

SessionRegistry - Interface: getAllPrincipals(), getAllSessions(), getSessionInformation(), registerNewSession(), removeSessionInformation()
SessionInformation - Class: getPrincipal(), getSessionId(), getLastRequest(), isExpired(), expireNow()
SessionRegistryImpl - In-memory implementation (listens to session events)
ReactiveSessionRegistry - Reactive interface returning Mono / Flux
ReactiveSessionInformation - Reactive session information with Instant timestamps
AbstractSessionEvent - Base class for session events

Default Behaviors:

Sessions registered automatically via HttpSessionEventPublisher (servlet listener)
getAllSessions() excludes expired sessions by default (use includeExpiredSessions=true to include)
expireNow() marks session as expired (doesn't remove from registry)
refreshLastRequest() updates last access time
Session events published by Spring Session or HttpSessionEventPublisher

Threading Model:

Synchronous registry is thread-safe (in-memory implementation)
Reactive registry returns Mono / Flux for non-blocking operations

Lifecycle:

Sessions registered on creation (via event listener)
Sessions removed on destruction (via event listener)
Manual expiration: Call expireNow() then optionally removeSessionInformation()

Exceptions:

No exceptions thrown by registry (returns null/empty if session not found)

Edge Cases:

Expired sessions: Marked as expired but may still exist in registry (check isExpired())
Session ID change: SessionIdChangedEvent published (update registry manually)
Clustered deployments: SessionRegistryImpl not suitable (use distributed implementation)
Concurrent access: In-memory implementation is thread-safe
Event listener: Requires HttpSessionEventPublisher for automatic registration

SessionRegistry

Central registry for maintaining information about active user sessions.

public interface SessionRegistry

{ .api }

Key Methods:

List<Object> getAllPrincipals()

{ .api }

Returns a list of all principals with active sessions.

List<SessionInformation> getAllSessions(Object principal, boolean includeExpiredSessions)

{ .api }

Returns all session information for a specific principal.

principal: The user's principal object
includeExpiredSessions: If true, includes expired sessions in the result

SessionInformation getSessionInformation(String sessionId)

{ .api }

Retrieves session information for a specific session ID.

void refreshLastRequest(String sessionId)

{ .api }

Updates the last access time for the session.

void registerNewSession(String sessionId, Object principal)

{ .api }

Registers a new session for a principal.

void removeSessionInformation(String sessionId)

{ .api }

Removes session information from the registry.

Example Usage:

@Service
public class SessionManagementService {

    private final SessionRegistry sessionRegistry;

    public void expireUserSessions(String username) {
        // Get all sessions for user
        List<SessionInformation> sessions =
            sessionRegistry.getAllSessions(username, false);

        // Expire all sessions
        sessions.forEach(SessionInformation::expireNow);
    }

    public int getActiveSessionCount() {
        List<Object> principals = sessionRegistry.getAllPrincipals();
        return principals.stream()
            .mapToInt(principal ->
                sessionRegistry.getAllSessions(principal, false).size())
            .sum();
    }

    public boolean hasActiveSession(String username) {
        List<SessionInformation> sessions =
            sessionRegistry.getAllSessions(username, false);
        return !sessions.isEmpty();
    }
}

ReactiveSessionRegistry

Reactive version of session registry for non-blocking session management.

public interface ReactiveSessionRegistry

{ .api }

Key Methods:

Mono<Void> saveSessionInformation(ReactiveSessionInformation sessionInformation)

{ .api }

Saves session information reactively.

Mono<ReactiveSessionInformation> getSessionInformation(String sessionId)

{ .api }

Retrieves session information for a session ID.

Mono<ReactiveSessionInformation> removeSessionInformation(String sessionId)

{ .api }

Removes and returns session information.

Mono<Void> updateLastAccessTime(String sessionId)

{ .api }

Updates the last access time for a session.

Flux<ReactiveSessionInformation> getAllSessions(Object principal)

{ .api }

Returns all sessions for a principal as a reactive stream.

Example Usage:

@Service
public class ReactiveSessionService {

    private final ReactiveSessionRegistry sessionRegistry;

    public Mono<Void> expireUserSessions(String username) {
        return sessionRegistry.getAllSessions(username)
            .flatMap(session ->
                sessionRegistry.removeSessionInformation(session.getSessionId()))
            .then();
    }

    public Mono<Long> countActiveSessions(String username) {
        return sessionRegistry.getAllSessions(username).count();
    }
}

Session Registry Implementations

SessionRegistryImpl

In-memory implementation of SessionRegistry with application event support.

public class SessionRegistryImpl
    implements SessionRegistry, ApplicationListener<AbstractSessionEvent>

{ .api }

Features:

Thread-safe in-memory storage
Automatic cleanup via application events
Supports concurrent access

Configuration:

@Bean
public SessionRegistry sessionRegistry() {
    return new SessionRegistryImpl();
}

@Bean
public HttpSessionEventPublisher httpSessionEventPublisher() {
    return new HttpSessionEventPublisher();
}

Complete Example:

@Configuration
public class SessionConfiguration {

    @Bean
    public SessionRegistry sessionRegistry() {
        return new SessionRegistryImpl();
    }

    @Bean
    public ServletListenerRegistrationBean<HttpSessionEventPublisher> httpSessionEventPublisher() {
        return new ServletListenerRegistrationBean<>(new HttpSessionEventPublisher());
    }
}

@RestController
public class SessionController {

    private final SessionRegistry sessionRegistry;

    @GetMapping("/api/sessions/active")
    public Map<String, Object> getActiveSessions() {
        List<Object> principals = sessionRegistry.getAllPrincipals();

        Map<String, Object> result = new HashMap<>();
        result.put("totalPrincipals", principals.size());
        result.put("totalSessions", principals.stream()
            .mapToInt(p -> sessionRegistry.getAllSessions(p, false).size())
            .sum());

        return result;
    }

    @PostMapping("/api/sessions/expire/{username}")
    public void expireSessions(@PathVariable String username) {
        sessionRegistry.getAllSessions(username, false)
            .forEach(SessionInformation::expireNow);
    }
}

InMemoryReactiveSessionRegistry

In-memory reactive implementation of session registry.

public class InMemoryReactiveSessionRegistry implements ReactiveSessionRegistry

{ .api }

Configuration:

@Configuration
public class ReactiveSessionConfiguration {

    @Bean
    public ReactiveSessionRegistry reactiveSessionRegistry() {
        return new InMemoryReactiveSessionRegistry();
    }
}

@RestController
public class ReactiveSessionController {

    private final ReactiveSessionRegistry sessionRegistry;

    @GetMapping("/api/sessions/user/{username}")
    public Flux<ReactiveSessionInformation> getUserSessions(@PathVariable String username) {
        return sessionRegistry.getAllSessions(username);
    }

    @DeleteMapping("/api/sessions/{sessionId}")
    public Mono<Void> deleteSession(@PathVariable String sessionId) {
        return sessionRegistry.removeSessionInformation(sessionId).then();
    }
}

Session Information

SessionInformation

Contains information about a user's session.

public class SessionInformation

{ .api }

Key Methods:

Object getPrincipal()

{ .api }

Returns the principal associated with this session.

String getSessionId()

{ .api }

Returns the session identifier.

Date getLastRequest()

{ .api }

Returns the last time the session was accessed.

void refreshLastRequest()

{ .api }

Updates the last access time to the current time.

boolean isExpired()

{ .api }

Returns true if the session has been marked as expired.

void expireNow()

{ .api }

Marks the session as expired.

Example:

@Component
public class SessionMonitor {

    private final SessionRegistry sessionRegistry;

    @Scheduled(fixedRate = 60000) // Every minute
    public void monitorSessions() {
        List<Object> principals = sessionRegistry.getAllPrincipals();

        for (Object principal : principals) {
            List<SessionInformation> sessions =
                sessionRegistry.getAllSessions(principal, true);

            for (SessionInformation session : sessions) {
                if (session.isExpired()) {
                    logger.info("Expired session: {} for user: {}",
                        session.getSessionId(), principal);
                    sessionRegistry.removeSessionInformation(session.getSessionId());
                } else {
                    long idleTime = System.currentTimeMillis() -
                        session.getLastRequest().getTime();
                    if (idleTime > 3600000) { // 1 hour
                        logger.warn("Idle session: {} for user: {}",
                            session.getSessionId(), principal);
                    }
                }
            }
        }
    }
}

ReactiveSessionInformation

Reactive version of session information.

public class ReactiveSessionInformation

{ .api }

Key Methods:

Object getPrincipal()

{ .api }

Returns the principal associated with this session.

String getSessionId()

{ .api }

Returns the session identifier.

Instant getLastAccessTime()

{ .api }

Returns the last access time as an Instant.

Example:

@Service
public class ReactiveSessionMonitor {

    private final ReactiveSessionRegistry sessionRegistry;

    public Flux<String> findIdleSessions(Duration idleThreshold) {
        Instant cutoff = Instant.now().minus(idleThreshold);

        return Mono.fromCallable(() -> sessionRegistry.getAllPrincipals())
            .flatMapMany(Flux::fromIterable)
            .flatMap(principal -> sessionRegistry.getAllSessions(principal))
            .filter(session -> session.getLastAccessTime().isBefore(cutoff))
            .map(ReactiveSessionInformation::getSessionId);
    }
}

Session Events

AbstractSessionEvent

Base class for all session-related events.

public abstract class AbstractSessionEvent extends ApplicationEvent

{ .api }

Subclasses:

SessionCreationEvent

Event published when a new session is created.

public class SessionCreationEvent extends AbstractSessionEvent

{ .api }

Example:

@Component
public class SessionEventListener {

    @EventListener
    public void handleSessionCreation(SessionCreationEvent event) {
        String sessionId = event.getId();
        logger.info("New session created: {}", sessionId);
        // Perform additional initialization
    }
}

SessionDestroyedEvent

Abstract event published when a session is destroyed.

public abstract class SessionDestroyedEvent extends AbstractSessionEvent

{ .api }

Key Methods:

String getId()

{ .api }

Returns the session ID of the destroyed session.

List<SecurityContext> getSecurityContexts()

{ .api }

Returns the security contexts associated with the destroyed session.

Example:

@Component
public class SessionDestructionListener {

    @EventListener
    public void handleSessionDestruction(SessionDestroyedEvent event) {
        String sessionId = event.getId();
        List<SecurityContext> contexts = event.getSecurityContexts();

        for (SecurityContext context : contexts) {
            Authentication auth = context.getAuthentication();
            if (auth != null) {
                logger.info("Session {} destroyed for user: {}",
                    sessionId, auth.getName());
                // Cleanup user-specific resources
            }
        }
    }
}

SessionIdChangedEvent

Event published when a session ID changes (e.g., for session fixation protection).

public class SessionIdChangedEvent extends AbstractSessionEvent

{ .api }

Key Methods:

String getOldSessionId()

{ .api }

Returns the old session ID.

String getNewSessionId()

{ .api }

Returns the new session ID.

Example:

@Component
public class SessionIdChangeListener {

    private final SessionRegistry sessionRegistry;

    @EventListener
    public void handleSessionIdChange(SessionIdChangedEvent event) {
        String oldId = event.getOldSessionId();
        String newId = event.getNewSessionId();

        logger.info("Session ID changed: {} -> {}", oldId, newId);

        // Update any external session tracking
        SessionInformation oldInfo = sessionRegistry.getSessionInformation(oldId);
        if (oldInfo != null) {
            sessionRegistry.removeSessionInformation(oldId);
            sessionRegistry.registerNewSession(newId, oldInfo.getPrincipal());
        }
    }
}

Concurrent Session Control

Configuration Example

@Configuration
@EnableWebSecurity
public class SessionManagementConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .sessionManagement(session -> session
                .maximumSessions(1)
                .maxSessionsPreventsLogin(true)
                .sessionRegistry(sessionRegistry())
                .expiredUrl("/session-expired")
            );
        return http.build();
    }

    @Bean
    public SessionRegistry sessionRegistry() {
        return new SessionRegistryImpl();
    }

    @Bean
    public HttpSessionEventPublisher httpSessionEventPublisher() {
        return new HttpSessionEventPublisher();
    }
}

Complete Implementation Example

@Configuration
public class ComprehensiveSessionConfig {

    @Bean
    public SessionRegistry sessionRegistry() {
        return new SessionRegistryImpl();
    }

    @Bean
    public HttpSessionEventPublisher httpSessionEventPublisher() {
        return new HttpSessionEventPublisher();
    }
}

@Service
public class SessionManagementService {

    private final SessionRegistry sessionRegistry;

    public SessionManagementService(SessionRegistry sessionRegistry) {
        this.sessionRegistry = sessionRegistry;
    }

    public void invalidateUserSessions(String username) {
        sessionRegistry.getAllSessions(username, false)
            .forEach(session -> {
                session.expireNow();
                sessionRegistry.removeSessionInformation(session.getSessionId());
            });
    }

    public List<SessionInfo> getUserSessionInfo(String username) {
        return sessionRegistry.getAllSessions(username, false).stream()
            .map(session -> new SessionInfo(
                session.getSessionId(),
                session.getLastRequest(),
                !session.isExpired()
            ))
            .collect(Collectors.toList());
    }

    public int getTotalActiveSessions() {
        return sessionRegistry.getAllPrincipals().stream()
            .mapToInt(principal ->
                sessionRegistry.getAllSessions(principal, false).size())
            .sum();
    }

    public boolean isSessionLimitExceeded(String username, int maxSessions) {
        int currentSessions = sessionRegistry.getAllSessions(username, false).size();
        return currentSessions >= maxSessions;
    }

    public void expireOldestSession(String username) {
        List<SessionInformation> sessions =
            sessionRegistry.getAllSessions(username, false);

        sessions.stream()
            .min(Comparator.comparing(SessionInformation::getLastRequest))
            .ifPresent(oldest -> {
                oldest.expireNow();
                sessionRegistry.removeSessionInformation(oldest.getSessionId());
            });
    }
}

@Component
public class SessionEventHandler {

    private static final Logger logger = LoggerFactory.getLogger(SessionEventHandler.class);

    @EventListener
    public void onSessionCreated(SessionCreationEvent event) {
        logger.info("Session created: {}", event.getId());
    }

    @EventListener
    public void onSessionDestroyed(SessionDestroyedEvent event) {
        logger.info("Session destroyed: {}", event.getId());
        event.getSecurityContexts().stream()
            .map(SecurityContext::getAuthentication)
            .filter(Objects::nonNull)
            .forEach(auth -> logger.info("User logged out: {}", auth.getName()));
    }

    @EventListener
    public void onSessionIdChanged(SessionIdChangedEvent event) {
        logger.info("Session ID changed from {} to {}",
            event.getOldSessionId(), event.getNewSessionId());
    }
}

@RestController
@RequestMapping("/api/admin/sessions")
public class SessionAdminController {

    private final SessionManagementService sessionService;

    @GetMapping("/active")
    public int getActiveSessions() {
        return sessionService.getTotalActiveSessions();
    }

    @GetMapping("/user/{username}")
    public List<SessionInfo> getUserSessions(@PathVariable String username) {
        return sessionService.getUserSessionInfo(username);
    }

    @DeleteMapping("/user/{username}")
    public void invalidateUserSessions(@PathVariable String username) {
        sessionService.invalidateUserSessions(username);
    }
}

record SessionInfo(String sessionId, Date lastAccess, boolean active) {}

Package

org.springframework.security.core.session

Install with Tessl CLI

npx tessl i tessl/maven-spring-security-core

tessl/maven-spring-security-core