Package org.springframework.security.config.annotation.web.configurers

Class SessionManagementConfigurer<H extends HttpSecurityBuilder<H>>

java.lang.Object

org.springframework.security.config.annotation.SecurityConfigurerAdapter<DefaultSecurityFilterChain,B>

org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer<SessionManagementConfigurer<H>,H>

org.springframework.security.config.annotation.web.configurers.SessionManagementConfigurer<H>

All Implemented Interfaces:

SecurityConfigurer<DefaultSecurityFilterChain,H>

public final class SessionManagementConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractHttpConfigurer<SessionManagementConfigurer<H>,H>

Allows configuring session management.

Security Filters

The following Filters are populated

• SessionManagementFilter
• ConcurrentSessionFilter if there are restrictions on how many concurrent sessions a user can have

Shared Objects Created

The following shared objects are created:

• RequestCache
• SecurityContextRepository
• SessionManagementConfigurer
• InvalidSessionStrategy

Shared Objects Used

• SecurityContextRepository
• AuthenticationTrustResolver is optionally used to populate the HttpSessionSecurityContextRepository and SessionManagementFilter

Since:

3.2

See Also:

• SessionManagementFilter
• ConcurrentSessionFilter

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
final class	SessionManagementConfigurer.ConcurrencyControlConfigurer	Allows configuring controlling of multiple sessions.
final class	SessionManagementConfigurer.SessionFixationConfigurer	Allows configuring SessionFixation protection

Constructor Summary

Constructors

Constructor	Description
SessionManagementConfigurer()	Creates a new instance

Method Summary

Modifier and Type	Method	Description
SessionManagementConfigurer<H>	addSessionAuthenticationStrategy(SessionAuthenticationStrategy sessionAuthenticationStrategy)	Adds an additional SessionAuthenticationStrategy to be used within the CompositeSessionAuthenticationStrategy.
void	configure(H http)	Configure the SecurityBuilder by setting the necessary properties on the SecurityBuilder.
SessionManagementConfigurer<H>	enableSessionUrlRewriting(boolean enableSessionUrlRewriting)	If set to true, allows HTTP sessions to be rewritten in the URLs when using HttpServletResponse.encodeRedirectURL(String) or HttpServletResponse.encodeURL(String), otherwise disallows HTTP sessions to be included in the URL.
void	init(H http)	Initialize the SecurityBuilder.
SessionManagementConfigurer<H>	invalidSessionStrategy(InvalidSessionStrategy invalidSessionStrategy)	Setting this attribute will inject the provided invalidSessionStrategy into the SessionManagementFilter.
SessionManagementConfigurer<H>	invalidSessionUrl(String invalidSessionUrl)	Setting this attribute will inject the SessionManagementFilter with a SimpleRedirectInvalidSessionStrategy configured with the attribute value.
SessionManagementConfigurer<H>.ConcurrencyControlConfigurer	maximumSessions(int maximumSessions)	Controls the maximum number of sessions for a user.
SessionManagementConfigurer<H>	requireExplicitAuthenticationStrategy(boolean requireExplicitAuthenticationStrategy)	Setting this means that explicit invocation of SessionAuthenticationStrategy is required.
SessionManagementConfigurer<H>	sessionAuthenticationErrorUrl(String sessionAuthenticationErrorUrl)	Defines the URL of the error page which should be shown when the SessionAuthenticationStrategy raises an exception.
SessionManagementConfigurer<H>	sessionAuthenticationFailureHandler(AuthenticationFailureHandler sessionAuthenticationFailureHandler)	Defines the AuthenticationFailureHandler which will be used when the SessionAuthenticationStrategy raises an exception.
SessionManagementConfigurer<H>	sessionAuthenticationStrategy(SessionAuthenticationStrategy sessionAuthenticationStrategy)	Allows explicitly specifying the SessionAuthenticationStrategy.
SessionManagementConfigurer<H>	sessionConcurrency(Customizer<SessionManagementConfigurer<H>.ConcurrencyControlConfigurer> sessionConcurrencyCustomizer)	Controls the maximum number of sessions for a user.
SessionManagementConfigurer<H>	sessionCreationPolicy(SessionCreationPolicy sessionCreationPolicy)	Allows specifying the SessionCreationPolicy
SessionManagementConfigurer<H>.SessionFixationConfigurer	sessionFixation()	Allows changing the default SessionFixationProtectionStrategy.
SessionManagementConfigurer<H>	sessionFixation(Customizer<SessionManagementConfigurer<H>.SessionFixationConfigurer> sessionFixationCustomizer)	Allows configuring session fixation protection.

Methods inherited from class org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer

disable, getSecurityContextHolderStrategy, withObjectPostProcessor, withObjectPostProcessor

Methods inherited from class org.springframework.security.config.annotation.SecurityConfigurerAdapter

addObjectPostProcessor, addObjectPostProcessor, and, getBuilder, postProcess, setBuilder

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

SessionManagementConfigurer

public SessionManagementConfigurer()

Creates a new instance

See Also:

• HttpSecurity.sessionManagement()

Method Details

invalidSessionUrl

public SessionManagementConfigurer<H> invalidSessionUrl(String invalidSessionUrl)

Setting this attribute will inject the SessionManagementFilter with a SimpleRedirectInvalidSessionStrategy configured with the attribute value. When an invalid session ID is submitted, the strategy will be invoked, redirecting to the configured URL.

Parameters:

invalidSessionUrl - the URL to redirect to when an invalid session is detected

Returns:

the SessionManagementConfigurer for further customization

requireExplicitAuthenticationStrategy

public SessionManagementConfigurer<H> requireExplicitAuthenticationStrategy(boolean requireExplicitAuthenticationStrategy)

Setting this means that explicit invocation of SessionAuthenticationStrategy is required.

Parameters:

requireExplicitAuthenticationStrategy - require explicit invocation of SessionAuthenticationStrategy

Returns:

the SessionManagementConfigurer for further customization

invalidSessionStrategy

public SessionManagementConfigurer<H> invalidSessionStrategy(InvalidSessionStrategy invalidSessionStrategy)

Setting this attribute will inject the provided invalidSessionStrategy into the SessionManagementFilter. When an invalid session ID is submitted, the strategy will be invoked, redirecting to the configured URL.

Parameters:

invalidSessionStrategy - the strategy to use when an invalid session ID is submitted.

Returns:

the SessionManagementConfigurer for further customization

sessionAuthenticationErrorUrl

public SessionManagementConfigurer<H> sessionAuthenticationErrorUrl(String sessionAuthenticationErrorUrl)

Defines the URL of the error page which should be shown when the SessionAuthenticationStrategy raises an exception. If not set, an unauthorized (402) error code will be returned to the client. Note that this attribute doesn't apply if the error occurs during a form-based login, where the URL for authentication failure will take precedence.

Parameters:

sessionAuthenticationErrorUrl - the URL to redirect to

Returns:

the SessionManagementConfigurer for further customization

sessionAuthenticationFailureHandler

public SessionManagementConfigurer<H> sessionAuthenticationFailureHandler(AuthenticationFailureHandler sessionAuthenticationFailureHandler)

Defines the AuthenticationFailureHandler which will be used when the SessionAuthenticationStrategy raises an exception. If not set, an unauthorized (402) error code will be returned to the client. Note that this attribute doesn't apply if the error occurs during a form-based login, where the URL for authentication failure will take precedence.

Parameters:

sessionAuthenticationFailureHandler - the handler to use

Returns:

the SessionManagementConfigurer for further customization

enableSessionUrlRewriting

public SessionManagementConfigurer<H> enableSessionUrlRewriting(boolean enableSessionUrlRewriting)

If set to true, allows HTTP sessions to be rewritten in the URLs when using HttpServletResponse.encodeRedirectURL(String) or HttpServletResponse.encodeURL(String), otherwise disallows HTTP sessions to be included in the URL. This prevents leaking information to external domains.

This is achieved by guarding HttpServletResponse.encodeURL(java.lang.String) and HttpServletResponse.encodeRedirectURL(java.lang.String) invocations. Any code that also overrides either of these two methods, like ResourceUrlEncodingFilter, needs to come after the security filter chain or risk being skipped.

Parameters:

enableSessionUrlRewriting - true if should allow the JSESSIONID to be rewritten into the URLs, else false (default)

Returns:

the SessionManagementConfigurer for further customization

See Also:

• HttpSessionSecurityContextRepository.setDisableUrlRewriting(boolean)

sessionCreationPolicy

public SessionManagementConfigurer<H> sessionCreationPolicy(SessionCreationPolicy sessionCreationPolicy)

Allows specifying the SessionCreationPolicy

Parameters:

sessionCreationPolicy - the SessionCreationPolicy to use. Cannot be null.

Returns:

the SessionManagementConfigurer for further customizations

Throws:

IllegalArgumentException - if SessionCreationPolicy is null.

See Also:

• SessionCreationPolicy

sessionAuthenticationStrategy

public SessionManagementConfigurer<H> sessionAuthenticationStrategy(SessionAuthenticationStrategy sessionAuthenticationStrategy)

Allows explicitly specifying the SessionAuthenticationStrategy. The default is to use ChangeSessionIdAuthenticationStrategy. If restricting the maximum number of sessions is configured, then CompositeSessionAuthenticationStrategy delegating to ConcurrentSessionControlAuthenticationStrategy, the default OR supplied SessionAuthenticationStrategy and RegisterSessionAuthenticationStrategy.

NOTE: Supplying a custom SessionAuthenticationStrategy will override the default session fixation strategy.

Parameters:

sessionAuthenticationStrategy -

Returns:

the SessionManagementConfigurer for further customizations

addSessionAuthenticationStrategy

public SessionManagementConfigurer<H> addSessionAuthenticationStrategy(SessionAuthenticationStrategy sessionAuthenticationStrategy)

Adds an additional SessionAuthenticationStrategy to be used within the CompositeSessionAuthenticationStrategy.

Parameters:

sessionAuthenticationStrategy -

Returns:

the SessionManagementConfigurer for further customizations

sessionFixation

public SessionManagementConfigurer<H>.SessionFixationConfigurer sessionFixation()

Allows changing the default SessionFixationProtectionStrategy.

Returns:

the SessionManagementConfigurer<H extends HttpSecurityBuilder<H>>.SessionFixationConfigurer for further customizations

sessionFixation

public SessionManagementConfigurer<H> sessionFixation(Customizer<SessionManagementConfigurer<H>.SessionFixationConfigurer> sessionFixationCustomizer)

Allows configuring session fixation protection.

Parameters:

sessionFixationCustomizer - the Customizer to provide more options for the SessionManagementConfigurer<H extends HttpSecurityBuilder<H>>.SessionFixationConfigurer

Returns:

the SessionManagementConfigurer for further customizations

maximumSessions

public SessionManagementConfigurer<H>.ConcurrencyControlConfigurer maximumSessions(int maximumSessions)

Controls the maximum number of sessions for a user. The default is to allow any number of sessions.

Parameters:

maximumSessions - the maximum number of sessions for a user

Returns:

the SessionManagementConfigurer for further customizations

sessionConcurrency

public SessionManagementConfigurer<H> sessionConcurrency(Customizer<SessionManagementConfigurer<H>.ConcurrencyControlConfigurer> sessionConcurrencyCustomizer)

Controls the maximum number of sessions for a user. The default is to allow any number of users.

Parameters:

sessionConcurrencyCustomizer - the Customizer to provide more options for the SessionManagementConfigurer<H extends HttpSecurityBuilder<H>>.ConcurrencyControlConfigurer

Returns:

the SessionManagementConfigurer for further customizations

init

public void init(H http)

Description copied from interface: SecurityConfigurer

Initialize the SecurityBuilder. Here only shared state should be created and modified, but not properties on the SecurityBuilder used for building the object. This ensures that the SecurityConfigurer.configure(SecurityBuilder) method uses the correct shared objects when building. Configurers should be applied here.

Specified by:

init in interface SecurityConfigurer<DefaultSecurityFilterChain,H extends HttpSecurityBuilder<H>>

Overrides:

init in class SecurityConfigurerAdapter<DefaultSecurityFilterChain,H extends HttpSecurityBuilder<H>>

configure

public void configure(H http)

Description copied from interface: SecurityConfigurer

Configure the SecurityBuilder by setting the necessary properties on the SecurityBuilder.

Specified by:

configure in interface SecurityConfigurer<DefaultSecurityFilterChain,H extends HttpSecurityBuilder<H>>

Overrides:

configure in class SecurityConfigurerAdapter<DefaultSecurityFilterChain,H extends HttpSecurityBuilder<H>>