spring-security/docs/guides/src/asciidoc/form.asc

= Creating a Custom Login Form
:author: Rob Winch
:starter-appname: hellomvc-jc
:completed-appname: form-jc
:include-dir: _includes

This guide builds off of link:hellomvc.html[Hello Spring MVC Security Java Config] to explain how to configure and use a custom login form with Spring Security Java Configuration.

include::{include-dir}/setting-up-the-sample.asc[]

Verify the application is working:

* A page displaying a user's inbox can be seen at http://localhost:8080/sample/
* Try clicking on the Compose link and creating a message. The message details should be displayed.
* Now click on the Inbox link and see the message listed. You can click on the summary link to see the details displayed again.


= Overriding the default configure(HttpSecurity) method

As we saw in link:hellomvc.html[Hello Spring MVC Security Java Config], Spring Security's `WebSecurityConfigurerAdapter` provides some convenient defaults to get our application
up and running quickly. However, our login form does not look like the rest of our application. Let's see how we can update our configuration to use a custom form.

== Default configure(HttpSecurity)

The default configuration for the configure(HttpSecurity) method can be seen below:

[source,java]
----
protected void configure(HttpSecurity http) throws Exception {
    http
        .authorizeRequests()
            .anyRequest().authenticated() <1>
            .and()
        .formLogin()                      <2>
            .and()
        .httpBasic();                     <3>
}
----

The configuration ensures that:

<1> every request requires the user to be authenticated
<2> form based authentication is supported
<3> HTTP Basic Authentication is supported

== Configuring a custom login page

We will want to ensure we compensate for overriding these defaults in our updates. Open up the `SecurityConfig` and insert the configure method as shown below:

.src/main/java/org/springframework/security/samples/config/SecurityConfig.java
[source,java]
----
// ...

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .anyRequest().authenticated()
                .and()
            .formLogin()
                .loginPage("/login");
    }

    // ...
}
----

The line `loginPage("/login")` instructs Spring Security

* when authentication is required, redirect the browser to */login*
* we are in charge of rendering the login page when */login* is requested
* when authentication attempt fails, redirect the browser to */login?error* (since we have not specified otherwise)
* we are in charge of rendering a failure page when */login?error* is requested
* when we successfully logout, redirect the browser to */login?logout* (since we have not specified otherwise)
* we are in charge of rendering a logout confirmation page when */login?logout* is requested

Go ahead and start up the server and try visiting http://localhost:8080/sample/ to see the updates to our configuration. In many browsers you will see an error similar to *This webpage has a redirect loop*. What is happening?

== Granting access to unauthenticated users

The issue is that Spring Security is protecting access to our custom login page. In particular the following is happening:

* We make a request to our web application
* Spring Security sees that we are not authenticated
* We are redirected to */login*
* The browser requests */login*
* Spring Security sees that we are not authenticated
* We are redirected to */login* ...

To fix this we need to instruct Spring Security to allow anyone to access the */login* URL. We can easily do this with the following updates:

.src/main/java/org/springframework/security/samples/config/SecurityConfig.java
[source,java]
----
// ...

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .anyRequest().authenticated()
                .and()
            .formLogin()
                .loginPage("/login")
                .permitAll();
    }

    // ...
}
----

The `permitAll()` statement instructs Spring Security to allow any access to any URL (i.e. */login* and */login?error*) associated to `formLogin()`.

NOTE: Granting access to the `formLogin()` URLs is not done by default since Spring Security needs to make certain assumptions about what is allowed and what is not. To be secure, it is best to ensure granting access to resources is explicit.

Start up the server and try visiting http://localhost:8080/sample/ to see the updates to our configuration. You should now get a 404 error stating that */login* cannot be found.

= Creating a login page

Within Spring Web MVC there are two steps to creating our login page:

* Creating a controller
* Creating a view

== Configuring a login view controller

Within Spring Web MVC, the first step is to ensure that we have a controller that can point to our view. Since our project adds the *messages-jc* project as a dependency and it contains a view controller for */login* we do not need to create a controller within our application. For reference, you can see the configuration below:

[source,java]
----
// ...

@EnableWebMvc
@ComponentScan("org.springframework.security.samples.mvc")
public class WebMvcConfiguration extends WebMvcConfigurerAdapter {

    // ...

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        registry.addViewController("/login").setViewName("login");
        registry.setOrder(Ordered.HIGHEST_PRECEDENCE);
    }
}
----

== Creating a login view

Our existing configuration means that all we need to do is create a *login.html* file with the following contents:

.src/main/resources/views/login.html
[source,xml]
----
<html xmlns:th="http://www.thymeleaf.org" xmlns:tiles="http://www.thymeleaf.org">
  <head>
    <title tiles:fragment="title">Messages : Create</title>
  </head>
  <body>
    <div tiles:fragment="content">
        <form name="f" th:action="@{/login}" method="post">               <1>
            <fieldset>
                <legend>Please Login</legend>
                <div th:if="${param.error}" class="alert alert-error">    <2>
                    Invalid username and password.
                </div>
                <div th:if="${param.logout}" class="alert alert-success"> <3>
                    You have been logged out.
                </div>
                <label for="username">Username</label>
                <input type="text" id="username" name="username"/>        <4>
                <label for="password">Password</label>
                <input type="password" id="password" name="password"/>    <5>
                <div class="form-actions">
                    <button type="submit" class="btn">Log in</button>
                </div>
            </fieldset>
        </form>
    </div>
  </body>
</html>
----

<1> The URL we submit our username and password to is the same URL as our login form (i.e. */login*), but a *POST* instead of a *GET*.
<2> When authentication fails, the browser is redirected to */login?error* so we can display an error message by detecting if the parameter *error* is non-null.
<3> When we are successfully logged out, the browser is redirected to */login?logout* so we can display an logout success message by detecting if the parameter *logout* is non-null.
<4> The username should be present on the HTTP parameter username
<5> The password should be present on the HTTP parameter password

IMPORTANT: Do not display details about why authentication failed. For example, we do not want to display that the user does not exist as this will tell an attacker that they should try a different username.

TIP: We use Spring Web MVC's <form:form> tag to automatically add the CSRF token to our form. We could also manually add the CSRF token using `<input type="hidden" name="${_csrf.parameterName}" value="${_csrf.token}"/>`.

Start up the server and try visiting http://localhost:8080/sample/ to see the updates to our configuration. We now see our login page, but it does not look very pretty. The issue is that we have not granted access to the css files.

== Grant access to remaining resources

We need to update our configuration to allow anyone to access our resources and our logout pages. Update the configuration as shown below:

.src/main/java/org/springframework/security/samples/config/SecurityConfig.java
[source,java]
----
// ...

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests()
                .antMatchers("/resources/**").permitAll() <1>
                .anyRequest().authenticated()
                .and()
            .formLogin()
                .loginPage("/login")
                .permitAll()
                .and()
            .logout()                                    <2>
                .permitAll();
    }

    // ...
}
----

<1> This allows anyone to access a URL that begins with */resources/*. Since this is where our css, javascript, and images are stored all our static resources are viewable by anyone.
<2> As you might expect, `logout().permitAll()` allows any user to request logout and view logout success URL.


Start up the server and try visiting http://localhost:8080/sample/ to see the updates to our configuration. We now see a custom login page that looks like the rest of our application.

* Try entering an invalid username and password. You will see our error message is displayed.
* Try entering a valid username and password. You will be authenticated successfully.
* Try clicking the Log Out button. You will see our logout success message

== Conclusion

You should now know how to add a custom login form using Spring Security's Java Configuration. To learn more refer to the link:index.html[Spring Security Guides index page].