Package org.springframework.security.web.server.authentication

# Class SwitchUserWebFilter

java.lang.Object
org.springframework.security.web.server.authentication.SwitchUserWebFilter

All Implemented Interfaces:
  `org.springframework.web.server.WebFilter`

public class SwitchUserWebFilter extends Object implements org.springframework.web.server.WebFilter
Switch User processing filter responsible for user context switching. A common use-case for this feature is the ability to allow higher-authority users (e.g. ROLE_ADMIN) to switch to a regular user (e.g. ROLE_USER).

This filter assumes that the user performing the switch will be required to be logged in as normal user (i.e. with a ROLE_ADMIN role). The user will then access a page/controller that enables the administrator to specify who they wish to become (see `switchUserUrl`).

Note: This URL will be required to have appropriate security constraints configured so that only users of that role can access it (e.g. ROLE_ADMIN).

On a successful switch, the user's `SecurityContext` will be updated to reflect the specified user and will also contain an additional `SwitchUserGrantedAuthority` which contains the original user. Before switching, a check will be made on whether the user is already currently switched, and any current switch will be exited to prevent "nested" switches.

To 'exit' from a user context, the user needs to access a URL (see `exitUserUrl`) that will switch back to the original user as identified by the `ROLE_PREVIOUS_ADMINISTRATOR`.

To configure the Switch User Processing Filter, create a bean definition for the Switch User processing filter and add to the filterChainProxy. Note that the filter must come after the `org.springframework.security.config.web.server.SecurityWebFiltersOrder#AUTHORIZATION` in the chain, in order to apply the correct constraints to the `switchUserUrl`. Example:

     SwitchUserWebFilter filter = new SwitchUserWebFilter(userDetailsService, loginSuccessHandler, failureHandler);
     http.addFilterAfter(filter, SecurityWebFiltersOrder.AUTHORIZATION);

Since:
  5.4
See Also:
  - `SwitchUserGrantedAuthority`

## Field Summary

Fields
Modifier and Type
Field
Description
`static final String`
`ROLE_PREVIOUS_ADMINISTRATOR`
`static final String`
`SPRING_SECURITY_SWITCH_USERNAME_KEY`

## Constructor Summary

Constructors
Constructor
Description
`SwitchUserWebFilter(org.springframework.security.core.userdetails.ReactiveUserDetailsService userDetailsService, String successTargetUrl, String failureTargetUrl)`
Creates a filter for the user context switching
`SwitchUserWebFilter(org.springframework.security.core.userdetails.ReactiveUserDetailsService userDetailsService, ServerAuthenticationSuccessHandler successHandler, ServerAuthenticationFailureHandler failureHandler)`
Creates a filter for the user context switching

## Method Summary

Modifier and Type
Method
Description
`protected reactor.core.publisher.Mono<org.springframework.security.core.Authentication>`
`exitSwitchUser(WebFilterExchange webFilterExchange)`
Attempt to exit from an already switched user.
`reactor.core.publisher.Mono<Void>`
`filter(org.springframework.web.server.ServerWebExchange exchange, org.springframework.web.server.WebFilterChain chain)`
`protected String`
`getUsername(org.springframework.web.server.ServerWebExchange exchange)`
Returns the name of the target user.
`void`
`setExitUserMatcher(ServerWebExchangeMatcher exitUserMatcher)`
Set the matcher to respond to exit user processing.
`void`
`setExitUserUrl(String exitUserUrl)`
Set the URL to respond to exit user processing.
`void`
`setSecurityContextRepository(ServerSecurityContextRepository securityContextRepository)`
Sets the repository for persisting the SecurityContext.
`void`
`setSwitchUserMatcher(ServerWebExchangeMatcher switchUserMatcher)`
Set the matcher to respond to switch user processing.
`void`
`setSwitchUserUrl(String switchUserUrl)`
Set the URL to respond to switch user processing.
`protected reactor.core.publisher.Mono<org.springframework.security.core.Authentication>`
`switchUser(WebFilterExchange webFilterExchange)`
Attempt to switch to another user.

### Methods inherited from class java.lang.Object

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

## Field Details

### SPRING_SECURITY_SWITCH_USERNAME_KEY

public static final String SPRING_SECURITY_SWITCH_USERNAME_KEY

See Also:
  - Constant Field Values

### ROLE_PREVIOUS_ADMINISTRATOR

public static final String ROLE_PREVIOUS_ADMINISTRATOR

See Also:
  - Constant Field Values

## Constructor Details

### SwitchUserWebFilter

public SwitchUserWebFilter(org.springframework.security.core.userdetails.ReactiveUserDetailsService userDetailsService, ServerAuthenticationSuccessHandler successHandler, @Nullable ServerAuthenticationFailureHandler failureHandler)
Creates a filter for the user context switching

Parameters:
  `userDetailsService` - The `UserDetailsService` which will be used to load information for the user that is being switched to.
  `successHandler` - Used to define custom behaviour on a successful switch or exit user.
  `failureHandler` - Used to define custom behaviour when a switch fails.

### SwitchUserWebFilter

public SwitchUserWebFilter(org.springframework.security.core.userdetails.ReactiveUserDetailsService userDetailsService, String successTargetUrl, @Nullable String failureTargetUrl)
Creates a filter for the user context switching

Parameters:
  `userDetailsService` - The `UserDetailsService` which will be used to load information for the user that is being switched to.
  `successTargetUrl` - Sets the URL to go to after a successful switch / exit user request
  `failureTargetUrl` - The URL to which a user should be redirected if the switch fails

## Method Details

### filter

public reactor.core.publisher.Mono<Void> filter(org.springframework.web.server.ServerWebExchange exchange, org.springframework.web.server.WebFilterChain chain)

Specified by:
  `filter` in interface `org.springframework.web.server.WebFilter`

### switchUser

protected reactor.core.publisher.Mono<org.springframework.security.core.Authentication> switchUser(WebFilterExchange webFilterExchange)
Attempt to switch to another user.

Parameters:
  `webFilterExchange` - The web filter exchange
Returns:
  The new `Authentication` object if successfully switched to another user, `Mono.empty()` otherwise.
Throws:
  `org.springframework.security.authentication.AuthenticationCredentialsNotFoundException` - If the target user can not be found by username

### exitSwitchUser

protected reactor.core.publisher.Mono<org.springframework.security.core.Authentication> exitSwitchUser(WebFilterExchange webFilterExchange)
Attempt to exit from an already switched user.

Parameters:
  `webFilterExchange` - The web filter exchange
Returns:
  The original `Authentication` object.
Throws:
  `org.springframework.security.authentication.AuthenticationCredentialsNotFoundException` - If there is no `Authentication` associated with this request or the user is not switched.

### getUsername

protected String getUsername(org.springframework.web.server.ServerWebExchange exchange)
Returns the name of the target user.

Parameters:
  `exchange` - The server web exchange
Returns:
  the name of the target user.

### setSecurityContextRepository

public void setSecurityContextRepository(ServerSecurityContextRepository securityContextRepository)
Sets the repository for persisting the SecurityContext. Default is `WebSessionServerSecurityContextRepository`

Parameters:
  `securityContextRepository` - the repository to use

### setExitUserUrl

public void setExitUserUrl(String exitUserUrl)
Set the URL to respond to exit user processing. This is a shortcut for * `setExitUserMatcher(ServerWebExchangeMatcher)`

Parameters:
  `exitUserUrl` - The exit user URL.

### setExitUserMatcher

public void setExitUserMatcher(ServerWebExchangeMatcher exitUserMatcher)
Set the matcher to respond to exit user processing.

Parameters:
  `exitUserMatcher` - The exit matcher to use

### setSwitchUserUrl

public void setSwitchUserUrl(String switchUserUrl)
Set the URL to respond to switch user processing. This is a shortcut for `setSwitchUserMatcher(ServerWebExchangeMatcher)`

Parameters:
  `switchUserUrl` - The switch user URL.

### setSwitchUserMatcher

public void setSwitchUserMatcher(ServerWebExchangeMatcher switchUserMatcher)
Set the matcher to respond to switch user processing.

Parameters:
  `switchUserMatcher` - The switch user matcher.