9.2. Authentication

Caution

This version is already obsolete. Please check the latest guideline.

9.2.1. Overview

This chapter explains about Authentication function provided by Spring Security.

Authentication process checks the validity of user using the application.

The standard method to check the validity of a user is to register the users who can use the application in a data store and and verify the authentication information (user name, password etc) input by the user. Although a relational database is commonly used in a data store wherein user information is registered, directory service or external system etc are also used.

Further, there are several methods which ask a user to input authentication information. Although a method wherein input form of HTML or a method wherein an authentication method of HTTP standard defined in RFC (Basic authentication or Digest authentication etc) are used in general, the methods like OpenID authentication or single sign-on authentication are also used.

This section introduces an implementation example wherein the authentication is done by verifying authentication information input in HTML input form and user information stored in the relational database, and explains how to use authentication function of Spring Security.

9.2.1.1. Authentication process architecture

Spring Security performs authentication with the following flow.

Authentication process architecture

Sr. No.	Description
(1)	Client specifies credentials (user name and password) for the path wherein authentication is performed and sends a request.
(2)	Authentication Filter fetches credentials from the request and calls authentication process of AuthenticationManager class.
(3)	ProviderManager (Implementation class of AuthenticationManager used by default) delegates actual authentication process to implementation class of AuthenticationProvider interface.

9.2.1.1.1. Authentication Filter

Authentication Filter is a servlet filter which offers implementation for the authentication method. Primary authentication methods supported by Spring Security are as given below..

Main Authentication Filter offered by Spring Security

Class Name	Description
UsernamePasswordAuthenticationFilter	Fetch credentials from HTTP request parameter in servlet filter class for form authentication.
BasicAuthenticationFilter	Fetch credentials from authentication header of HTTP request in servlet filter class for Basic authentication.
DigestAuthenticationFilter	Fetch credentials from authentication header of HTTP request in servlet filter class for Digest authentication.
RememberMeAuthenticationFilter	Fetch credentials from Cookies of HTTP request in servlet filter class for Remember Me authentication. If Remember Me authentication is enabled, user stays logged in even if browser is closed and a session timeout has occurred.

These servlet filters are one of the Authentication filters introduced in Framework processing.

Note

When an authentication process not supported by Spring Security must be adopted, it must be incorporated in Spring Security after creating a Authentication Filter for adopting this authentication method.

9.2.1.1.2. AuthenticationManager

AuthenticationManager is an interface for implementing the authentication process. In default implementation (ProviderManager) offered by Spring Security, a system is adopted wherein actual authentication process is delegated to AuthenticationProvider and process results of authentication process performed by AuthenticationProvider are handled.

9.2.1.1.3. AuthenticationProvider

AuthenticationProvider is an interface which provides implementation of authentication process. A key AuthenticationProvider implementation class offered by Spring Security is as given below.

A key AuthenticationProvider offered by Spring Security

Class Name	Description
DaoAuthenticationProvider	Implementation class which performs authentication process by checking user credentials and user status registered in the data store. Fetch credentials and user status required for checking, from the class which implements UserDetails interface.

Note

When an authentication process not offered by Spring Security must be adopted, it must be incorporated in Spring Security after creating an AuthenticationProvider for implementing authentication process.

9.2.2. How to use

Bean definition example and implementation method required for using authentication function is explained.

This section, as explained in Overview, explains a method to carry out authentication process by verifying credentials input in HTML input form and user information stored in the relational database.

9.2.2.1. Form authentication

Spring Security performs form authentication as per the flow given below.

Form authentication system

Sr. No.	Description
(1)	Client sends credentials (user name and password) as request parameters for the path which carries out form authentication.
(2)	UsernamePasswordAuthenticationFilter class fetches credentials from request parameter and calls authentication process of AuthenticationManager.
(3)	UsernamePasswordAuthenticationFilter class handles the authentication results returned from AuthenticationManager. Call AuthenticationSuccessHandler method when the authentication is successful, call AuthenticationFailureHandler method when a failure occurs in the authentication and perform screen transition.

9.2.2.1.1. Applying form authentication

Bean is defined as below when form authentication is used.

• Definition example of spring-security.xml

<sec:http>
    <sec:form-login />    <!-- (1) -->
    <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Form authentication is enabled when <sec:form-login> tag is defined.

Tip

About auto-config attribute

An auto-config attribute which specifies whether the settings for form authentication (<sec:form-login> tag), Basic authentication (<sec:http-basic> tag) and logout (<sec:logout> tag) are performed automatically, is provided in <sec:http>. Default value is false (not set automatically) and it is recommended to use default value even in the reference document of Spring Security.

Even in this guideline, a style wherein a tag is specified explicitly is recommended.

Element name	Description
<form-login>	Security Filter(UsernamePasswordAuthenticationFilter) which performs form authentication process is applied.
<http-basic>	Security Filter(BasicAuthenticationFilter) which performs Basic authentication in conformance with RFC1945 is applied. For detailed usage method, refer JavaDoc of BasicAuthenticationFilter.
<logout>	Security Filter(LogoutFilter) which performs logout process is applied. For details of logout process, refer “Logout”.

Further note that when auto-config is not defined, form authentication (<sec:form-login> tag) or Basic authentication (<sec:http-basic> tag) must be defined. This is required to meet the specification of Spring Security wherein a Bean must be defined for one or more Authentication Filters in a single SecurityFilterChain (<sec:http>).

9.2.2.1.2. Default operation

If user account is accessed for "/login" using GET method in the default operation of Spring Security, a default login form provided by Spring Security is displayed and when login button is clicked, "/login" is accessed by POST method and authentication process is carried out.

9.2.2.1.3. Creating login form

Although a login form for form authentication is provided in Spring Security as a default, it is rarely used as it is. Below, a method wherein an auto-created login form is applied in Spring Security is explained.

At first, a JSP for displaying a login form is created. An implementation example wherein a login form is displayed after receiving a request in Spring MVC is given below.

• How to create a JSP for displaying a login form (xxx-web/src/main/webapp/WEB-INF/views/login/loginForm.jsp)

<%@ page contentType="text/html;charset=UTF-8" pageEncoding="UTF-8" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>
<%-- omitted --%>
<div id="wrapper">
    <h3>Login Screen</h3>
    <%-- (1) --%>
    <c:if test="${param.containsKey('error')}">
        <t:messagesPanel messagesType="error"
            messagesAttributeName="SPRING_SECURITY_LAST_EXCEPTION"/> <%-- (2) --%>
    </c:if>
    <form:form action="${pageContext.request.contextPath}/login" method="post"> <%-- (3) --%>
        <table>
            <tr>
                <td><label for="username">User Name</label></td>
                <td><input type="text" id="username" name="username"></td>
            </tr>
            <tr>
                <td><label for="password">Password</label></td>
                <td><input type="password" id="password" name="password"></td>
            </tr>
            <tr>
                <td>&nbsp;</td>
                <td><button>Login</button></td>
            </tr>
        </table>
    </form:form>
</div>
<%-- omitted --%>

Sr. No.	Description
(1)	An area to display authentication error.
(2)	Output an exception message which is output at the time of authentication error. It is recommended to output by using <t:messagesPanel> tag provided by a common library. For how to use <t:messagesPanel> tag, refer “Message Management”. Note that, when an authentication error occurs, exception object is stored in the session or request scope with the attribute name "SPRING_SECURITY_LAST_EXCEPTION".
(3)	Login form to enter user name and password. Send user name and password to request parameters username and password respectively. Also note that token value for CSRF measures is sent to request parameter by using <form:form>. CSRF measures are explained in “CSRF Countermeasures”.

Next, login form thus created is applied to Spring Security.

• Definition example of spring-security.xml

<sec:http>
  <sec:form-login
      login-page="/login/loginForm"
      login-processing-url="/login" /> <!-- (1)(2) -->
  <sec:intercept-url pattern="/login/**" access="permitAll"/>  <!-- (3) -->
  <sec:intercept-url pattern="/**" access="isAuthenticated()"/> <!-- (4) -->
</sec:http>

Sr. No.	Description
(1)	Specify path to display login form in login-page attribute. When an anonymous user accesses a Web resource for which authentication is required, the user is redirected to a path specified in the attribute and a login form is displayed. Here, a request is received by Spring MVC and a login form is displayed. For details, refer “Receive a request by Spring MVC and display login form”.
(2)	Specify path for performing authentication process in login-processing-url attribute. Although default path is also "/login", it should be explicitly specified.
(3)	Assign the rights enabling access to all users for the location under /login path where login form is stored. For how to specify access policy for web resource, refer “Authorization”.
(4)	Assign the access rights for web resource handled by the application. In the example above, only authenticated users are granted the rights to access location under root path of web application. For how to specify access policy for web resource, refer “Authorization”.

Note

Changes in Spring Security 4.0

Default values of following configuration are changed from Spring Security version 4.0

• username-parameter
• password-parameter
• login-processing-url
• authentication-failure-url

9.2.2.2. Response when authentication is successful

Spring Security offers AuthenticationSuccessHandler interface and implementation class as the components to control the response when the authentication is successful.

Implementation class of AuthenticationSuccessHandler

Implementation class	Description
SavedRequestAwareAuthenticationSuccessHandler	Implementation class that redirects to a URL which the user have attempted to access prior to authentication. Implementation class used by default.
SimpleUrlAuthenticationSuccessHandler	Implementation class which redirects or forwards to defaultTargetUrl.

9.2.2.2.1. Default operation

In the default operation of Spring Security, the request that was denied prior to authentication is saved in HTTP session and when the authentication is successful, the request which was denied access is restored and redirected. Page is displayed if the authenticated user has the access rights for redirected page, authentication error occurs if the user does not have the access rights. SavedRequestAwareAuthenticationSuccessHandler class is used to carry out this operation.

Since the transition destination after explicitly displaying login form and performing authentication is the root path of web application ("/"), as per default configuration of Spring Security, user is redirected to the root path of Web application when the authentication is successful.

9.2.2.3. Response when authentication fails

Spring Security offers AuthenticationFailureHandler interface and implementation class as the components to control the response when the authentication fails.

Implementation class of AuthenticationFailureHandler

Implementation class	Description
SimpleUrlAuthenticationFailureHandler	Implementation class which redirects or forwards to a specified path (defaultFailureUrl).
ExceptionMappingAuthenticationFailureHandler	Implementation class which can map authentication exception and URL for transition. Since the exception class generated by Spring Security for each error cause vary, the transition destination can be changed for each error type if this implementation class is used.
DelegatingAuthenticationFailureHandler	Implementation class which can map authentication exception and AuthenticationFailureHandler. Although it resembles ExceptionMappingAuthenticationFailureHandler, a flexible behaviour can be supported by specifying AuthenticationFailureHandler for each authentication exception.

9.2.2.3.1. Default operation

In the default operation of Spring Security, user is redirected to a URL assigned with a query parameter "error"in a path which displays login form.

As an example, when the path to display login form is "/login", the user is redirected to "/login?error".

9.2.2.4. DB authentication

Spring Security performs DB authentication in the flow given below.

DB authentication system

Sr. No.	Description
(1)	Spring Security receives authentication request from the client and calls authentication process of DaoAuthenticationProvider.
(2)	DaoAuthenticationProvider calls user information fetch process of UserDetailsService.
(3)	Implementation class of UserDetailsService fetches user information from data store.
(4)	Implementation class of UserDetailsService generates UserDetails from the user information fetched from data store.
(5)	DaoAuthenticationProvider verifies UserDetails returned from UserDetailsService and authentication information specified by client, and checks validity of user specified by client.

Note

DB authentication offered by Spring Security

Spring Security offers an implementation class to fetch user information from relational database through JDBC.

• org.springframework.security.core.userdetails.User (Implementation class of UserDetails)
• org.springframework.security.core.userdetails.jdbc.JdbcDaoImpl (Implementation class of UserDetailsService)

Since these implementation classes only perform authentication processes of minimum level (password verification, determination of user validity), they are used as it is very rarely. Hence, this guideline explains how to create implementation classes of UserDetails and UserDetailsService.

9.2.2.4.1. Creating UserDetails

UserDetails is an interface which provides credentials (user name and password) and user status necessary in the authentication process and defines following methods. When DaoAuthenticationProvider is used as AuthenticationProvider, implementation class of UserDetails is created in accordance with the requirements of application.

UserDetails interface

public interface UserDetails extends Serializable {
    String getUsername(); // (1)
    String getPassword(); // (2)
    boolean isEnabled(); // (3)
    boolean isAccountNonLocked(); // (4)
    boolean isAccountNonExpired(); // (5)
    boolean isCredentialsNonExpired(); // (6)
    Collection<? extends GrantedAuthority> getAuthorities(); // (7)
}

Sr. No.	Method name	Description
(1)	getUsername	Return user name.
(2)	getPassword	Return registered password. When the password returned by this method and the password specified by the client do not match, DaoAuthenticationProvider throws BadCredentialsException.
(3)	isEnabled	Determine whether the user is valid. Return true in case of valid user. When the user is invalid, DaoAuthenticationProvider throws DisabledException.
(4)	isAccountNonLocked	Determine locked status of the account. When the account is not locked, return true. When the account is locked, DaoAuthenticationProvider throws LockedException.
(5)	isAccountNonExpired	Determine expiry status of the account. Return true when the account is not expired. When the account is expired, DaoAuthenticationProvider throws AccountExpiredException.
(6)	isCredentialsNonExpired	Determine expiry status of credentials. Return true when the credentials are not expired. When the credentials are expired, DaoAuthenticationProvider throws CredentialsExpiredException.
(7)	getAuthorities	Return list of rights assigned to the user. This method is used in the authorization process.

Note

Changing transition destination based on authentication exception

When the user wants to change the screen transition for each exception thrown by DaoAuthenticationProvider, ExceptionMappingAuthenticationFailureHandler must be used as AuthenticationFailureHandler.

As an example, when user wants to transit to password change screen in case of password expiry for the user, screen transition can be changed by handling CredentialsExpiredException by using ExceptionMappingAuthenticationFailureHandler.

For details, refer Customising response at the time of authentication failure.

Note

Credentials provided by Spring Security

Although Spring Security provides an implementation class (org.springframework.security.core.userdetails.User) for retaining credentials (user name and password) and user status, it can store only the information required for the authentication process. Since the information of the user (name of the user etc) which is not used in the authentication process is frequently required in the general applications, User class can rarely be used as it is.

Here, an implementation class of UserDetails which retains account information is created. This example can also be implemented by inheriting User. However, here an example wherein UserDetails is implemented is introduced.

• How to create implementation class of UserDetails

public class AccountUserDetails implements UserDetails { // (1)

    private final Account account;
    private final Collection<GrantedAuthority> authorities;

    public AccountUserDetails(
        Account account, Collection<GrantedAuthority> authorities) {
        // (2)
        this.account = account;
        this.authorities = authorities;
    }

    // (3)
    public String getPassword() {
        return account.getPassword();
    }
    public String getUsername() {
        return account.getUsername();
    }
    public boolean isEnabled() {
        return account.isEnabled();
    }
    public Collection<GrantedAuthority> getAuthorities() {
        return authorities;
    }

    // (4)
    public boolean isAccountNonExpired() {
        return true;
    }
    public boolean isAccountNonLocked() {
        return true;
    }
    public boolean isCredentialsNonExpired() {
        return true;
    }

    // (5)
    public Account getAccount() {
        return account;
    }

}

Sr. No.	Description
(1)	Create a class which implements UserDetails interface.
(2)	Retain user information and rights information in the property.
(3)	Implement method defined in UserDetails interface.
(4)	Although the example of this sections does not implement check for, “Account locking”, “Account expiry” and “Credentials expiry”, these must be checked in accordance with the requirements.
(5)	Provide a getter method to enable access to account information in the process after successful completion of authentication.

Spring Security provides User class as an implementation class of UserDetails. When you inherit a User class, credentials and user status can be easily retained.

• How to create UserDetails implementation class which inherits User class

public class AccountUserDetails extends User {

    private final Account account;

    public AccountUserDetails(Account account, boolean accountNonExpired,
            boolean credentialsNonExpired, boolean accountNonLocked,
            Collection<GrantedAuthority> authorities) {
        super(account.getUsername(), account.getPassword(),
                account.isEnabled(), true, true, true, authorities);
        this.account = account;
    }

    public Account getAccount() {
        return account;
    }
}

9.2.2.4.2. Creating UserDetailsService

UserDetailsService is an interface to fetch credentials and user status required for authentication process from data store and defines following methods. When DaoAuthenticationProvider is used as AuthenticationProvider, implementation class of UserDetailsService is created in accordance with the requirements of the application.

• UserDetailsService interface

public interface UserDetailsService {
    UserDetails loadUserByUsername(String username) throws UsernameNotFoundException;
}

Here, a service class is created to search account information from the database and generate an instance of UserDetails. In this sample, account information is fetched by using SharedService. For SharedService, refer Implementation of Service.

• How to create AccountSharedService interface

public interface AccountSharedService {
    Account findOne(String username);
}

• How to create implementation class of AccountSharedService

// (1)
@Service
@Transactional
public class AccountSharedServiceImpl implements AccountSharedService {
    @Inject
    AccountRepository accountRepository;

    // (2)
    @Override
    public Account findOne(String username) {
        Account account = accountRepository.findOneByUsername(username);
        if (account == null) {
            throw new ResourceNotFoundException("The given account is not found! username="
                    + username);
        }
        return account;
    }
}

Sr. No.	Description
(1)	Create a class which implements AccountSharedService interface and assign @Service. In the example above, AccountSharedServiceImpl is registered in DI container using component scan function.
(2)	Search account information from the database. When account information is not found, an exception of common library - ResourceNotFoundException is thrown. For how to create a repository, refer “Spring Security Tutorial”.

• How to create implementation class of UserDetailsService

// (1)
@Service
@Transactional
public class AccountUserDetailsService implements UserDetailsService {
    @Inject
    AccountSharedService accountSharedService;

    public UserDetails loadUserByUsername(String username)
            throws UsernameNotFoundException {

        try {
            Account account = accountSharedService.findOne(username);
            // (2)
            return new AccountUserDetails(account, getAuthorities(account));
        } catch (ResourceNotFoundException e) {
            // (3)
            throw new UsernameNotFoundException("user not found", e);
        }
    }

    // (4)
    private Collection<GrantedAuthority> getAuthorities(Account account) {
        if (account.isAdmin()) {
            return AuthorityUtils.createAuthorityList("ROLE_USER", "ROLE_ADMIN");
        } else {
            return AuthorityUtils.createAuthorityList("ROLE_USER");
        }
    }
}

Sr. No.	Description
(1)	Create a class which implements UserDetailsService interface and assign @Service. In the example above, UserDetailsService is registered in DI container using a component scan function.
(2)	Fetch account information by using AccountSharedService. When the account information is found, UserDetails is generated. In the example above, user name, password and user validity status are fetched from account information.
(3)	When the account information is not found, UsernameNotFoundException is thrown.
(4)	Generate information about the rights (role) retained by the user. The rights (role) generated here are used in the authorization process.

Note

Information of rights to be used in the authorization

Authorization process of Spring Security handles the rights information starting with "ROLE_"as a role. Hence, when resource access is to be controlled by using role, "ROLE_" must be assigned as a prefix to the rights information which is being handled as a role.

Note

Concealing authentication exception information

In the default operation of Spring Security, error handling is performed after changing UsernameNotFoundException to an exception called BadCredentialsException. BadCredentialsException denotes an error in any field of the credentials specified by the client, specific error causes are not notified to the client.

9.2.2.4.3. Applying DB authentication

When the authentication is to be performed by using UserDetailsService thus created, UserDetailsService thus created must be applied by enabling DaoAuthenticationProvider.

• Definition example of spring-security.xml

<sec:authentication-manager> <!-- (1) -->
    <sec:authentication-provider user-service-ref="accountUserDetailsService"> <!-- (2) -->
        <sec:password-encoder ref="passwordEncoder" /> <!-- (3) -->
    </sec:authentication-provider>
</sec:authentication-manager>

<bean id="passwordEncoder"
    class="org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder" /> <!-- (4) -->

Sr. No.	Description
(1)	Define a Bean for AuthenticationManager.
(2)	Define <sec:authentication-provider> element in the <sec:authentication-manager> element. Specify a Bean of AccountUserDetailsService created by “Creating UserDetailsService”, in user-service-ref attribute. Based on this definition, DaoAuthenticationProvider of default setup is enabled.
(3)	Specify a Bean of PasswordEncoder to be used at the time of password verification.
(4)	Define a Bean for PasswordEncoder to be used at the time of password verification. In the example above, BCryptPasswordEncoder is defined which performs password hashing by using BCrypt algorithm. For password hashing, refer “Password hashing”.

9.2.2.5. Password hashing

When a password is stored in the database, password is not stored as it is and a hash value of the password is generally stored.

Spring Security provides an interface and implementation class for password hashing and operates in coordination with the authentication function.

There are 2 types of interfaces provided by Spring Security.

• org.springframework.security.crypto.password.PasswordEncoder
• org.springframework.security.authentication.encoding.PasswordEncoder

Although both the interfaces include PasswordEncoder, PasswordEncoder of org.springframework.security.authentication.encoding package is deprecated.

When there are no specific constraints in the password hashing requirements, using the implementation class of PasswordEncoder interface of org.springframework.security.crypto.password package is recommended.

Note

For how to use deprecated PasswordEncoder, refer “Using PasswordEncoder of deprecated package”.

Definition of a method for org.springframework.security.crypto.password.PasswordEncoder

public interface PasswordEncoder {
    String encode(CharSequence rawPassword);
    boolean matches(CharSequence rawPassword, String encodedPassword);
}

Method defined in PasswordEncoder

Method name	Description
encode	A method for password hashing. It can be used for hashing of passwords which are stored in the data store during account registration process and password change process.
matches	A method to verify plain text password and hashed password. This method can also be used in the authentication process of Spring Security and can also be used to verify current password and the password used earlier during password change process etc.

Spring Security offers following classes as the implementation class of PasswordEncoder interface.

Implementation class of PasswordEncoder

Implementation class	Description
BCryptPasswordEncoder	Implementation class which performs password hashing and verification by using BCrypt algorithm. When there are no specific constraints in password hashing requirement, using this class is recommended. For details, refer JavaDoc of BCryptPasswordEncoder.
StandardPasswordEncoder	Implementation class which performs password hashing and verification by using SHA-256 algorithm. For details, refer JavaDoc of StandardPasswordEncoder.
NoOpPasswordEncoder	Implementation class which does not perform hashing. It is a class used for testing and is not used in the actual application.

This section explains how to use BCryptPasswordEncoderthat has been recommended by Spring Security.

9.2.2.5.1. BCryptPasswordEncoder

BCryptPasswordEncoder is an implementation class which performs password hashing and password verification by using BCrypt algorithm. 16 byte random numbers (java.security.SecureRandom) are used in Salt, Stretching is done for 1024 (2 to the power of 10) times by default..

• Definition example of applicationContext.xml

<bean id="passwordEncoder"
    class="org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder" > <!-- (1) -->
    <constructor-arg name="strength" value="11" /> <!-- (2) -->
</bean>

Sr. No.	Description
(1)	Specify BCryptPasswordEncoder in passwordEncoder class.
(2)	Specify number of rounds for stretching count of hashing in the argument of constructor. This argument can be omitted and the values that can be specified are in the range from 4 to 31. Note that default value is 10 when the argument value is not specified. The explanation is omitted in the guideline, however java.security.SecureRandom.SecureRandom can also be specified as a constructor argument.

Warning

How to use SecureRandom

When SecureRandom is to be used in Linux environment, a delay or timeout in the processing is likely to occur. This event depends on the random number generator to be used and description is given in the document given below.

• https://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html

When this event occurs, it can be avoided by adding one of the following settings.

• Specify -Djava.security.egd=file:/dev/urandom while executing Java command.
• Change securerandom.source=/dev/random` in ``${JAVA_HOME}/jre/lib/security/java.security to securerandom.source=/dev/urandom.

If this event occurs in the version prior to b19 of Java SE 7 (prior to official release), /dev/./urandom must be specified instead of /dev/urandom. However, algorithm used by SecureRandom cannot be avoided in case of NativePRNG.

PasswordEncoder is used in the class which carries out a process by using BCryptPasswordEncoder, by injecting from DI container.

@Service
@Transactional
public class AccountServiceImpl implements AccountService {

    @Inject
    AccountRepository accountRepository;

    @Inject
    PasswordEncoder passwordEncoder; // (1)

    public Account register(Account account, String rawPassword) {
        // omitted
        String encodedPassword = passwordEncoder.encode(rawPassword); // (2)
        account.setPassword(encodedPassword);
        // omitted
        return accountRepository.save(account);
    }

}

Sr. No.	Description
(1)	Inject PasswordEncoder.
(2)	Call injected PasswordEncoder method. Here, the password stored in the data store is hashed.

Note

Salt

A salt is a string which is added to data targeted for hashing. Since number of digits exceed the actual password length by assigning a salt to a password, password analysis using programs like rainbow crack become difficult. Note that, it is recommended to set different values of salt (random values) for each user. This is necessary because if identical salt value is used, the string (password) before hashing can be easily identified from the hash value.

Note

Stretching

Information related to stored password is repeatedly encrypted by iterating hash function calculation in order to extend the time required for password analysis as a countermeasure against password brute force attack. However, stretching frequency must be determined considering the system performance since stretching is likely to impact system performance.

In Spring Security, stretching is done for 1024 times (2 to the power of 10) by default, however this frequency can be changed by constructor argument (strength). A value from 4 (16 times) to 31 (2, 147, 483, 648 times) can be specified in the strength. More the frequency of stretching, stronger the password. However, it is likely to impact performance due to higher complexity.

9.2.2.6. Handling authentication event

Spring Security offers a system which links process results of authentication process with other components using an event notification system offered by Spring Security.

If this system is used, following security requirements can be incorporated in the authentication function of Spring Security.

• Save authentication history of successful and failed authentication in database or log.
• Lock account if wrong password is entered in succession.

Authentication event is notified as given below.

Event notification system

Sr. No.	Description
(1)	Spring Security authentication function passes authentication results (authentication information and authentication exception) in AuthenticationEventPublisher and requests notification of authentication event.
(2)	Default implementation class of AuthenticationEventPublisher interface generates an instance of authentication event class corresponding to authentication results, passes to ApplicationEventPublisher and requests event notification.
(3)	Implementation class of ApplicationEventPublisher interface notifies the event to implementation class of ApplicationListener interface.
(4)	ApplicationListenerMethodAdaptor, one of the implementation classes of ApplicationListener calls a method assigned by @org.springframework.context.event.EventListener and notifies an event.

Note

Memo

Although it was necessary to receive the event by creating an implementation class of ApplicationListenertill Spring 4.1, an event can be created in Spring 4.2 only by implementing a method which assigns @EventListener to POJO. Note that, even in subsequent versions of Spring 4.2, an event can be received by creating an implementation class of ApplicationListener interface as earlier.

Events used by Spring Security can be classified into 2 types - the events which notify successful authentication and the events which notify failure in authentication. Event class offered by Spring Security are explained below.

9.2.2.6.1. Authentication successful event

There are 3 main events which are notified by Spring Security at the time of successful authentication. These events are notified in the following order unless an error occurs in between.

Event class which notifies that the authentication is successful

Event class	Description
AuthenticationSuccessEvent	An event class to notify that the authentication process by AuthenticationProvider is successful. If this event is handled, it can be detected whether the client has specified correct information. It must be noted that an error is likely to occur in the subsequent processes after handling this event.
SessionFixationProtectionEvent	An event class to notify that session fixation attack countermeasure process (change process of session ID) is successful. If this event is handled, session ID after the change can be detected.
InteractiveAuthenticationSuccessEvent	An event class to notify that authentication process is entirely successful. If this event is handled, it can be detected that the overall authentication process is successful except the screen transition.

9.2.2.6.2. Authentication failure event

Main events which are notified by Spring Security at the time of authentication failure are as below. When authentication fails, any one of the events is notified.

Event class which notifies that authentication has failed

Event class	Description
AuthenticationFailureBadCredentialsEvent	Event class which notifies that BadCredentialsException has occurred.
AuthenticationFailureDisabledEvent	Event class which notifies that DisabledException has occurred.
AuthenticationFailureLockedEvent	Event class which notifies that LockedException has occurred.
AuthenticationFailureExpiredEvent	Event class which notifies that AccountExpiredException has occurred.
AuthenticationFailureCredentialsExpiredEvent	Event class which notifies that CredentialsExpiredException has occurred.
AuthenticationFailureServiceExceptionEvent	Event class which notifies that AuthenticationServiceException has occurred.

9.2.2.6.3. Creating event listener

When you want to carry out a process by receiving authentication event notification, a class implementing a method that assigns @EventListener is created and registered in DI container.

• Implementation example for event listener class

@Component
public class AuthenticationEventListeners {

    private static final Logger log =
            LoggerFactory.getLogger(AuthenticationEventListeners.class);

@EventListener // (1)
public void handleBadCredentials(
    AuthenticationFailureBadCredentialsEvent event) { // (2)
    log.info("Bad credentials is detected. username : {}", event.getAuthentication().getName());
    // omitted
}

Sr. No.	Description
(1)	Create a method which assigns @EventListener to a method.
(2)	Specify an authentication event class which is to be handled in the method argument.

The example above is an example wherein a class is created that handles AuthenticationFailureBadCredentialsEvent that is notified when the client specified authentication information is incorrect. Other events can also be handled in the same manner.

9.2.2.7. Logout

Spring Security performs logout process as per the flow given below.

Logout process system

Sr. No.	Description
(1)	Client sends a request to a path intended for logout process.
(2)	LogoutFilter calls LogoutHandler method and performs actual logout process.
(3)	LogoutFilter calls LogoutSuccessHandler method and performs screen transition.

A plurality of implementation classes of LogoutHandler play respective roles as below.

Implementation class of main LogoutHandler

Implementation class	Description
SecurityContextLogoutHandler	Class which clears authentication information of login user and cancels a session.
CookieClearingLogoutHandler	Class which sends a response for deleting specific cookies.
CsrfLogoutHandler	Class which deletes a token for CSRF countermeasure.

Since LogoutHandlerautomatically sets the class which supports bean definition offered by Spring Security, in LogoutFilter, there is no need for a developer to be specifically aware of the same. Note that, if Remember Me authentication function is enabled, implementation class of LogoutHandler is also configured to delete the token for Remember Me authentication.

9.2.2.7.1. Applying logout process

Define a bean as below for application of logout process.

• Definition example of spring-security.xml

<sec:http>
    <!-- omitted -->
    <sec:logout /> <!-- (1) -->
    <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Logout process is enabled by defining <sec:logout> tag.

Note

Changes in Spring Security 4.0

Default values of following configuration changes from Spring Security 4.0 version.

• logout-url

Tip

Delete Cookie

Although description is omitted in the guideline, note that delete-cookies attribute exists in <sec:logout> tag for deleting Cookie specified at the time of logout. However, it has been reported that a cookie is sometimes not deleted even after using this attribute.

For details, refer following JIRA of Spring Security.

• https://jira.spring.io/browse/SEC-2091

9.2.2.7.2. Default operation

In the default operation of Spring Security, if a request is sent to the path "/logout", logout process is carried out. Logout process consists of “clearing authentication information of logged in user” and “cancelling a session”.

Further,

• “Deleting token for CSRF measures” when CSRF measures are adopted
• “Deleting token for Remember Me authentication” when Remember Me authentication function is used

are also carried out.

• Implementation example of JSP for calling logout process

<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>
<%-- omitted --%>
<form:form action="${pageContext.request.contextPath}/logout" method="post"> <%-- (1) --%>
    <button>Logout</button>
</form:form>

Sr. No.	Description
(1)	Create a form for logout. Further, token value of CSRF measure is sent in request parameter by using <form:form>. CSRF measures are explained in “CSRF Countermeasures”.

Note

Sending CSRF tokens

If CSRF measures are enabled, tokens for CSRF measures must be sent by using POST method.

9.2.2.8. Response when logout is successful

Spring Security offers an interface LogoutSuccessHandlerand implementation class as the components to control response when the logout is successfully completed.

Implementation class of AuthenticationFailureHandler

Implementation class	Description
SimpleUrlLogoutSuccessHandler	Implementation class which redirects in the specified path (defaultTargetUrl).

9.2.2.8.1. Default operation

In default operation of Spring Security, user is redirected to a URL wherein a query parameter called "logout"is assigned to the path for displaying login form.

As an example, when the path to display login form is "/login", the user is redirected to "/login?logout".

9.2.2.9. Accessing authentication information

Authentication information of the authenticated user is stored in the session during default implementation of Spring Security. Authentication information stored in the session is stored in SecurityContextHolder class by SecurityContextPersistenceFilter class for each request and can be accessed from anywhere if it is in the same thread.

A method wherein UserDetails are fetched from authentication information and the information retained in the fetched UserDetails is accessed.

9.2.2.9.1. Access from Java

An audit log which records information like “When”, “Who”, “Which data” and “Type of access” is fetched in the general business application. “Who” for fulfilling these requirements can be fetched from authentication information.

• Implementation example to access authentication information from Java

Authentication authentication =
        SecurityContextHolder.getContext().getAuthentication(); // (1)
String userUuid = null;
if (authentication.getPrincipal() instanceof AccountUserDetails) {
    AccountUserDetails userDetails =
            AccountUserDetails.class.cast(authentication.getPrincipal()); // (2)
    userUuid = userDetails.getAccount().getUserUuid(); // (3)
}
if (log.isInfoEnabled()) {
    log.info("type:Audit\tuserUuid:{}\tresource:{}\tmethod:{}",
            userUuid, httpRequest.getRequestURI(), httpRequest.getMethod());
}

Sr. No.	Description
(1)	Fetch authentication information (Authentication object) from SecurityContextHolder.
(2)	Call Authentication#getPrincipal() method and fetch UserDetails object. When there is no authentication (anonymous user), note that a string indicating an anonymous user is returned.
(3)	Fetch information required for processing from UserDetails. Here, a value which uniquely identifies the user (UUID) is fetched.

Warning

Access and coupling of authentication information

In the default operation of Spring Security, since authentication information is stored in ThreadLocal variable, it can be accessed from anywhere if the thread is identical to a thread which receives request. Although this system is convenient, it results in direct dependency of the class which requires authentication information on SecurityContextHolder class. Hence, care must be taken since it reduces coupling between components when not used correctly.

Spring Security also offers a system to maintain coupling between components by coordinating with Spring MVC function. How to coordinate with Spring MVC is explained in “Coordination between authentication process and Spring MVC”. This guideline recommends fetching authentication information by using coordination with Spring MVC.

Note

When a filter (FORM_LOGIN_FILTER) for authentication is to be customized, it is necessary to disable the following 2 SessionAuthenticationStrategy classes, apart from specifying <sec:concurrency-control> element.

• org.springframework.security.web.authentication.session.ConcurrentSessionControlAuthenticationStrategy

  A class to check number of sessions for each logged in user after successful authentication.
• org.springframework.security.web.authentication.session.RegisterSessionAuthenticationStrategy

  A class to register a session with successful authentication, in session management area.

In version 1.0.x.RELEASE dependent Spring Security 3.1, org.springframework.security.web.authentication.session.ConcurrentSessionControlStrategy class is provided; however, it is deprecated API from Spring Security 3.2 and it is abolished API from Spring Security 4.0. When upgrading version from Spring Security 3.1 to Spring Security 3.2 or later versions, changes need to be made so that it can be used with combination of following classes.

• ConcurrentSessionControlAuthenticationStrategy (added in Spring Security 3.2)
• RegisterSessionAuthenticationStrategy (added in Spring Security 3.2)
• org.springframework.security.web.authentication.session.SessionFixationProtectionStrategy

For specific methods of definition, refer to sample code of Spring Security Reference -Web Application Security (Concurrency Control)-.

9.2.2.9.2. Access from JSP

User information of login user is displayed on the screen in general Web application. User information of login user while meeting these requirements can be fetched from authentication information.

• Implementation example for accessing authentication information from JSP

<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>
<%-- omitted --%>
Welcome、
<sec:authentication property="principal.account.lastName"/> <%-- (1) --%>
San

Sr. No.	Description
(1)	Use <sec:authentication> tag offered by Spring Security and fetch authentication information (Authentication object). Specify path for the property to be accessed in property attribute. When a nested object is to be accessed, property name should be joined by ".".

Tip

How to display authentication information

Although the implementation example for displaying user information which contains authentication information is explained, it is possible to store value in any scope variable by combining var attribute and scope attribute. When the display contents are to be changed according to the login user status, user information can be stored in the variable and display can be changed by using JSTL tag library etc.

In the example above, it can also be displayed as described below. Since scope attribute is omitted in this example, page scope is applied.

<%@ taglib prefix="sec" uri="http://www.springframework.org/security/tags" %>
<%-- omitted --%>
<sec:authentication var="principal" property="principal"/>
<%-- omitted --%>
Welcome
${f:h(principal.account.lastName)}
San

9.2.2.10. Coordination between authentication process and Spring MVC

Spring Security offers various components for coordinating with Spring MVC. How to use the components for coordinating with authentication process is explained.

9.2.2.10.1. Accessing authentication information

Spring Security offers AuthenticationPrincipalArgumentResolver class as a component which delivers authentication information (UserDetails) to Spring MVC controller method. If AuthenticationPrincipalArgumentResolver is used, UserDetails interface or instance of its implementation class can be received as a method argument of controller resulting in enhanced coupling of components.

AuthenticationPrincipalArgumentResolver must be applied to Spring MVC first for receiving Authentication information (UserDetails) as a controller argument. Bean for applying AuthenticationPrincipalArgumentResolver is as below. Note that AuthenticationPrincipalArgumentResolver is already cong=figured in the blank project.

• Definition example of spring-mvc.xml

  <mvc:annotation-driven>
      <mvc:argument-resolvers>
          <!-- omitted -->
          <!-- (1) -->
          <bean class="org.springframework.security.web.method.annotation.AuthenticationPrincipalArgumentResolver" />
          <!-- omitted -->
      </mvc:argument-resolvers>
</mvc:annotation-driven>

Sr. No.	Description
(1)	Apply AuthenticationPrincipalArgumentResolver in Spring MVC as an implementation class of HandlerMethodArgumentResolver.

Following method is created while receiving authentication information (UserDetails) by controller method.

• How to create a method which receives authentication information (UserDetails)

@RequestMapping("account")
@Controller
public class AccountController {

    public String view(
            @AuthenticationPrincipal AccountUserDetails userDetails, // (1)
            Model model) {
        model.addAttribute(userDetails.getAccount());
        return "profile";
    }

}

Sr. No.	Description
(1)	Declare an argument to receive authentication information (UserDetails) and specify @org.springframework.security.core.annotation.AuthenticationPrincipal as an argument annotation. AuthenticationPrincipalArgumentResolver configures authentication information (UserDetails) in the argument assigned by @AuthenticationPrincipal.

9.2.3. How to extend

The section describes customization points and extension methods offered by Spring Security.

Spring Security offers a lot of customization points. Since it is not possible to introduce all the customization points here, we will focus on a few typical customization points here.

9.2.3.1. Customizing form authentication

Customization points of form authentication process are explained.

9.2.3.1.1. Changing authentication path

In Spring Security, the path for carrying out authentication process is “"/login"” by default, however it can be changed by defining a bean as below.

• Definition example of spring-security.xml

<sec:http>
  <sec:form-login login-processing-url="/authentication" /> <!-- (1) -->
  <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Specify a path for carrying out authentication process in login-processing-url attribute.

Note

When path of authentication process is changed, request destination of Login form must be changed as well.

9.2.3.1.2. Change request parameter name which sends credentials

In Spring Security, request parameters for sending credentials (user name and password) are “username” and “password” by default, however, these can be changed by defining a bean as shown below.

• Definition example for spring-security.xml

<sec:http>
    <sec:form-login
        username-parameter="uid"
        password-parameter="pwd" /> <!-- (1) (2) -->
    <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Specify a request parameter name for user name in username-parameter attribute.
(2)	Specify a request parameter name for password in password-parameter attribute.

Note

When request parameter name is changed, field name in Login form must also be changed.

9.2.3.2. Customising response when authentication is successful

Customization points of response when authentication is successful are explained.

9.2.3.2.1. Changing default transition destination

Transition destination (default URL) after displaying login form on its own and by carrying out authentication process is the root path of Web application ("/"), however it can be changed by defining a bean as given below.

• Definition example of spring-security.xml

<sec:http>
    <sec:form-login default-target-url="/menu" /> <!-- (1) -->
</sec:http>

Sr. No.	Description
(1)	Specify default path for transition in default-target-url attribute when the authentication is successful.

9.2.3.2.2. Fixing transition destination

In default operation of Spring Security, when a request for a page for which authentication is required is received during unauthenticated stage, the request thus received is temporarily stored in HTTP session and then transition is done to authentication page. Although request is restored and redirected when the authentication is successful, transition to the same screen can be assured by defining a bean as below.

• Definition example of spring-security.xml

<sec:http>
    <sec:form-login
        default-target-url="/menu"
        always-use-default-target="true" /> <!-- (1) -->
</sec:http>

Sr. No.	Description
(1)	Specify truein always-use-default-target attribute.

9.2.3.2.3. Applying AuthenticationSuccessHandler

When the requirements are not met only by using the system wherein default operations provided by Spring Security are customised, implementation class of AuthenticationSuccessHandler interface can be applied directly by defining a bean as given below.

• Definition example of spring-security.xml

<bean id="authenticationSuccessHandler" class="com.example.app.security.handler.MyAuthenticationSuccessHandler"> <!-- (1) -->

<sec:http>
    <sec:form-login authentication-success-handler-ref="authenticationSuccessHandler" /> <!-- (2) -->
</sec:http>

Sr. No.	Description
(1)	Define a bean for implementation class of AuthenticationSuccessHandler interface.
(2)	Specify authenticationSuccessHandler defined in authentication-success-handler-ref attribute.

Warning

Responsibility of AuthenticationSuccessHandler

AuthenticationSuccessHandler is an interface which performs processes for Web layer at the time of successful authentication (mainly processes related to screen transition). Therefore, a process dependent on business rule (business logic) like clearing number of authentication failures should not be called through implementation class of this interface.

“Handling authentication event” system introduced in earlier section should be used for calling the processes that are dependent on business rules.

9.2.3.3. Customising response at the time of authentication failure

Customization points for the response at the time of authentication failure are explained.

9.2.3.3.1. Changing transition destination

In default operation of Spring Security, the user is redirected to a URL wherein a query parameter "error"is assigned to path for displaying login form, however it can be changed by defining a bean as given below.

• Definition example of spring-security.xml

<sec:http>
    <sec:form-login authentication-failure-url="/loginFailure" /> <!-- (1) -->
</sec:http>

Sr.No.	Description
(1)	Specify a path for transition in authentication-failure-url attribute at the time of authentication failure.

9.2.3.3.2. Applying AuthenticationFailureHandler

When the requirements are not met only by using the system wherein default operations provided by Spring Security are customised, implementation class of AuthenticationFailureHandler interface can be applied directly by defining a bean as below.

• Definition example of spring-security.xml

 <!-- (1) -->
<bean id="authenticationFailureHandler"
    class="org.springframework.security.web.authentication.ExceptionMappingAuthenticationFailureHandler" />
    <property name="defaultFailureUrl" value="/login/systemError" /> <!-- (2) -->
    <property name="exceptionMappings"> <!-- (3) -->
        <props>
            <prop key="org.springframework.security.authentication.BadCredentialsException"> <!-- (4) -->
                /login/badCredentials
            </prop>
            <prop key="org.springframework.security.core.userdetails.UsernameNotFoundException"> <!-- (5) -->
                /login/usernameNotFound
            </prop>
            <prop key="org.springframework.security.authentication.DisabledException"> <!-- (6) -->
                /login/disabled
            </prop>
            <!-- omitted -->
        </props>
    </property>
</bean>

<sec:http>
    <sec:form-login authentication-failure-handler-ref="authenticationFailureHandler" /> <!-- (7) -->
</sec:http>

Sr. No.	Description
(1)	Define a bean for implementation class of AuthenticationFailureHandler interface.
(2)	Specify default transition destination URL in defaultFailureUrl attribute. When the exceptions that do not match the definitions given in (4)~(6) below occur, move to transition destination of the configuration.
(3)	Set implementation class of org.springframework.security.authentication.AuthenticationServiceException handled in the exceptionMappings property and transition destination at the time exception occurrence in Map format. Set implementation class of org.springframework.security.authentication.AuthenticationServiceException in key and set transition destination URL in value.
(4)	BadCredentialsException It is thrown at the time of authentication error due to password verification failure.
(5)	UsernameNotFoundException It is thrown at the time of authentication error due to invalid user ID (non-existent user ID). When org.springframework.security.authentication.dao.AbstractUserDetailsAuthenticationProvider specifies inherited class in the authentication provider, the exception changes to BadCredentialsException if hideUserNotFoundExceptions property is not changed to false.
(6)	DisabledException It is thrown at the time of authentication error due to invalid user ID.
(7)	Set authenticationFailureHandler in authentication-failure-handler-ref attribute.

Note

Control during occurrence of exception

When an exception defined in exceptionMappings property occur, the user is redirected to transition destination mapped in the exception, however, since exception object thus occurred is not stored in the session scope, error message generated by Spring Security cannot be displayed on the screen.

Therefore, error message displayed in the transition destination screen must be generated by the process for redirect (Controller or View process).

Further, it must be added that since the processes referring properties below are not called, operation does not undergo any change even after changing the setup value.

• useForward
• allowSessionCreation

9.2.3.4. Customising logout process

Customization points for logout process are explained.

9.2.3.4.1. Changing logout path

In Spring Security, default path which carries out logout process is “"/logout"”, however it can be changed by defining a bean as given below.

• Definition example of spring-security.xml

<sec:http>
    <!-- omitted -->
    <sec:logout logout-url="/auth/logout" /> <!-- (1) -->
    <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Set logout-url attribute and specify path to carry out logout process.

Note

When logout path is changed, request destination of logout form must be changed as well.

Tip

Behaviour during occurrence of system error When system error occurs, discontinuation of operations is likely. If the operation is not to be continued after occurrence of system error, adopting following measures is recommended.

• Clear session information when the system error occurs.
• Clear authentication information when the system error occurs

An example wherein authentication information at the time of system exception occurrence is cleared using an exception handling function of common library is explained. For details of exception handling function, refer “Exception Handling”.

// (1)
public class LogoutSystemExceptionResolver extends SystemExceptionResolver {
    // (2)
    @Override
    protected ModelAndView doResolveException(HttpServletRequest request,
            HttpServletResponse response, java.lang.Object handler,
            java.lang.Exception ex) {

        // Carry out SystemExceptionResolver
        ModelAndView resulut = super.doResolveException(request, response,
                handler, ex);

        // Clear authentication information (2)
        SecurityContextHolder.clearContext();

        return resulut;
    }
}

Sr. No.	Description
(1)	Extend org.terasoluna.gfw.web.exception.SystemExceptionResolver.SystemExceptionResolver.
(2)	Clear authentication information.

Further, the same requirement can also be met by clearing the session, besides using the method that clears authentication information. Implement according to the project requirement.

9.2.3.5. Customising response when logout is successful

Customization points for the response when logout process is successful is explained.

9.2.3.5.1. Changing transition destination

• Definition example of spring-security.xml

<sec:http>
  <!-- omitted -->
  <sec:logout logout-success-url="/logoutSuccess" /> <!-- (1) -->
  <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Set logout-success-url attribute and specify path for the transition when the logout is successful.

9.2.3.5.2. Applying LogoutSuccessHandler

• Definition example of spring-security.xml

<!-- (1) -->
<bean id="logoutSuccessHandler" class="com.example.app.security.handler.MyLogoutSuccessHandler" />

<sec:http>
    <!-- omitted -->
    <sec:logout success-handler-ref="logoutSuccessHandler" /> <!-- (2) -->
    <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Define a bean for implementation class of LogoutSuccessHandler interface.
(2)	Set LogoutSuccessHandlerin success-handler-ref attribute.

9.2.3.6. Customising error message

When authentication fails, error message provided by Spring Security is displayed, however, the error message can be changed.

For details of how to change the message, refer Message Management.

9.2.3.6.1. Message during system error

When an unexpected error occurs (system error etc) during authentication process, InternalAuthenticationServiceException exception is thrown. Since cause exception message is set in the message retained by InternalAuthenticationServiceException, it should not be displayed as it is on the screen.

For example, when a DB access error occurs while fetching user information from database, an exception message retained by SQLException is displayed on the screen. The measures like handling InternalAuthenticationServiceException by using ExceptionMappingAuthenticationFailureHandler and transiting to the path for notifying occurrence of system error are necessary for not displaying exception message of system error on the screen.

• Definition example of spring-security.xml

  <bean id="authenticationFailureHandler"
      class="org.springframework.security.web.authentication.ExceptionMappingAuthenticationFailureHandler">
      <property name="defaultFailureUrl" value="/login?error" />
      <property name="exceptionMappings">
          <props>
              <prop key="org.springframework.security.authentication.InternalAuthenticationServiceException">
                  /login?systemError
              </prop>
              <!-- omitted -->
          </props>
      </property>
  </bean>

<sec:http>
    <sec:form-login authentication-failure-handler-ref="authenticationFailureHandler" />
</sec:http>

Query parameter (systemError) is used for identifying occurrence of system error and transition is made to login form. When systemError is specified in the query parameter, in the login form specified in the transition destination, a fixed error message is displayed instead of an authentication exception message.

• Implementation example of login form

<c:choose>
    <c:when test="${param.containsKey('error')}">
        <span style="color: red;">
            <c:out value="${SPRING_SECURITY_LAST_EXCEPTION.message}"/>
        </span>
    </c:when>
    <c:when test="${param.containsKey('systemError')}">
        <span style="color: red;">
            System Error occurred.
        </span>
    </c:when>
</c:choose>

Note

An implementation example for transiting to login form is introduced, however it is also possible to move to system error screen.

9.2.3.7. Input check at the time of authentication

A check is carried out in advance for obvious input error on the authentication page during reduction of load on DB server etc. In such a case, input check using Bean validation can also be carried out.

9.2.3.7.1. Input check using Bean Validation

An example of input check using Bean Validation is explained below. For details of Bean Validation, refer Input Validation.

• Implementation example of form class

public class LoginForm implements Serializable {

    // omitted
    @NotEmpty // (1)
    private String username;

    @NotEmpty // (1)
    private String password;
    // omitted

}

Sr. No.	Description
(1)	In this example, usernameand password are mandatory respectively.

• Implementation example of controller class

@ModelAttribute
public LoginForm setupForm() { // (1)
    return new LoginForm();
}

@RequestMapping(value = "login")
public String login(@Validated LoginForm form, BindingResult result) {
    // omitted
    if (result.hasErrors()) {
        // omitted
    }
    return "forward:/authenticate"; // (2)
}

Sr. No.	Description
(1)	Initialise LoginForm.
(2)	Forward to path specified in login-processing-url attribute of <sec:form-login>element using “forward”. For setup related to authentication, refer Customizing form authentication.

In addition, authentication path is added to Spring Security servlet filter for Spring Security processing even during the transition using Forward.

• Setup example of web.xml

<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>
<!-- (1) -->
<filter-mapping>
    <filter-name>springSecurityFilterChain</filter-name>
    <url-pattern>/authenticate</url-pattern>
    <dispatcher>FORWARD</dispatcher>
</filter-mapping>

Sr. No.	Description
(1)	Specify pattern for authentication by using Forward. Here "/authenticate" is specified as an authentication path.

9.2.3.8. Expansion of authentication process

In case of authentication requirements which cannot be handled by authentication provider offered by Spring Security, a class which implements org.springframework.security.authentication.AuthenticationProvider interface must be created.

Here, an expansion example for performing DB authentication by using 3 parameters - user name, password and Company identifier (unique authentication parameter)is shown below.

A class shown below must be created for implementing above requirements.

Sr. No.	Description
(1)	An implementation class of org.springframework.security.core.Authentication interface which retains user name, password and company identifier. It is created by inheriting org.springframework.security.authentication.UsernamePasswordAuthenticationToken class.
(2)	An implementation class of org.springframework.security.authentication.AuthenticationProvider which performs DB authentication by using user name, password and company identifier. It is created by inheriting org.springframework.security.authentication.dao.DaoAuthenticationProvider class.
(3)	An Authentication Filter class for generating Authentication which is passed to AuthenticationManager(AuthenticationProvider) by fetching user name, password and company identifier from request parameters. It is created by inheriting org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter class.

Note

Since a unique parameter is added as an parameter for authentication in this example, implementation class of Authenticationinterface and Authentication Filter class for generating Authentication must be expanded.

When the authentication is to be performed only by user name and password, authentication process can be expanded only by creating implementation class of AuthenticationProvider interface

9.2.3.8.1. Creating an implementation class of Authentication interface

UsernamePasswordAuthenticationToken class is inherited and a class that retains a company identifier (unique authentication parameter) besides user name and password is created.

// import omitted
public class CompanyIdUsernamePasswordAuthenticationToken extends
    UsernamePasswordAuthenticationToken {

    private static final long serialVersionUID = SpringSecurityCoreVersion.SERIAL_VERSION_UID;

    // (1)
    private final String companyId;

    // (2)
    public CompanyIdUsernamePasswordAuthenticationToken(
            Object principal, Object credentials, String companyId) {
        super(principal, credentials);
        this.companyId = companyId;
    }

    // (3)
    public CompanyIdUsernamePasswordAuthenticationToken(
            Object principal, Object credentials, String companyId,
            Collection<? extends GrantedAuthority> authorities) {
        super(principal, credentials, authorities);
        this.companyId = companyId;
    }

    public String getCompanyId() {
        return companyId;
    }

}

Sr. No.	Description
(1)	Create a field that retains a company identifier.
(2)	Create a constructor to be used while creating an instance which retains information prior to authentication (information specified by request parameter).
(3)	Create a constructor to be used while creating an instance which retains authenticated information. Authenticated state is reached by passing authorization information to the argument of parent class constructor.

9.2.3.8.2. Creating an implementation class of AuthenticationProvider interface

DaoAuthenticationProvider class is inherited and a class which performs DB authentication by using user name, password and company identifier is created.

// import omitted
public class CompanyIdUsernamePasswordAuthenticationProvider extends
    DaoAuthenticationProvider {

    // omitted

    @Override
    protected void additionalAuthenticationChecks(UserDetails userDetails,
            UsernamePasswordAuthenticationToken authentication)
            throws AuthenticationException {

        // (1)
        super.additionalAuthenticationChecks(userDetails, authentication);

        // (2)
        CompanyIdUsernamePasswordAuthenticationToken companyIdUsernamePasswordAuthentication =
                (CompanyIdUsernamePasswordAuthenticationToken) authentication;
        String requestedCompanyId = companyIdUsernamePasswordAuthentication.getCompanyId();
        String companyId = ((SampleUserDetails) userDetails).getAccount().getCompanyId();
        if (!companyId.equals(requestedCompanyId)) {
            throw new BadCredentialsException(messages.getMessage(
                    "AbstractUserDetailsAuthenticationProvider.badCredentials",
                    "Bad credentials"));
        }
    }

    @Override
    protected Authentication createSuccessAuthentication(Object principal,
            Authentication authentication, UserDetails user) {
        String companyId = ((SampleUserDetails) user).getAccount()
                .getCompanyId();
        // (3)
        return new CompanyIdUsernamePasswordAuthenticationToken(user,
                authentication.getCredentials(), companyId,
                user.getAuthorities());
    }

    @Override
    public boolean supports(Class<?> authentication) {
        // (4)
        return CompanyIdUsernamePasswordAuthenticationToken.class
                .isAssignableFrom(authentication);
    }

}

Sr. No.	Description
(1)	Call parent class method and implement check process provided by Spring Security. This process also includes password authentication process.
(2)	When password authentication is successful, check validity of company identifier (unique authentication parameter). In the example above, it is checked whether the requested company identifier and the company identifier retained in the table are identical.
(3)	When password authentication and unique authentication process are successful, CompanyIdUsernamePasswordAuthenticationTokenis created in an authenticated state and then returned.
(4)	When castable Authentication is specified in CompanyIdUsernamePasswordAuthenticationToken, perform authentication process by using this class.

Note

User existence check, user status check (checks for invalid user, locked user, expired user etc) are carried out as processes of parent class before calling additionalAuthenticationChecks method.

9.2.3.8.3. Creating Authentication Filter

UsernamePasswordAuthenticationFilter class is inherited and an Authentication Filter class is created for passing authentication information (user name, password and company identifier) to AuthenticationProvider.

attemptAuthentication method implementation is customised by copying method of UsernamePasswordAuthenticationFilter class.

// import omitted
public class CompanyIdUsernamePasswordAuthenticationFilter extends
    UsernamePasswordAuthenticationFilter {

    @Override
    public Authentication attemptAuthentication(HttpServletRequest request,
            HttpServletResponse response) throws AuthenticationException {

        if (!request.getMethod().equals("POST")) {
            throw new AuthenticationServiceException("Authentication method not supported: "
                    + request.getMethod());
        }

        // (1)
        // Obtain UserName, Password, CompanyId
        String username = super.obtainUsername(request);
        String password = super.obtainPassword(request);
        String companyId = obtainCompanyId(request);
        if (username == null) {
            username = "";
        } else {
            username = username.trim();
        }
        if (password == null) {
            password = "";
        }
        CompanyIdUsernamePasswordAuthenticationToken authRequest =
            new CompanyIdUsernamePasswordAuthenticationToken(username, password, companyId);

        // Allow subclasses to set the "details" property
        setDetails(request, authRequest);

        return this.getAuthenticationManager().authenticate(authRequest); // (2)
    }

    // (3)
    protected String obtainCompanyId(HttpServletRequest request) {
        return request.getParameter("companyId");
    }
}

Sr. No.	Description
(1)	Generate an instance of CompanyIdUsernamePasswordAuthenticationToken from the authentication information fetched from request parameter (user name, password, company identifier).
(2)	Specify authentication information specified by request parameter (CompanyIdUsernamePasswordAuthenticationToken instance) and call authenticate method of org.springframework.security.authentication.AuthenticationManager. If AuthenticationManager method is called, AuthenticationProvider authentication process gets called.
(3)	Company identifier is fetched by using request parameter "companyId".

9.2.3.8.4. Modifying login form

Company identifier is added for login form (JSP) created by Creating login form.

<form:form action="${pageContext.request.contextPath}/login" method="post">
    <!-- omitted -->
        <tr>
            <td><label for="username">User Name</label></td>
            <td><input type="text" id="username" name="username"></td>
        </tr>
        <tr>
            <td><label for="companyId">Company Id</label></td>
            <td><input type="text" id="companyId" name="companyId"></td> <!-- (1) -->
        </tr>
        <tr>
            <td><label for="password">Password</label></td>
            <td><input type="password" id="password" name="password"></td>
        </tr>
    <!-- omitted -->
</form:form>

Sr. No.	Description
(1)	Specify "companyId" in input field name of company identifier.

9.2.3.8.5. Applying expanded authentication process

DB authentication process which use user name, password and company identifier (unique authentication parameter) are applied in Spring Security.

• Definition example of spring-security.xml

<!-- omitted -->

<!-- (1) -->
<sec:http
    entry-point-ref="loginUrlAuthenticationEntryPoint">

    <!-- omitted -->

    <!-- (2) -->
    <sec:custom-filter
        position="FORM_LOGIN_FILTER" ref="companyIdUsernamePasswordAuthenticationFilter" />

    <!-- omitted -->

    <sec:csrf token-repository-ref="csrfTokenRepository" />

    <sec:logout
        logout-url="/logout"
        logout-success-url="/login" />

    <!-- omitted -->

    <sec:intercept-url pattern="/login" access="permitAll" />
    <sec:intercept-url pattern="/**" access="isAuthenticated()" />

    <!-- omitted -->

</sec:http>

<!-- (3) -->
<bean id="loginUrlAuthenticationEntryPoint"
    class="org.springframework.security.web.authentication.LoginUrlAuthenticationEntryPoint">
    <constructor-arg value="/login" />
</bean>

<!-- (4) -->
<bean id="companyIdUsernamePasswordAuthenticationFilter"
    class="com.example.app.common.security.CompanyIdUsernamePasswordAuthenticationFilter">
    <!-- (5) -->
    <property name="requiresAuthenticationRequestMatcher">
        <bean class="org.springframework.security.web.util.matcher.AntPathRequestMatcher">
            <constructor-arg index="0" value="/authentication" />
            <constructor-arg index="1" value="POST" />
        </bean>
    </property>
    <!-- (6) -->
    <property name="authenticationManager" ref="authenticationManager" />
    <!-- (7) -->
    <property name="sessionAuthenticationStrategy" ref="sessionAuthenticationStrategy" />
    <!-- (8) -->
    <property name="authenticationFailureHandler">
        <bean class="org.springframework.security.web.authentication.SimpleUrlAuthenticationFailureHandler">
            <constructor-arg value="/login?error=true" />
        </bean>
    </property>
    <!-- (9) -->
    <property name="authenticationSuccessHandler">
        <bean class="org.springframework.security.web.authentication.SimpleUrlAuthenticationSuccessHandler" />
    </property>
</bean>

<!-- (6') -->
<sec:authentication-manager alias="authenticationManager">
    <sec:authentication-provider ref="companyIdUsernamePasswordAuthenticationProvider" />
</sec:authentication-manager>
<bean id="companyIdUsernamePasswordAuthenticationProvider"
    class="com.example.app.common.security.CompanyIdUsernamePasswordAuthenticationProvider">
    <property name="userDetailsService" ref="sampleUserDetailsService" />
    <property name="passwordEncoder" ref="passwordEncoder" />
</bean>

<!-- (7') -->
<bean id="sessionAuthenticationStrategy"
    class="org.springframework.security.web.authentication.session.CompositeSessionAuthenticationStrategy">
    <constructor-arg>
        <util:list>
            <bean class="org.springframework.security.web.csrf.CsrfAuthenticationStrategy">
                <constructor-arg ref="csrfTokenRepository" />
            </bean>
            <bean class="org.springframework.security.web.authentication.session.SessionFixationProtectionStrategy" />
        </util:list>
    </constructor-arg>
</bean>

<bean id="csrfTokenRepository"
    class="org.springframework.security.web.csrf.HttpSessionCsrfTokenRepository" />


<!-- omitted -->

Sr. No.	Description
(1)	When "FORM_LOGIN_FILTER" is to be changed by using <sec:custom-filter> tag of (2), following settings must be applied to <sec:http> tag attribute. Since auto-configuration cannot be used, auto-config="false" is specified or auto-config attribute is deleted. Since <sec:form-login> tag cannot be used, AuthenticationEntryPoint is specified explicitly by using entry-point-ref attribute.
(2)	Use <sec:custom-filter> tag and change "FORM_LOGIN_FILTER". Specify "FORM_LOGIN_FILTER" in position attribute of <sec:custom-filter> tag and specify a bean for Authentication Filter expanded in ref attribute.
(3)	Specify a bean of AuthenticationEntryPointused in entry-point-ref attribute of <sec:http> tag. Here, a bean of org.springframework.security.web.authentication.LoginUrlAuthenticationEntryPoint class used while specifying <sec:form-login> tag is specified.
(4)	Define a bean of Authentication Filter class used as "FORM_LOGIN_FILTER". Here, a bean of expanded Authentication Filter class (CompanyIdUsernamePasswordAuthenticationFilter) is defined.
(5)	Specify RequestMatcher instance for detecting a request performing authentication process, in requiresAuthenticationRequestMatcher property. It is configured to perform authentication process when a request is raised in the "/authentication" path. This is similar to specifying "/authentication" in login-processing-url attribute of <sec:form-login> tag.
(6)	Specify a value set in alias attribute of <sec:authentication-manager> tag, in authenticationManager property. If alias attribute of <sec:authentication-manager> tag is specified, a bean of AuthenticationManager generated by Spring Security can be used for DI of another bean.
(6’)	Set expanded AuthenticationProvider(CompanyIdUsernamePasswordAuthenticationProvider) for AuthenticationManager generated by Spring Security.
(7)	Specify a bean of component (SessionAuthenticationStrategy) that controls handling of a session during successful authentication in sessionAuthenticationStrategy property.
(7’)	Define a bean of component (SessionAuthenticationStrategy) that controls handling of a session during successful authentication. Here, A component to recreate CSRF token (CsrfAuthenticationStrategy) A component to generate a new session for preventing session fixation attack (SessionFixationProtectionStrategy) offered by Spring Security are enabled.
(8)	Specify a handler class in authenticationFailureHandler property which is called at the time of authentication failure.
(9)	Specify a handler class in authenticationSuccessHandler property which is called at the time of successful authentication.

Note

Regarding auto-config

When Basic authentication process and logout process are to be enabled by specifying auto-config="false" or by omitting specification, <sec:http-basic> tag and <sec:logout> tag must be defined explicitly.

9.2.3.9. Using PasswordEncoder of deprecated package

Based on security requirements, it is likely that the implementation is not possible using the class which implements PasswordEncoder described earlier. In particular, when it is necessary to follow hashing requirements used in the existing account information, it may not meet the requirements of PasswordEncoder described earlier.

Basically, existing hashing requirements are as given below.

• Algorithm is SHA-512.
• Stretching frequency is 1000.
• Salt is stored in the account table column and it must be passed from outside of PasswordEncoder.

In such a case, implementation class of org.springframework.security.authentication.encoding.PasswordEncoder interface must be used to meet requirements instead of implementation class of org.springframework.security.crypto.password.PasswordEncoder interface.

Warning

In Spring Security 3.1.4 and earlier versions, a class that implements org.springframework.security.authentication.encoding.PasswordEncoderwas used in the hashing, however, it is deprecated in the 3.1.4 and subsequent versions.

9.2.3.9.1. Using ShaPasswordEncoder

This guideline explains the use of PasswordEncoderof deprecated package using an example of ShaPasswordEncoder.

When the hashing requirements are as below, requirements can be met by using ShaPasswordEncoder.

• Algorithm is SHA-512
• Stretching frequency is 1000

First, define a bean for ShaPasswordEncoder.

• Definition example of applicationContext.xml

<bean id ="passwordEncoder"
    class="org.springframework.security.authentication.encoding.ShaPasswordEncoder"> <!-- (1) -->
    <constructor-arg value="512" /> <!-- (2) -->
    <property name="iterations" value="1000" /> <!-- (3) -->
</bean>

Sr. No.	Description
(1)	Define a bean for org.springframework.security.authentication.encoding.ShaPasswordEncoder.
(2)	Specify type of SHA algorithm. The values that can be specified are “1, 256, 384, 512”. Value is “1” when it is not specified.
(3)	Specify stretching frequency at the time of hashing. Value is 1 when it is not specified.

Next, ShaPasswordEncoder is applied to authentication process (DaoAuthenticationProvider) of Spring Security.

• Definition example of spring-security.xml

<bean id="authenticationProvider"
    class="org.springframework.security.authentication.dao.DaoAuthenticationProvider">
    <!-- omitted -->
    <property name="saltSource" ref="saltSource" /> <!-- (1) -->
    <property name="userDetailsService" ref="userDetailsService" />
    <property name="passwordEncoder" ref="passwordEncoder" /> <!-- (2) -->
</bean>

<bean id="saltSource"
    class="org.springframework.security.authentication.dao.ReflectionSaltSource"> <!-- (3) -->
    <property name="userPropertyToUse" value="username" /> <!-- (4) -->
</bean>

Sr. No.	Description
(1)	Specify a bean for implementation class of org.springframework.security.authentication.dao.SaltSource in saltSource property. SaltSource is an interface that fetches salt from UserDetails.
(2)	Specify a bean for implementation class of org.springframework.security.authentication.encoding.PasswordEncoder interface in passwordEncoder property. In the example above, a bean for ShaPasswordEncoder is specified.
(3)	Define a bean for SaltSource. In the example above, a class (ReflectionSaltSource) that fetches salt from UserDetails property using reflection, is used.
(4)	Specify UserDetails property where salt is stored. In the example above, a value of username property of UserDetails is used as a salt.

When deprecated PasswordEncoder is to be used in the process of application, PasswordEncoder is used after injection.

• Implementation example of Java class

@Inject
PasswordEncoder passwordEncoder;

public String register(Customer customer, String rawPassword, String userSalt) {
    // omitted
    String password = passwordEncoder.encodePassword(rawPassword, userSalt); // (1)
    customer.setPassword(password);
    // omitted
}

public boolean matches(Customer customer, String rawPassword, String userSalt) {
    return passwordEncoder.isPasswordValid(customer.getPassword(), rawPassword, userSalt); // (2)
}

Sr. No.	Description
(1)	When password is to be hashed, use encodePassword method. Specify password, salt string in the method argument, in a sequence.
(2)	When the password is to be verified, use isPasswordValid method. Specify hashed password, plain text password and salt string in the method argument, in a sequence.

9.2.4. Appendix

9.2.4.1. Receive a request by Spring MVC and display login form

A method wherein a request is received by Spring MVC and login form is displayed is explained.

• Definition example of spring-mvc.xml

Definition example of Controller which displays login form.

@Controller
@RequestMapping("/login")
public class LoginController { // (1)

    @RequestMapping
    public String index() {
        return "login";
    }
}

Sr. No.	Description
(1)	Return “login” as view name. src/main/webapp/WEB-INF/views/login.jsp is output by InternalResourceViewResolver

As per this example, it is also possible to substitute by using <mvc:view-controller> in case of a controller with only one method which simply returns only the view name.

For details, refer HTML response.

9.2.4.2. Using Remember Me authentication

“Remember Me authentication” is one of the functions to enhance the user experience who frequently access Websites, and retains logged in state of a user for a little longer than normal lifecycle. If this function is used, the user can login again without entering user name and password by using a Token for Remember Me authentication retained by a Cookie, even when the browser is closed or session has timed-out. Note that, this function is enabled only when the user has authorised retaining the logged in state.

Spring Security supports “Remember Me authentication of Hash-Based Token method and Persistent Token method. Hash-Based Token method is used as a default.

When Remember Me authentication is to be used, <sec:remember-me> tag is added.

• Definition example of spring-security.xml

<sec:http>
    <!-- omitted -->
    <sec:remember-me key="terasoluna-tourreservation-km/ylnHv"
        token-validity-seconds="#{30 * 24 * 60 * 60}" />  <!-- (1) (2) -->
    <!-- omitted -->
</sec:http>

Sr. No.	Description
(1)	Specify a key value in key attribute for identifying an application that generates a Token for Remember Me authentication. When key value is not specified, a unique value is generated every time an application starts. Note that, when a key value retained by Hash-Based Token and a key value retained by server vary, it is handled as an invalid Token. In other words, when a Hash-Based Token generated before restarting an application is to be handled as a valid Token, key attribute must be specified.
(2)	Specify validity period of Token for Remember Me authentication in seconds, in the token-validity-seconds attribute. When it is not specified, the validity period is 14 days by default. In the example above, 30 days has been set as a validity period.

For attributes other than above, refer Spring Security Reference -The Security Namespace (<remember-me>) -.

Note

Changes in Spring Security 4.0

Default value of following settings is changed from Spring Security 4.0 version

• remember-me-parameter
• remember-me-cookie

A flag (checkbox field) to specify use of “Remember Me authentication” function is provided in the login form.

• Implementation example of JSP of login form

<form:form action="${pageContext.request.contextPath}/login" method="post">
        <!-- omitted -->
        <tr>
            <td><label for="remember-me">Remember Me : </label></td>
            <td><input name="remember-me" id="remember-me" type="checkbox" checked="checked" value="true"></td> <!-- (1) -->
        </tr>
        <!-- omitted -->
</form:form>

Sr. No.	Description
(1)	Add a flag (checkbox item) to specify whether “Remember Me authentication” function is used, and specify remember-me - a default value of remember-me-parameter in field name (request parameter name). Set true in value attribute of checkbox. If authentication process is carried out after ticking the checkbox, “Remember Me authentication” function is applied for subsequent requests.

Tip

About setup value of value attribute

Description of setting true in value attribute is given in rememberMeRequested - JavaDoc, however on, yes and 1 can also be set in the implementation.