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

Class FormLoginConfigurer<H extends HttpSecurityBuilder<H>>

java.lang.Object

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

org.springframework.security.config.annotation.web.configurers.AbstractHttpConfigurer<T,B>

org.springframework.security.config.annotation.web.configurers.AbstractAuthenticationFilterConfigurer<H,FormLoginConfigurer<H>,UsernamePasswordAuthenticationFilter>

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

All Implemented Interfaces:

SecurityConfigurer<DefaultSecurityFilterChain,H>

public final class FormLoginConfigurer<H extends HttpSecurityBuilder<H>>
extends AbstractAuthenticationFilterConfigurer<H,FormLoginConfigurer<H>,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 and Description
FormLoginConfigurer() Creates a new instance

Method Summary

Modifier and Type	Method and Description
protected RequestMatcher	createLoginProcessingUrlMatcher(java.lang.String loginProcessingUrl) Create the RequestMatcher given a loginProcessingUrl
FormLoginConfigurer<H>	failureForwardUrl(java.lang.String forwardUrl) Forward Authentication Failure Handler
void	init(H http) Initialize the SecurityBuilder.
FormLoginConfigurer<H>	loginPage(java.lang.String loginPage) Specifies the URL to send users to if login is required.
FormLoginConfigurer<H>	passwordParameter(java.lang.String passwordParameter) The HTTP parameter to look for the password when performing authentication.
FormLoginConfigurer<H>	successForwardUrl(java.lang.String forwardUrl) Forward Authentication Success Handler
FormLoginConfigurer<H>	usernameParameter(java.lang.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, setAuthenticationFilter, successHandler, updateAccessDefaults, updateAuthenticationDefaults

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

disable, withObjectPostProcessor

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

addObjectPostProcessor, and, getBuilder, postProcess, setBuilder

Methods inherited from class java.lang.Object

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

Constructor Detail

FormLoginConfigurer

public FormLoginConfigurer()

Creates a new instance

See Also:

HttpSecurity.formLogin()

Method Detail

loginPage

public FormLoginConfigurer<H> loginPage(java.lang.String loginPage)

Specifies the URL to send users to if login is required. If used with WebSecurityConfigurerAdapter 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 conjuction with WebSecurityConfigurerAdapter, 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>>,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(java.lang.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(java.lang.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(java.lang.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(java.lang.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 java.lang.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<DefaultSecurityFilterChain,H extends HttpSecurityBuilder<H>>

Overrides:

init in class AbstractAuthenticationFilterConfigurer<H extends HttpSecurityBuilder<H>,FormLoginConfigurer<H extends HttpSecurityBuilder<H>>,UsernamePasswordAuthenticationFilter>

Throws:

java.lang.Exception

createLoginProcessingUrlMatcher

protected RequestMatcher createLoginProcessingUrlMatcher(java.lang.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>>,UsernamePasswordAuthenticationFilter>

Parameters:

loginProcessingUrl - creates the RequestMatcher based upon the loginProcessingUrl

Returns:

the RequestMatcher to use based upon the loginProcessingUrl