Spring Security Form Login Example ~ Requirement Constraints

Thanks to mkyong. This tutorial is based on his tutorial

Spring Security allows developer to integrate security features with J2EE web application easily, it highjacks incoming HTTP request via servlet filters, and implements “user defined” security checking.

By default, if no login form is provided, Spring Security will create a simple login form automatically, see demonstration in this Spring Security hello world example.
In this tutorial, we show you how to create a custom login form and ask Spring Security to use it for login authentication.

Technologies used :

Spring 3.0.5.RELEASE
Spring Security 3.0.5.RELEASE
Eclipse Indigo
JDK 1.6
Maven 3

Step : 1

If you are new java and Maven, then first setup environment in your local document. This document will help you to set up Java, Maven and Tomcat.

Step : 2

In the Eclipse IDE, Select File –> New –> Other –> Maven Project as shown here.

In the next screen, Verify that the Create a simple project checkbox is disabled and click Next.

In the next screen, Enter maven-archetype-webapp as a filter, select maven-archetype-webapp in the artifact list and click Next

In the next screen, enter the values as shown and Click Finish

After finish, the following project will be created with the folders as shown.

Step : 3

Let us create our java folder where we will create all required java classes here. Goto the Project springformlogin ->Src->Main and Right click and say new folder.
Enter the new folder name as "Java".
Now let include this folder into Project build path.Follow the steps
Select springformlogin in the Navigator.
Right Click and Select Properties
Select Java Build Path in the Left hand Tree.
Go to Source Tab
Select "Add Folder" in the right hand side.
Select Java Folder and click ok.
Now select Edit and enter "**/*.java" in inclusion pattern in the top.

Step : 4

POM File changes. Let us do the following changes in the POM.XML File
1. By default, Maven 3 will use the JDK 1.4 to compile the source of your project, which is rather old and obsolete. Fortunately, Maven comes with a Maven Compiler Plugin, which enable Maven to compile the project source with a particular JDK version.

2. Spring Security Dependencies: To use Spring security 3.0, you need “spring-security-core.jar“, “spring-security-web.jar” and “spring-security-config.jar“. Spring libraries are available in Maven central repository. Let us add this into POM.XML File as follows (You can remove all the content and copy from here and paste it)
3. And also, we will use jstl dependency.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>springformlogin</groupId>
    <artifactId>springformlogin</artifactId>
    <packaging>war</packaging>
    <version>0.0.1-SNAPSHOT</version>
    <name>springformlogin Maven Webapp</name>
    <url>http://maven.apache.org</url>

    <properties>
        <spring.version>3.0.5.RELEASE</spring.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>junit</groupId>
            <artifactId>junit</artifactId>
            <version>3.8.1</version>
            <scope>test</scope>
        </dependency>

        <!-- Spring 3 -->
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-core</artifactId>
            <version>${spring.version}</version>
        </dependency>

        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-web</artifactId>
            <version>${spring.version}</version>
        </dependency>

        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
            <version>${spring.version}</version>
        </dependency>

        <!-- Spring Security -->
        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-core</artifactId>
            <version>${spring.version}</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-web</artifactId>
            <version>${spring.version}</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-config</artifactId>
            <version>${spring.version}</version>
        </dependency>

    <!-- jstl -->
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>jstl</artifactId>
            <version>1.2</version>
        </dependency>
        
    </dependencies>
    <build>
        <finalName>springformlogin</finalName>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>2.3.1</version>
                <configuration>
                    <source>1.6</source>
                    <target>1.6</target>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Step : 5

Spring controller to handle what URL should go where. Select java folder and Select new Class. Give the package name as "com.example.common.controller" and class name as "LoginController". After clicking Finish, folders will be created and will look as follows

And paste the following code in the java file

package com.example.common.controller;

import java.security.Principal;
import org.springframework.stereotype.Controller;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
 
@Controller
public class LoginController {
 
    @RequestMapping(value="/welcome", method = RequestMethod.GET)
    public String printWelcome(ModelMap model, Principal principal ) {
 
        String name = principal.getName();
        model.addAttribute("username", name);
        model.addAttribute("message", "Spring Security Custom Form example");
        return "hello";
 
    }
 
    @RequestMapping(value="/login", method = RequestMethod.GET)
    public String login(ModelMap model) {
 
        return "login";
 
    }
    
    @RequestMapping(value="/loginfailed", method = RequestMethod.GET)
    public String loginerror(ModelMap model) {
 
        model.addAttribute("error", "true");
        return "login";
 
    }
    
    @RequestMapping(value="/logout", method = RequestMethod.GET)
    public String logout(ModelMap model) {
 
        return "login";
 
    }
    
}

Step : 6

Now let us create the JSP Page. Create a new folder called "Pages" under webapp\web-inf folder as shown here.

Now right click on pages folder and Select new jsp file and give the name as "hello.jsp". Replace the default content and paste the following

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"%>
<html>
<body>
    <h3>Message : ${message}</h3>
    <h3>Username : ${username}</h3>

    <a href="<c:url value="/j_spring_security_logout" />" > Logout</a>

</body>
</html>

File : login.jsp

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core"%>
<html>
<head>
<title>Login Page</title>
<style>
.errorblock {
    color: #ff0000;
    background-color: #ffEEEE;
    border: 3px solid #ff0000;
    padding: 8px;
    margin: 16px;
}
</style>
</head>
<body onload='document.f.j_username.focus();'>
    <h3>Login with Username and Password (Custom Page)</h3>

    <c:if test="${not empty error}">
        <div class="errorblock">
            Your login attempt was not successful, try again.<br /> Caused :
            ${sessionScope["SPRING_SECURITY_LAST_EXCEPTION"].message}
        </div>
    </c:if>

    <form name='f' action="<c:url value='j_spring_security_check' />"
        method='POST'>

        <table>
            <tr>
                <td>User:</td>
                <td><input type='text' name='j_username' value=''>
                </td>
            </tr>
            <tr>
                <td>Password:</td>
                <td><input type='password' name='j_password' />
                </td>
            </tr>
            <tr>
                <td colspan='2'><input name="submit" type="submit"
                    value="submit" />
                </td>
            </tr>
            <tr>
                <td colspan='2'><input name="reset" type="reset" />
                </td>
            </tr>
        </table>

    </form>
</body>
</html>

Step : 7

Right click on web-INF Folder and Select new file and Enter the file name as "mvc-dispatcher-servlet.xml"

Paste the following content

<beans xmlns="http://www.springframework.org/schema/beans"
    xmlns:context="http://www.springframework.org/schema/context"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="
        http://www.springframework.org/schema/beans     
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
        http://www.springframework.org/schema/context 
        http://www.springframework.org/schema/context/spring-context-3.0.xsd">

    <context:component-scan base-package="com.example.common.controller" />

    <bean
        class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="prefix">
            <value>/WEB-INF/pages/</value>
        </property>
        <property name="suffix">
            <value>.jsp</value>
        </property>
    </bean>

    <bean id="messageSource"
        class="org.springframework.context.support.ResourceBundleMessageSource">
        <property name="basenames">
            <list>
                <value>mymessages</value>
            </list>
        </property>
    </bean>
    
</beans>

Step : 8

Now let us add the spring security. Right click on web-INF Folder and Select new file and Enter the file name as "spring-security.xml"

login-page=”/login” – The login form will be “/login”
default-target-url=”/welcome” – If authentication success, forward to “/welcome”
authentication-failure-url=”/loginfailed” – If authentication failed, forward to “/loginfailed”
logout-success-url=”/logout” – If logout , forward to “/logout”

Paste the following content

<beans:beans xmlns="http://www.springframework.org/schema/security"
    xmlns:beans="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
    http://www.springframework.org/schema/security
    http://www.springframework.org/schema/security/spring-security-3.0.3.xsd">

    <http auto-config="true">
        <intercept-url pattern="/welcome*" access="ROLE_USER" />
        <form-login login-page="/login" default-target-url="/welcome"
            authentication-failure-url="/loginfailed" />
        <logout logout-success-url="/logout" />
    </http>

    <authentication-manager>
        <authentication-provider>
            <user-service>
                <user name="mkyong" password="123456" authorities="ROLE_USER" />
            </user-service>
        </authentication-provider>
    </authentication-manager>

</beans:beans>

Step : 9

To integrate Spring security with web application, just declare “DelegatingFilterProxy” as servlet filter to intercept incoming request.Open WEB.xml and replace with the following one.

<web-app id="WebApp_ID" version="2.4"
    xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee 
    http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

    <display-name>Spring MVC Application</display-name>

    <!-- Spring MVC -->
    <servlet>
        <servlet-name>mvc-dispatcher</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>
    <servlet-mapping>
        <servlet-name>mvc-dispatcher</servlet-name>
        <url-pattern>/</url-pattern>
    </servlet-mapping>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>
            /WEB-INF/mvc-dispatcher-servlet.xml,
            /WEB-INF/spring-security.xml
        </param-value>
    </context-param>

    <!-- Spring Security -->
    <filter>
        <filter-name>springSecurityFilterChain</filter-name>
        <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>springSecurityFilterChain</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

</web-app>

Step : 10

Default Spring’s error message is not user friendly enough. In Spring Security, when authentication is failed, following predefined error messages will be displayed

Spring display : Bad credentials

We can override above error message and display your custom error message. Spring Security stored messages in “messages.properties” inside “spring-security-core.jar“. To override it, find which key generate what error message in spring security message.properties file, and redefine it with your own properties file.

Create a new properties file, put it on project classpath, and override the Spring’s “key” with your custom error message. In this case, just override “AbstractUserDetailsAuthenticationProvider.badCredentials“.

File : mymessages.properties

AbstractUserDetailsAuthenticationProvider.badCredentials=Invalid username or password

Step : 11
Now let us start the server .

Access URL “http://localhost:8080/springformlogin/welcome“, Spring will redirect to your custom login form.

If username/password is wrong, authentication failed, display custom error messages.

If username/password is correct, authentication success, display requested page.

Requirement Constraints

Sunday, 6 January 2013