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

java.lang.Object
  extended by org.apache.shiro.web.servlet.ServletContextSupport
      extended by org.apache.shiro.web.servlet.AbstractFilter
          extended by org.apache.shiro.web.servlet.NameableFilter
              extended by org.apache.shiro.web.servlet.OncePerRequestFilter
                  extended by org.apache.shiro.web.servlet.AdviceFilter
                      extended by org.apache.shiro.web.filter.PathMatchingFilter
                          extended by org.apache.shiro.web.filter.AccessControlFilter
                              extended by org.apache.shiro.web.filter.authc.AuthenticationFilter
                                  extended by org.apache.shiro.web.filter.authc.AuthenticatingFilter
                                      extended by org.apache.shiro.web.filter.authc.BasicHttpAuthenticationFilter
All Implemented Interfaces:
Filter, Nameable, PathConfigProcessor

public class BasicHttpAuthenticationFilter
extends AuthenticatingFilter

Requires the requesting user to be authenticated for the request to continue, and if they're not, requires the user to login via the HTTP Basic protocol-specific challenge. Upon successful login, they're allowed to continue on to the requested resource/url.

This implementation is a 'clean room' Java implementation of Basic HTTP Authentication specification per RFC 2617.

Basic authentication functions as follows:

  1. A request comes in for a resource that requires authentication.
  2. The server replies with a 401 response status, sets the WWW-Authenticate header, and the contents of a page informing the user that the incoming resource requires authentication.
  3. Upon receiving this WWW-Authenticate challenge from the server, the client then takes a username and a password and puts them in the following format:

    username:password

  4. This token is then base 64 encoded.
  5. The client then sends another request for the same resource with the following header:

    Authorization: Basic Base64_encoded_username_and_password

The onAccessDenied(javax.servlet.ServletRequest, javax.servlet.ServletResponse) method will only be called if the subject making the request is not authenticated

Since:
0.9
See Also:
RFC 2617, Basic Access Authentication

Field Summary
protected static String AUTHENTICATE_HEADER
          HTTP Authentication header, equal to WWW-Authenticate
protected static String AUTHORIZATION_HEADER
          HTTP Authorization header, equal to Authorization
 
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
BasicHttpAuthenticationFilter()
           
 
Method Summary
protected  AuthenticationToken createToken(ServletRequest request, ServletResponse response)
          Creates an AuthenticationToken for use during login attempt with the provided credentials in the http header.
 String getApplicationName()
          Returns the name to use in the ServletResponse's WWW-Authenticate header.
 String getAuthcScheme()
          Returns the HTTP WWW-Authenticate header scheme that this filter will use when sending the HTTP Basic challenge response.
protected  String getAuthzHeader(ServletRequest request)
          Returns the AUTHORIZATION_HEADER from the specified ServletRequest.
 String getAuthzScheme()
          Returns the HTTP Authorization header value that this filter will respond to as indicating a login request.
protected  String[] getPrincipalsAndCredentials(String authorizationHeader, ServletRequest request)
          Returns the username obtained from the authorizationHeader.
protected  String[] getPrincipalsAndCredentials(String scheme, String encoded)
          Returns the username and password pair based on the specified encoded String obtained from the request's authorization header.
protected  boolean isLoginAttempt(ServletRequest request, ServletResponse response)
          Determines whether the incoming request is an attempt to log in.
protected  boolean isLoginAttempt(String authzHeader)
          Default implementation that returns true if the specified authzHeader starts with the same (case-insensitive) characters specified by the authzScheme, false otherwise.
protected  boolean isLoginRequest(ServletRequest request, ServletResponse response)
          Delegates to isLoginAttempt.
protected  boolean onAccessDenied(ServletRequest request, ServletResponse response)
          Processes unauthenticated requests.
protected  boolean sendChallenge(ServletRequest request, ServletResponse response)
          Builds the challenge for authorization by setting a HTTP 401 (Unauthorized) status as well as the response's AUTHENTICATE_HEADER.
 void setApplicationName(String applicationName)
          Sets the name to use in the ServletResponse's WWW-Authenticate header.
 void setAuthcScheme(String authcScheme)
          Sets the HTTP WWW-Authenticate header scheme that this filter will use when sending the HTTP Basic challenge response.
 void setAuthzScheme(String authzScheme)
          Sets the HTTP Authorization header value that this filter will respond to as indicating a login request.
 
Methods inherited from class org.apache.shiro.web.filter.authc.AuthenticatingFilter
cleanup, createToken, createToken, executeLogin, getHost, isAccessAllowed, isPermissive, isRememberMe, onLoginFailure, onLoginSuccess
 
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, onAccessDenied, onPreHandle, redirectToLogin, saveRequest, saveRequestAndRedirectToLogin, setLoginUrl
 
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

AUTHORIZATION_HEADER

protected static final String AUTHORIZATION_HEADER
HTTP Authorization header, equal to Authorization

See Also:
Constant Field Values

AUTHENTICATE_HEADER

protected static final String AUTHENTICATE_HEADER
HTTP Authentication header, equal to WWW-Authenticate

See Also:
Constant Field Values
Constructor Detail

BasicHttpAuthenticationFilter

public BasicHttpAuthenticationFilter()
Method Detail

getApplicationName

public String getApplicationName()
Returns the name to use in the ServletResponse's WWW-Authenticate header.

Per RFC 2617, this name name is displayed to the end user when they are asked to authenticate. Unless overridden by the setApplicationName(String) method, the default value is 'application'.

Please see setApplicationName(String) for an example of how this functions.

Returns:
the name to use in the ServletResponse's 'WWW-Authenticate' header.

setApplicationName

public void setApplicationName(String applicationName)
Sets the name to use in the ServletResponse's WWW-Authenticate header.

Per RFC 2617, this name name is displayed to the end user when they are asked to authenticate. Unless overridden by this method, the default value is "application"

For example, setting this property to the value Awesome Webapp will result in the following header:

WWW-Authenticate: Basic realm="Awesome Webapp"

Side note: As you can see from the header text, the HTTP Basic specification calls this the authentication 'realm', but we call this the 'applicationName' instead to avoid confusion with Shiro's Realm constructs.

Parameters:
applicationName - the name to use in the ServletResponse's 'WWW-Authenticate' header.

getAuthzScheme

public String getAuthzScheme()
Returns the HTTP Authorization header value that this filter will respond to as indicating a login request.

Unless overridden by the setAuthzScheme(String) method, the default value is BASIC.

Returns:
the Http 'Authorization' header value that this filter will respond to as indicating a login request

setAuthzScheme

public void setAuthzScheme(String authzScheme)
Sets the HTTP Authorization header value that this filter will respond to as indicating a login request.

Unless overridden by this method, the default value is BASIC

Parameters:
authzScheme - the HTTP Authorization header value that this filter will respond to as indicating a login request.

getAuthcScheme

public String getAuthcScheme()
Returns the HTTP WWW-Authenticate header scheme that this filter will use when sending the HTTP Basic challenge response. The default value is BASIC.

Returns:
the HTTP WWW-Authenticate header scheme that this filter will use when sending the HTTP Basic challenge response.
See Also:
sendChallenge(javax.servlet.ServletRequest, javax.servlet.ServletResponse)

setAuthcScheme

public void setAuthcScheme(String authcScheme)
Sets the HTTP WWW-Authenticate header scheme that this filter will use when sending the HTTP Basic challenge response. The default value is BASIC.

Parameters:
authcScheme - the HTTP WWW-Authenticate header scheme that this filter will use when sending the Http Basic challenge response.
See Also:
sendChallenge(javax.servlet.ServletRequest, javax.servlet.ServletResponse)

onAccessDenied

protected boolean onAccessDenied(ServletRequest request,
                                 ServletResponse response)
                          throws Exception
Processes unauthenticated requests. It handles the two-stage request/challenge authentication protocol.

Specified by:
onAccessDenied in class AccessControlFilter
Parameters:
request - incoming ServletRequest
response - outgoing ServletResponse
Returns:
true if the request should be processed; false if the request should not continue to be processed
Throws:
Exception - if there is an error processing the request.

isLoginAttempt

protected boolean isLoginAttempt(ServletRequest request,
                                 ServletResponse response)
Determines whether the incoming request is an attempt to log in.

The default implementation obtains the value of the request's AUTHORIZATION_HEADER, and if it is not null, delegates to isLoginAttempt(authzHeaderValue). If the header is null, false is returned.

Parameters:
request - incoming ServletRequest
response - outgoing ServletResponse
Returns:
true if the incoming request is an attempt to log in based, false otherwise

isLoginRequest

protected final boolean isLoginRequest(ServletRequest request,
                                       ServletResponse response)
Delegates to isLoginAttempt.

Overrides:
isLoginRequest in class AccessControlFilter
Parameters:
request - the incoming ServletRequest
response - the outgoing ServletResponse
Returns:
true if the incoming request is a login request, false otherwise.

getAuthzHeader

protected String getAuthzHeader(ServletRequest request)
Returns the AUTHORIZATION_HEADER from the specified ServletRequest.

This implementation merely casts the request to an HttpServletRequest and returns the header:

HttpServletRequest httpRequest = toHttp(reaquest);
return httpRequest.getHeader(AUTHORIZATION_HEADER);

Parameters:
request - the incoming ServletRequest
Returns:
the Authorization header's value.

isLoginAttempt

protected boolean isLoginAttempt(String authzHeader)
Default implementation that returns true if the specified authzHeader starts with the same (case-insensitive) characters specified by the authzScheme, false otherwise.

That is:

String authzScheme = getAuthzScheme().toLowerCase();
return authzHeader.toLowerCase().startsWith(authzScheme);

Parameters:
authzHeader - the 'Authorization' header value (guaranteed to be non-null if the isLoginAttempt(javax.servlet.ServletRequest, javax.servlet.ServletResponse) method is not overriden).
Returns:
true if the authzHeader value matches that configured as defined by the authzScheme.

sendChallenge

protected boolean sendChallenge(ServletRequest request,
                                ServletResponse response)
Builds the challenge for authorization by setting a HTTP 401 (Unauthorized) status as well as the response's AUTHENTICATE_HEADER.

The header value constructed is equal to:

getAuthcScheme() + " realm=\"" + getApplicationName() + "\"";

Parameters:
request - incoming ServletRequest, ignored by this implementation
response - outgoing ServletResponse
Returns:
false - this sends the challenge to be sent back

createToken

protected AuthenticationToken createToken(ServletRequest request,
                                          ServletResponse response)
Creates an AuthenticationToken for use during login attempt with the provided credentials in the http header.

This implementation:

  1. acquires the username and password based on the request's authorization header via the getPrincipalsAndCredentials method
  2. The return value of that method is converted to an AuthenticationToken via the createToken method
  3. The created AuthenticationToken is returned.

Specified by:
createToken in class AuthenticatingFilter
Parameters:
request - incoming ServletRequest
response - outgoing ServletResponse
Returns:
the AuthenticationToken used to execute the login attempt

getPrincipalsAndCredentials

protected String[] getPrincipalsAndCredentials(String authorizationHeader,
                                               ServletRequest request)
Returns the username obtained from the authorizationHeader.

Once the authzHeader is split per the RFC (based on the space character ' '), the resulting split tokens are translated into the username/password pair by the getPrincipalsAndCredentials(scheme,encoded) method.

Parameters:
authorizationHeader - the authorization header obtained from the request.
request - the incoming ServletRequest
Returns:
the username (index 0)/password pair (index 1) submitted by the user for the given header value and request.
See Also:
getAuthzHeader(javax.servlet.ServletRequest)

getPrincipalsAndCredentials

protected String[] getPrincipalsAndCredentials(String scheme,
                                               String encoded)
Returns the username and password pair based on the specified encoded String obtained from the request's authorization header.

Per RFC 2617, the default implementation first Base64 decodes the string and then splits the resulting decoded string into two based on the ":" character. That is:

String decoded = Base64.decodeToString(encoded);
return decoded.split(":");

Parameters:
scheme - the authcScheme found in the request authzHeader. It is ignored by this implementation, but available to overriding implementations should they find it useful.
encoded - the Base64-encoded username:password value found after the scheme in the header
Returns:
the username (index 0)/password (index 1) pair obtained from the encoded header data.


Copyright © 2004-2014 The Apache Software Foundation. All Rights Reserved.