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

# Class SessionManagementConfigurer<H extends HttpSecurityBuilder<H>>

java.lang.Object
org.springframework.security.config.annotation.SecurityConfigurerAdapter<org.springframework.security.web.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<org.springframework.security.web.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(org.springframework.security.web.authentication.session.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(org.springframework.security.web.session.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(org.springframework.security.web.authentication.AuthenticationFailureHandler sessionAuthenticationFailureHandler)`
Defines the `AuthenticationFailureHandler` which will be used when the SessionAuthenticationStrategy raises an exception.
`SessionManagementConfigurer<H>`
`sessionAuthenticationStrategy(org.springframework.security.web.authentication.session.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(org.springframework.security.web.session.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(org.springframework.security.web.authentication.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(org.springframework.security.web.authentication.session.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(org.springframework.security.web.authentication.session.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<org.springframework.security.web.DefaultSecurityFilterChain,H extends HttpSecurityBuilder<H>>`
Overrides:
  `init` in class `SecurityConfigurerAdapter<org.springframework.security.web.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<org.springframework.security.web.DefaultSecurityFilterChain,H extends HttpSecurityBuilder<H>>`
Overrides:
  `configure` in class `SecurityConfigurerAdapter<org.springframework.security.web.DefaultSecurityFilterChain,H extends HttpSecurityBuilder<H>>`