org.apache.shiro.web.filter.authc

Class BasicHttpAuthenticationFilter

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.BasicHttpAuthenticationFilter

All Implemented Interfaces:

javax.servlet.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

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
BasicHttpAuthenticationFilter()

Method Summary

Modifier and Type	Method and Description
protected AuthenticationToken	createToken(javax.servlet.ServletRequest request, javax.servlet.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(javax.servlet.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, javax.servlet.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	isAccessAllowed(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, Object mappedValue) The Basic authentication filter can be configured with a list of HTTP methods to which it should apply.
protected boolean	isLoginAttempt(javax.servlet.ServletRequest request, javax.servlet.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(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response) Delegates to isLoginAttempt.
protected boolean	onAccessDenied(javax.servlet.ServletRequest request, javax.servlet.ServletResponse response) Processes unauthenticated requests.
protected boolean	sendChallenge(javax.servlet.ServletRequest request, javax.servlet.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, 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)

isAccessAllowed

protected boolean isAccessAllowed(javax.servlet.ServletRequest request,
                                  javax.servlet.ServletResponse response,
                                  Object mappedValue)

The Basic authentication filter can be configured with a list of HTTP methods to which it should apply. This method ensures that authentication is only required for those HTTP methods specified. For example, if you had the configuration:

    [urls]
    /basic/** = authcBasic[POST,PUT,DELETE]
 

then a GET request would not required authentication but a POST would.

Overrides:

isAccessAllowed in class AuthenticatingFilter

Parameters:

request - The current HTTP servlet request.

response - The current HTTP servlet response.

mappedValue - The array of configured HTTP methods as strings. This is empty if no methods are configured.

Returns:

true if request should be allowed access

onAccessDenied

protected boolean onAccessDenied(javax.servlet.ServletRequest request,
                                 javax.servlet.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(javax.servlet.ServletRequest request,
                                 javax.servlet.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(javax.servlet.ServletRequest request,
                                       javax.servlet.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(javax.servlet.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(javax.servlet.ServletRequest request,
                                javax.servlet.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(javax.servlet.ServletRequest request,
                                          javax.servlet.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,
                                               javax.servlet.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.