org.apache.shiro.web.filter.authc
Class FormAuthenticationFilter

java.lang.Object
  org.apache.shiro.web.servlet.ServletContextSupport
      org.apache.shiro.web.servlet.AbstractFilter
          org.apache.shiro.web.servlet.NameableFilter
              org.apache.shiro.web.servlet.OncePerRequestFilter
                  org.apache.shiro.web.servlet.AdviceFilter
                      org.apache.shiro.web.filter.PathMatchingFilter
                          org.apache.shiro.web.filter.AccessControlFilter
                              org.apache.shiro.web.filter.authc.AuthenticationFilter
                                  org.apache.shiro.web.filter.authc.AuthenticatingFilter
                                      org.apache.shiro.web.filter.authc.FormAuthenticationFilter

All Implemented Interfaces:

Filter, Nameable, PathConfigProcessor

public class FormAuthenticationFilter
extends AuthenticatingFilter

Requires the requesting user to be authenticated for the request to continue, and if they are not, forces the user to login via by redirecting them to the loginUrl you configure.

This filter constructs a UsernamePasswordToken with the values found in username, password, and rememberMe request parameters. It then calls Subject.login(usernamePasswordToken), effectively automatically performing a login attempt. Note that the login attempt will only occur when the isLoginSubmission(request,response) is true, which by default occurs when the request is for the loginUrl and is a POST request.

If the login attempt fails, the resulting AuthenticationException fully qualified class name will be set as a request attribute under the failureKeyAttribute key. This FQCN can be used as an i18n key or lookup mechanism to explain to the user why their login attempt failed (e.g. no account, incorrect password, etc).

If you would prefer to handle the authentication validation and login in your own code, consider using the PassThruAuthenticationFilter instead, which allows requests to the AccessControlFilter.loginUrl to pass through to your application's code directly.

Since:

0.9

See Also:

PassThruAuthenticationFilter

Field Summary

static String	DEFAULT_ERROR_KEY_ATTRIBUTE_NAME
static String	DEFAULT_PASSWORD_PARAM
static String	DEFAULT_REMEMBER_ME_PARAM
static String	DEFAULT_USERNAME_PARAM

Fields inherited from class org.apache.shiro.web.filter.authc.AuthenticatingFilter

PERMISSIVE

Fields inherited from class org.apache.shiro.web.filter.authc.AuthenticationFilter

DEFAULT_SUCCESS_URL

Fields inherited from class org.apache.shiro.web.filter.AccessControlFilter

DEFAULT_LOGIN_URL, GET_METHOD, POST_METHOD

Fields inherited from class org.apache.shiro.web.filter.PathMatchingFilter

appliedPaths, pathMatcher

Fields inherited from class org.apache.shiro.web.servlet.OncePerRequestFilter

ALREADY_FILTERED_SUFFIX

Fields inherited from class org.apache.shiro.web.servlet.AbstractFilter

filterConfig

Constructor Summary

FormAuthenticationFilter()

Method Summary

protected AuthenticationToken	createToken(ServletRequest request, ServletResponse response)
String	getFailureKeyAttribute()
protected String	getPassword(ServletRequest request)
String	getPasswordParam()
String	getRememberMeParam()
protected String	getUsername(ServletRequest request)
String	getUsernameParam()
protected boolean	isLoginSubmission(ServletRequest request, ServletResponse response) This default implementation merely returns true if the request is an HTTP POST, false otherwise.
protected boolean	isRememberMe(ServletRequest request) Returns true if "rememberMe" should be enabled for the login attempt associated with the current request, false otherwise.
protected boolean	onAccessDenied(ServletRequest request, ServletResponse response) Processes requests where the subject was denied access as determined by the isAccessAllowed method.
protected boolean	onLoginFailure(AuthenticationToken token, AuthenticationException e, ServletRequest request, ServletResponse response)
protected boolean	onLoginSuccess(AuthenticationToken token, Subject subject, ServletRequest request, ServletResponse response)
protected void	setFailureAttribute(ServletRequest request, AuthenticationException ae)
void	setFailureKeyAttribute(String failureKeyAttribute)
void	setLoginUrl(String loginUrl) Sets the login URL used to authenticate a user.
void	setPasswordParam(String passwordParam) Sets the request parameter name to look for when acquiring the password.
void	setRememberMeParam(String rememberMeParam) Sets the request parameter name to look for when acquiring the rememberMe boolean value.
void	setUsernameParam(String usernameParam) Sets the request parameter name to look for when acquiring the username.

Methods inherited from class org.apache.shiro.web.filter.authc.AuthenticatingFilter

cleanup, createToken, createToken, executeLogin, getHost, isAccessAllowed, isPermissive

Methods inherited from class org.apache.shiro.web.filter.authc.AuthenticationFilter

getSuccessUrl, issueSuccessRedirect, setSuccessUrl

Methods inherited from class org.apache.shiro.web.filter.AccessControlFilter

getLoginUrl, getSubject, isLoginRequest, onAccessDenied, onPreHandle, redirectToLogin, saveRequest, saveRequestAndRedirectToLogin

Methods inherited from class org.apache.shiro.web.filter.PathMatchingFilter

getPathWithinApplication, isEnabled, pathsMatch, pathsMatch, preHandle, processPathConfig

Methods inherited from class org.apache.shiro.web.servlet.AdviceFilter

afterCompletion, doFilterInternal, executeChain, postHandle

Methods inherited from class org.apache.shiro.web.servlet.OncePerRequestFilter

doFilter, getAlreadyFilteredAttributeName, isEnabled, isEnabled, setEnabled, shouldNotFilter

Methods inherited from class org.apache.shiro.web.servlet.NameableFilter

getName, setName, toStringBuilder

Methods inherited from class org.apache.shiro.web.servlet.AbstractFilter

destroy, getFilterConfig, getInitParam, init, onFilterConfigSet, setFilterConfig

Methods inherited from class org.apache.shiro.web.servlet.ServletContextSupport

getContextAttribute, getContextInitParam, getServletContext, removeContextAttribute, setContextAttribute, setServletContext, toString

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ERROR_KEY_ATTRIBUTE_NAME

public static final String DEFAULT_ERROR_KEY_ATTRIBUTE_NAME

See Also:

Constant Field Values

DEFAULT_USERNAME_PARAM

public static final String DEFAULT_USERNAME_PARAM

See Also:

Constant Field Values

DEFAULT_PASSWORD_PARAM

public static final String DEFAULT_PASSWORD_PARAM

See Also:

Constant Field Values

DEFAULT_REMEMBER_ME_PARAM

public static final String DEFAULT_REMEMBER_ME_PARAM

See Also:

Constant Field Values

Constructor Detail

FormAuthenticationFilter

public FormAuthenticationFilter()

Method Detail

setLoginUrl

public void setLoginUrl(String loginUrl)

Description copied from class: AccessControlFilter

Sets the login URL used to authenticate a user.

Most Shiro filters use this url as the location to redirect a user when the filter requires authentication. Unless overridden, the DEFAULT_LOGIN_URL is assumed.

Overrides:

setLoginUrl in class AccessControlFilter

Parameters:

loginUrl - the login URL used to authenticate a user, used when redirecting users if authentication is required.

getUsernameParam

public String getUsernameParam()

setUsernameParam

public void setUsernameParam(String usernameParam)

Sets the request parameter name to look for when acquiring the username. Unless overridden by calling this method, the default is username.

Parameters:

usernameParam - the name of the request param to check for acquiring the username.

getPasswordParam

public String getPasswordParam()

setPasswordParam

public void setPasswordParam(String passwordParam)

Sets the request parameter name to look for when acquiring the password. Unless overridden by calling this method, the default is password.

Parameters:

passwordParam - the name of the request param to check for acquiring the password.

getRememberMeParam

public String getRememberMeParam()

setRememberMeParam

public void setRememberMeParam(String rememberMeParam)

Sets the request parameter name to look for when acquiring the rememberMe boolean value. Unless overridden by calling this method, the default is rememberMe.

RememberMe will be true if the parameter value equals any of those supported by WebUtils.isTrue(request,value), false otherwise.

Parameters:

rememberMeParam - the name of the request param to check for acquiring the rememberMe boolean value.

getFailureKeyAttribute

public String getFailureKeyAttribute()

setFailureKeyAttribute

public void setFailureKeyAttribute(String failureKeyAttribute)

onAccessDenied

protected boolean onAccessDenied(ServletRequest request,
                                 ServletResponse response)
                          throws Exception

Description copied from class: AccessControlFilter

Processes requests where the subject was denied access as determined by the isAccessAllowed method.

Specified by:

onAccessDenied in class AccessControlFilter

Parameters:

request - the incoming ServletRequest

response - the outgoing ServletResponse

Returns:

true if the request should continue to be processed; false if the subclass will handle/render the response directly.

Throws:

Exception - if there is an error processing the request.

isLoginSubmission

protected boolean isLoginSubmission(ServletRequest request,
                                    ServletResponse response)

This default implementation merely returns true if the request is an HTTP POST, false otherwise. Can be overridden by subclasses for custom login submission detection behavior.

Parameters:

request - the incoming ServletRequest

response - the outgoing ServletResponse.

Returns:

true if the request is an HTTP POST, false otherwise.

createToken

protected AuthenticationToken createToken(ServletRequest request,
                                          ServletResponse response)

Specified by:

createToken in class AuthenticatingFilter

isRememberMe

protected boolean isRememberMe(ServletRequest request)

Description copied from class: AuthenticatingFilter

Returns true if "rememberMe" should be enabled for the login attempt associated with the current request, false otherwise.

This implementation always returns false and is provided as a template hook to subclasses that support rememberMe logins and wish to determine rememberMe in a custom mannner based on the current request.

Overrides:

isRememberMe in class AuthenticatingFilter

Parameters:

request - the incoming ServletRequest

Returns:

true if "rememberMe" should be enabled for the login attempt associated with the current request, false otherwise.

onLoginSuccess

protected boolean onLoginSuccess(AuthenticationToken token,
                                 Subject subject,
                                 ServletRequest request,
                                 ServletResponse response)
                          throws Exception

Overrides:

onLoginSuccess in class AuthenticatingFilter

Throws:

Exception

onLoginFailure

protected boolean onLoginFailure(AuthenticationToken token,
                                 AuthenticationException e,
                                 ServletRequest request,
                                 ServletResponse response)

Overrides:

onLoginFailure in class AuthenticatingFilter

setFailureAttribute

protected void setFailureAttribute(ServletRequest request,
                                   AuthenticationException ae)

getUsername

protected String getUsername(ServletRequest request)

getPassword

protected String getPassword(ServletRequest request)