Package org.tynamo.security.shiro.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.tynamo.security.shiro.AccessControlFilter
org.tynamo.security.shiro.authc.AuthenticationFilter
org.tynamo.security.shiro.authc.AuthenticatingFilter
org.tynamo.security.shiro.authc.BasicHttpAuthenticationFilter
All Implemented Interfaces:
jakarta.servlet.Filter, org.apache.shiro.lang.util.Nameable
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(jakarta.servlet.ServletRequest, jakarta.servlet.ServletResponse) method will only be called if the subject making the request is not authenticated
Since:
0.4.0
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

    • BasicHttpAuthenticationFilter

      public BasicHttpAuthenticationFilter(LoginContextService loginContextService)

  • Method Details

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

    • onAccessDenied

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

    • getAuthzHeader

      protected String getAuthzHeader(jakarta.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(jakarta.servlet.ServletRequest, jakarta.servlet.ServletResponse) method is not overriden).
      Returns:
      true if the authzHeader value matches that configured as defined by the authzScheme.

    • sendChallenge

      protected boolean sendChallenge(jakarta.servlet.ServletRequest request, jakarta.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 org.apache.shiro.authc.AuthenticationToken createToken(jakarta.servlet.ServletRequest request, jakarta.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, jakarta.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:

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