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

# Class FormLoginConfigurer<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<T,B>
org.springframework.security.config.annotation.web.configurers.AbstractAuthenticationFilterConfigurer<H,FormLoginConfigurer<H>,org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter>
org.springframework.security.config.annotation.web.configurers.FormLoginConfigurer<H>

All Implemented Interfaces:
  `SecurityConfigurer<org.springframework.security.web.DefaultSecurityFilterChain,H>`

public final class FormLoginConfigurer<H extends HttpSecurityBuilder<H>> extends AbstractAuthenticationFilterConfigurer<H,FormLoginConfigurer<H>,org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter>
Adds form based authentication. All attributes have reasonable defaults making all parameters are optional. If no `loginPage(String)` is specified, a default login page will be generated by the framework.

## Security Filters

The following Filters are populated

- `UsernamePasswordAuthenticationFilter`

## Shared Objects Created

The following shared objects are populated

- `AuthenticationEntryPoint`

## Shared Objects Used

The following shared objects are used:

- `AuthenticationManager`
- `RememberMeServices` - is optionally used. See `RememberMeConfigurer`
- `SessionAuthenticationStrategy` - is optionally used. See `SessionManagementConfigurer`
- `DefaultLoginPageGeneratingFilter` - if present will be populated with information from the configuration

Since:
  3.2

## Constructor Summary

Constructors
Constructor
Description
`FormLoginConfigurer()`
Creates a new instance

## Method Summary

Modifier and Type
Method
Description
`protected org.springframework.security.web.util.matcher.RequestMatcher`
`createLoginProcessingUrlMatcher(String loginProcessingUrl)`
Create the `RequestMatcher` given a loginProcessingUrl
`FormLoginConfigurer<H>`
`failureForwardUrl(String forwardUrl)`
Forward Authentication Failure Handler
`void`
`init(H http)`
Initialize the `SecurityBuilder`.
`FormLoginConfigurer<H>`
`loginPage(String loginPage)`
Specifies the URL to send users to if login is required.
`FormLoginConfigurer<H>`
`passwordParameter(String passwordParameter)`
The HTTP parameter to look for the password when performing authentication.
`FormLoginConfigurer<H>`
`successForwardUrl(String forwardUrl)`
Forward Authentication Success Handler
`FormLoginConfigurer<H>`
`usernameParameter(String usernameParameter)`
The HTTP parameter to look for the username when performing authentication.

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

`authenticationDetailsSource, configure, defaultSuccessUrl, defaultSuccessUrl, failureHandler, failureUrl, getAuthenticationEntryPoint, getAuthenticationEntryPointMatcher, getAuthenticationFilter, getFailureUrl, getLoginPage, getLoginProcessingUrl, isCustomLoginPage, loginProcessingUrl, permitAll, permitAll, registerAuthenticationEntryPoint, registerDefaultAuthenticationEntryPoint, securityContextRepository, setAuthenticationFilter, successHandler, updateAccessDefaults, updateAuthenticationDefaults`

### 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

### FormLoginConfigurer

public FormLoginConfigurer()
Creates a new instance

See Also:
  - `HttpSecurity.formLogin()`

## Method Details

### loginPage

public FormLoginConfigurer<H> loginPage(String loginPage)

Specifies the URL to send users to if login is required. If used with `EnableWebSecurity` a default login page will be generated when this attribute is not specified.

If a URL is specified or this is not being used in conjunction with `EnableWebSecurity`, users are required to process the specified URL to generate a login page. In general, the login page should create a form that submits a request with the following requirements to work with `UsernamePasswordAuthenticationFilter`:

- It must be an HTTP POST
- It must be submitted to `AbstractAuthenticationFilterConfigurer.loginProcessingUrl(String)`
- It should include the username as an HTTP parameter by the name of `usernameParameter(String)`
- It should include the password as an HTTP parameter by the name of `passwordParameter(String)`

## Example login.jsp

Login pages can be rendered with any technology you choose so long as the rules above are followed. Below is an example login.jsp that can be used as a quick start when using JSP's or as a baseline to translate into another view technology.

     <c:url value="/login" var="loginProcessingUrl"/>
     <form action="${loginProcessingUrl}" method="post">
        <fieldset>
            <legend>Please Login</legend>
            <!-- use param.error assuming FormLoginConfigurer#failureUrl contains the query parameter error -->
            <c:if test="${param.error != null}">
                <div>
                    Failed to login.
                    <c:if test="${SPRING_SECURITY_LAST_EXCEPTION != null}">
                      Reason: <c:out value="${SPRING_SECURITY_LAST_EXCEPTION.message}" />
                    </c:if>
                </div>
            </c:if>
            <!-- the configured LogoutConfigurer#logoutSuccessUrl is /login?logout and contains the query param logout -->
            <c:if test="${param.logout != null}">
                <div>
                    You have been logged out.
                </div>
            </c:if>
            <p>
            <label for="username">Username</label>
            <input type="text" id="username" name="username"/>
            </p>
            <p>
            <label for="password">Password</label>
            <input type="password" id="password" name="password"/>
            </p>
            <!-- if using RememberMeConfigurer make sure remember-me matches RememberMeConfigurer#rememberMeParameter -->
            <p>
            <label for="remember-me">Remember Me?</label>
            <input type="checkbox" id="remember-me" name="remember-me"/>
            </p>
            <div>
                <button type="submit" class="btn">Log in</button>
            </div>
        </fieldset>
     </form>

## Impact on other defaults

Updating this value, also impacts a number of other default values. For example, the following are the default values when only formLogin() was specified.

- /login GET - the login form
- /login POST - process the credentials and if valid authenticate the user
- /login?error GET - redirect here for failed authentication attempts
- /login?logout GET - redirect here after successfully logging out

If "/authenticate" was passed to this method it update the defaults as shown below:

- /authenticate GET - the login form
- /authenticate POST - process the credentials and if valid authenticate the user
- /authenticate?error GET - redirect here for failed authentication attempts
- /authenticate?logout GET - redirect here after successfully logging out

Overrides:
  `loginPage` in class `AbstractAuthenticationFilterConfigurer<H extends HttpSecurityBuilder<H>,FormLoginConfigurer<H extends HttpSecurityBuilder<H>>,org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter>`
Parameters:
  `loginPage` - the login page to redirect to if authentication is required (i.e. "/login")
Returns:
  the `FormLoginConfigurer` for additional customization

### usernameParameter

public FormLoginConfigurer<H> usernameParameter(String usernameParameter)
The HTTP parameter to look for the username when performing authentication. Default is "username".

Parameters:
  `usernameParameter` - the HTTP parameter to look for the username when performing authentication
Returns:
  the `FormLoginConfigurer` for additional customization

### passwordParameter

public FormLoginConfigurer<H> passwordParameter(String passwordParameter)
The HTTP parameter to look for the password when performing authentication. Default is "password".

Parameters:
  `passwordParameter` - the HTTP parameter to look for the password when performing authentication
Returns:
  the `FormLoginConfigurer` for additional customization

### failureForwardUrl

public FormLoginConfigurer<H> failureForwardUrl(String forwardUrl)
Forward Authentication Failure Handler

Parameters:
  `forwardUrl` - the target URL in case of failure
Returns:
  the `FormLoginConfigurer` for additional customization

### successForwardUrl

public FormLoginConfigurer<H> successForwardUrl(String forwardUrl)
Forward Authentication Success Handler

Parameters:
  `forwardUrl` - the target URL in case of success
Returns:
  the `FormLoginConfigurer` for additional customization

### init

public void init(H http) throws Exception
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 `AbstractAuthenticationFilterConfigurer<H extends HttpSecurityBuilder<H>,FormLoginConfigurer<H extends HttpSecurityBuilder<H>>,org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter>`
Throws:
  `Exception`

### createLoginProcessingUrlMatcher

protected org.springframework.security.web.util.matcher.RequestMatcher createLoginProcessingUrlMatcher(String loginProcessingUrl)
Description copied from class: `AbstractAuthenticationFilterConfigurer`
Create the `RequestMatcher` given a loginProcessingUrl

Specified by:
  `createLoginProcessingUrlMatcher` in class `AbstractAuthenticationFilterConfigurer<H extends HttpSecurityBuilder<H>,FormLoginConfigurer<H extends HttpSecurityBuilder<H>>,org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter>`
Parameters:
  `loginProcessingUrl` - creates the `RequestMatcher` based upon the loginProcessingUrl
Returns:
  the `RequestMatcher` to use based upon the loginProcessingUrl