com.cometway.httpd
Class HTTPAuthenticationAgent

java.lang.Object
  com.cometway.props.Props
      com.cometway.ak.Agent
          com.cometway.ak.ServiceAgent
              com.cometway.httpd.WebServerExtension
                  com.cometway.httpd.HTTPAuthenticationAgent

All Implemented Interfaces:

AgentInterface, HasStateMachineModel

public class HTTPAuthenticationAgent
extends WebServerExtension

This agent is used by the WebServer to handle authorization of password protected accesses.

The authentication file defines the realms and the usernames and passwords which are used to authenticate accesses to the paths associated with each realm. The authentication file is delimited by newlines and must end with a newline. Each realm is declared with a PATH and the REALM name, space seperated, followed by usernames and passwords, in pairs which are seperated by a space. If multiple hostnames require authentication, a HOSTNAME (no spaces) can be provided in the beginning of the PATH/REALM/username/password list to denote which host those realms should apply to. A special HOSTNAME can be used to denote a default set of realms, if there are no matches to any other HOSTNAMEs, the default is used. If only one set of realms are required (no multiple hostnames), the HOSTNAME field can be left out.

The fields in the authentication file has these restrictions:

HOSTNAME - cannot contain any spaces, must be either default or 
           a qualified hostname that is passed to the webserver via the
           Host: field. The HOSTNAME can also contain a ':' followed
           by a port number. If the port number is excluded, and a port number
           is included in the Host: field, then all ports will be mapped.
PATH     - must start with AND end with a/, cannot contain any spaces,
           if the PATH contains escape characters (for example: a space), it
           must be escaped using a % and a 2 digit hex value representing
           the ASCII character. Characters that will need to be escaped are as
           follows: spaces and everything EXCEPT letters, numbers, the '*', '-',
           '.', '@', '_', and '/'. Spaces MUST be encoded as %32.
REALM    - The realm name can by any alphanumeric string and can include spaces,
           commas, periods, colons, semicolons, exclaimation points, and dashes.
username - This is an alphanumeric string that CANNOT include spaces or punctuation.
password - This is a string that can contain all letters, numbers, punctuation, and
           spaces.
   

The general format of the authentication file is as follows:

HOSTNAME0
PATH0 REALM0
username0 password0
username1 password1
username2 password2
username3 password3
PATH1 REALM1
username0 password0
username1 password1

HOSTNAME1
PATH2 REALM2
username0 password0
username1 password1
PATH3 REALM3
username0 password0

etc...
        

Examples:

Here we have an example of a webserver serving a single domain

default
/protected/ Protected Realm
foo bar
/images/protected%32images/ Protected Image Realm
foo bar
   

So here the URI '/protected/sensitive_stuff' will fall under the Protected Realm, and a username/password of foo/bar will authenticate with this realm. The URI '/images/mypicture.gif' does not fall under a realm and will not need authentication, however; the URI '/images/protected images/private_picture.gif' does fall under the Protected Image Realm and will require the foo/bar password. Note the space in the directory 'protected images', and how it is required that the PATH be listed as 'protected%32images' in the authentication file.

In this example, we have a webserver that serves 2 domains as well as an HTTPS service. Since the HTTPS runs on a different port, special attention is given to the port numbers in the PATH field of the authentication file.

host.domain1.org:80
/protected/ Protected Realm
abc 123
xyz 321

host.domain1.org:443
/protected/ Protected HTTPS Realm
abc 789

host.domain2.org
/protected/ Domain2 Protected Realm
foo bar
   

The domain 'host.domain1.org' has been split into 2 seprated HOSTNAME entries: one for the HTTP requests (port 80) and one for the HTTPS requests (port 443). Given the URL 'http://host.domain1.org/protected/data.txt' a username/password of abc/123 or xyz/321 must be given to be authenticated. Given the URL 'https://host.domain1.org/protected/secure_data.txt', the username/password abc/789 must be used because it is being accessed through port 443 (https). However, the second domain, host.domain2.org, doesn't have a port listed. Therefore, the 2 URLs 'http://host.domain2.org/protected/data.txt' AND 'https://host.domain2.org/protected/secure.txt' may use the same username/password to be authenticated.

Field Summary

protected static java.lang.String	DEFAULT_HOME
protected java.util.Hashtable	hosts

Fields inherited from class com.cometway.ak.Agent

agent_id, agentController, CREATING_STATE, debugReporter, DESTROYED_STATE, DESTROYING_STATE, errorReporter, FAILED_STATE, printlnReporter, props, RUNNING_STATE, STARTING_STATE, STOPPED_STATE, STOPPING_STATE, warningReporter

Constructor Summary

HTTPAuthenticationAgent()

Method Summary

boolean	authenticate(Props request) Authenticates HTTP request.
boolean	authenticateUser(java.lang.String realm, java.lang.String username, java.lang.String password) This is a temporary workaround to provide an alternate authentication method to subclasses.
java.lang.String	getUsername(Props request) Pass in the Props of an HTTPAgentRequest, get the username that was used to HTTP authenticate this request.
boolean	handleRequest(HTTPAgentRequest request) This method is used only when the client is not authorized.
void	initProps() Initializes properties for this agent: "service_name" is the name this agent uses to register with Service Manager (default: http_authentication.agent), "authentication_file" is the location of the file to authenticate requests with (default: ./http.authentication).
boolean	isAuthenticated(java.lang.String path, java.lang.String hostname) Tests to see if path is Authenticated.
void	readAuthenticationFile(java.lang.String filename) Reads Authentication file, stores file in buffer, and prints Head Node of Authentication hash table.
void	start() This method inherited from com.cometway.ak.ServiceAgent includes functionality to register itself with the WebServer (temporary).
void	stop() Unregisters this instance with the service manager using the service_name property.

Methods inherited from class com.cometway.ak.Agent

currentStateEquals, debug, destroy, error, error, getAgentController, getDateTimeStr, getProps, getServiceImpl, getStateMachineModel, println, register, registerService, setAgentController, setProps, toString, unregister, unregisterService, warning, warning

Methods inherited from class com.cometway.props.Props

addListener, append, copy, copyFrom, copyTo, decrementInteger, dump, enableListeners, enumerateKeys, format, getBoolean, getByteArray, getCharacter, getDate, getDate, getDateString, getDouble, getFloat, getHexString, getInteger, getKeys, getLong, getNextKey, getProperty, getProperty, getPropsContainer, getSize, getString, getString, getTokens, getTokens, getTrimmedString, getVector, hasProperty, incrementInteger, insertProps, loadProps, notifyPropsChanged, notifyPropsChangedIgnore, notifyPropsChangedIgnore, parse, propertyMatchesRegEx, readFromFile, regExPropertyMatches, removeAll, removeListener, removeProperty, resumeNotify, saveProps, set, setBoolean, setCharacter, setDefault, setDouble, setFloat, setInteger, setLong, setProperty, setProperty, setProperty, setPropsContainer, suspendNotify, writeToFile

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

DEFAULT_HOME

protected static final java.lang.String DEFAULT_HOME

See Also:

Constant Field Values

hosts

protected java.util.Hashtable hosts

Constructor Detail

HTTPAuthenticationAgent

public HTTPAuthenticationAgent()

Method Detail

initProps

public void initProps()

Initializes properties for this agent: "service_name" is the name this agent uses to register with Service Manager (default: http_authentication.agent), "authentication_file" is the location of the file to authenticate requests with (default: ./http.authentication).

Specified by:

initProps in interface AgentInterface

Overrides:

initProps in class Agent

start

public void start()

Description copied from class: WebServerExtension

This method inherited from com.cometway.ak.ServiceAgent includes functionality to register itself with the WebServer (temporary).

Specified by:

start in interface AgentInterface

Overrides:

start in class WebServerExtension

stop

public void stop()

Description copied from class: ServiceAgent

Unregisters this instance with the service manager using the service_name property.

Specified by:

stop in interface AgentInterface

Overrides:

stop in class ServiceAgent

readAuthenticationFile

public void readAuthenticationFile(java.lang.String filename)

Reads Authentication file, stores file in buffer, and prints Head Node of Authentication hash table.

isAuthenticated

public boolean isAuthenticated(java.lang.String path,
                               java.lang.String hostname)

Tests to see if path is Authenticated.

authenticateUser

public boolean authenticateUser(java.lang.String realm,
                                java.lang.String username,
                                java.lang.String password)

This is a temporary workaround to provide an alternate authentication method to subclasses.

authenticate

public boolean authenticate(Props request)

Authenticates HTTP request.

getUsername

public java.lang.String getUsername(Props request)

Pass in the Props of an HTTPAgentRequest, get the username that was used to HTTP authenticate this request. null if no username was used to authenticate. NOTE: This method does not check if the username/password is actually valid for the given path.

handleRequest

public boolean handleRequest(HTTPAgentRequest request)

This method is used only when the client is not authorized.

Overrides:

handleRequest in class WebServerExtension