Class BasicAuthHandler

  • All Implemented Interfaces:
    Handler

    public class BasicAuthHandler
    extends java.lang.Object
    implements Handler
    The BasicAuthHandler obtains a Session ID by performing "basic" authentication, using either the "Authorization" or the "Proxy-Authorization" headers. This handler prevents subsequent downstream handlers from being accessed unless the proper authentication was seen in the request. The Session ID obtained by this handler is meant to be used by those downsteams handlers to access whatever session-dependent information they need.

    If the request does not contain the authentication headers or the authentication information is not valid, this handler sends an HTTP error message along with the "WWW-Authenticate" or "Proxy-Authenticate" header, as appropriate. See code, authorization, authenticate

    If the request does contain valid authentication information, the Session ID associated with the authentication information is inserted into the request properties, for use by downstream handlers. After inserting the Session ID, this handler returns false to allow the downstream handlers to run. IF the Session ID in empty (e.g. ""), then, although authenticateion succeeds, no Session Id property is set.

    The set of valid Session IDs is contained in a globally accessible table managed by the SessionManager, which may be initialized with a static table (see mapFile).

    The format of the initialization table (if any) described above is a Java properties file where keys are the Base64 encoded strings obtained from the Authentication header and the values are the associated Session IDs. Base64 strings can contain the '=' character, but the keys in a Java properties file cannot contain an '=' character, so all '=' characters in the Base64 strings must be converted to '!' in the properties file, as shown in the following sample properties file:

     bXIuIGhhdGU6a2ZqYw!! = radion
     Zm9vOmJhcg!! = foo
     
    The data in the SessionManager table doesn't use the '!'s, only ='s.
    There are several different types of authentication possible. All authentication handlers should follow these basic principles:
    • The authentication handler examines some aspect of the request to decide if the appropriate authentication is present.
    • If the request is acceptable, the authentication handler should insert the extracted Session ID into a request property and then return false, to allow subsequent handlers to run and perhaps use the Session ID.
    • If the request is not acceptable, the authentication handler can return an error message or do some other thing to try to obtain a valid authentication.
    • Handlers wishing to be protected by authentication should not subclass an authentication handler. Instead, such handler should be written to assume that authentication has already been performed and then just examine the Session ID present. The web developer is then responsible for choosing which one (of possibly many) forms of authentication to use and installing those authentication handlers before the "sensitive" handler.
    • Handlers that are protected by an authentication handler can use the Session ID stored in the request properties regardless of the specifics of the authentication handler.
     handlers=auth history file
    
     auth.class=BasicAuthHandler
     auth.session=account
     auth.message=Go away, you're not allowed here!
    
     history.class=HistoryHandler
     history.session=account
    
     file.class=FileHandler
     file.root=htdocs
     
    In the sample pseudo-configuation file specified above, the BasicAuthHandler is first invoked to see if the HTTP "basic" authentication header is present in the request. If it isn't, a nasty message is sent back. If the "basic" authentication header is present and corresponds to a user that the BasicAuthHandler knows about, the Session ID associated with that user is stored in the specified property named "account".

    Subsequently, the HistoryHandler examines its specified property (also "account") for the Session ID and uses that to keep track of which session is issuing the HTTP request.

    Each handler that needs a Session ID should have a configuration parameter that allows the web developer to specify the name of the request property that holds the Session ID. Multiple handlers can all use the same request property as each other, all protected by the same authentication handler.


    This handler uses the following configuration properties:
    prefix, suffix, glob, match
    Sepcify the URL that triggers this handler.
    code
    The type of authentication to perform. The default value is 401.

    The value 401 corresponds to standard "basic" authentication. The "Authorization" request header is supposed to contain the authentication string. If the request was not authenticated, the "WWW-Authenticate" header is sent in the HTTP error response to cause the browser to prompt the client to authenticate.

    The value 407 corresponds to "basic" proxy/firewall authentication. The "Proxy-Authorization" request header is supposed to contain the authentication string. If the request was not authenticated, the "Proxy-Authenticate" header is sent in the HTTP error response to cause the browser to prompt the client to authenticate.

    Any other value may also be specified. Whatever the value, it will be returned as the HTTP result code of the error message.

    authorization
    If specified, this is the request header that will contain the "basic" authentication string, instead of the "Authorization" or "Proxy-Authorization" header implied by code.
    authenticate
    If specified, this is the response header that will be sent in the HTTP error response if the user is not authenticated.

    If this string is "", then this handler will authenticate the request if the authorization header is present, but will not send an HTTP error message if the request could not be authenticated. This is useful if the web developer wants to do something more complex (such as invoking an arbitrary set of handlers) instead of just sending a simple error message if the request was not authenticated. In this case, the web developer can determine that the request was not authenticated because no Session ID will be present in the request properties.

    realm
    The "realm" of the HTTP authentication error message. This is a string that the browser is supposed to present to the client when asking the client the authenticate. It provides a human-friendly name describing who wants the authentication.
    message
    The body of the HTTP authentication error message. This will be displayed by the browser if the client chooses not to authenticate. The default value is "". Patterns of the form ${xxx} are replaced with the value of the xxx entry of request.props.
    mapFile
    If specified, this is the initial Session ID file. This is expected to be a java properties file, whose keys are the authentication tokens, and whose values are the Session IDs that are inserted into the request properties.

    The keys in the file are basic authentication (base64) tokens with any trailing "=" characters changed to "!".

    session
    The name of the request property that the Session ID will be stored in, to be passed to downstream handlers. The default value is "SessionID".
    ident
    The ident argument to SessionManager.getSession(java.lang.Object, java.lang.Object, java.lang.Class) to get the table of valid sessions. The default value is "authorized". If ident is of the form ident:session, then the session portion is used as the session argument to SessionManager.get(). Otherwise the session argument is NULL. This table may be manipulated with the SetTemplate, using the "ident" namespace and "session" for the SetTemplate "sessionTable" parameter.
    Version:
    2.3, 06/11/13
    Author:
    Stephen Uhler (stephen.uhler@sun.com), Colin Stevens (colin.stevens@sun.com)
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      boolean complain​(Request request, java.lang.String reason)
      Authentication failed.
      boolean init​(Server server, java.lang.String propsPrefix)
      Initializes this handler.
      boolean respond​(Request request)
      Looks up the credentials for this request, and insert them into the request stream.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • code

        public int code
      • authorization

        public java.lang.String authorization
      • authenticate

        public java.lang.String authenticate
      • realm

        public java.lang.String realm
      • message

        public java.lang.String message
      • mapFile

        public java.lang.String mapFile
      • session

        public java.lang.String session
      • ident

        public java.lang.String ident
      • sessionTable

        public java.lang.String sessionTable
    • Constructor Detail

      • BasicAuthHandler

        public BasicAuthHandler()
    • Method Detail

      • init

        public boolean init​(Server server,
                            java.lang.String propsPrefix)
        Initializes this handler. It is an error if the mapFile parameter is specified but that file cannot be loaded.
        Specified by:
        init in interface Handler
        Parameters:
        server - The HTTP server that created this handler.
        prefix - A prefix to prepend to all of the keys that this handler uses to extract configuration information.
        Returns:
        true if this Handler initialized successfully, false otherwise.
      • respond

        public boolean respond​(Request request)
                        throws java.io.IOException
        Looks up the credentials for this request, and insert them into the request stream. If no credentials are found, prompt the user for them.
        Specified by:
        respond in interface Handler
        Parameters:
        request - The Request object that represents the HTTP request.
        Returns:
        true if the request was handled. A request was handled if a response was supplied to the client, typically by calling Request.sendResponse() or Request.sendError.
        Throws:
        java.io.IOException - if there was an I/O error while sending the response to the client. Typically, in that case, the Server will (try to) send an error message to the client and then close the client's connection.

        The IOException should not be used to silently ignore problems such as being unable to access some server-side resource (for example getting a FileNotFoundException due to not being able to open a file). In that case, the Handler's duty is to turn that IOException into a HTTP response indicating, in this case, that a file could not be found.

      • complain

        public boolean complain​(Request request,
                                java.lang.String reason)
                         throws java.io.IOException
        Authentication failed. Send the appropriate authentication required header as a response.
        Parameters:
        request - The request to respond to
        reason - The reason for failure (for diagnostics)
        Returns:
        True
        Throws:
        java.io.IOException