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, org.apache.shiro.lang.util.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 AccessControlFilter.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:

  • Field Details

    • AUTHORIZATION_HEADER

      protected static final String AUTHORIZATION_HEADER
      HTTP Authorization header, equal to Authorization
      See Also:

    • AUTHENTICATE_HEADER

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

  • Constructor Details

  • Method Details

    • createToken

      protected org.apache.shiro.authc.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.
      Parameters:
      request - incoming ServletRequest
      response - outgoing ServletResponse (never used)
      Returns:
      the AuthenticationToken used to execute the login attempt

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

    • 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:

    • 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:

    • 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(request);
      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(ServletRequest, ServletResponse) method is not overridden).
      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

    • 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: