| 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.
The set of valid Session IDs is contained either in (1) a static file or
in (2) a globally accessible table managed by the SessionManager.
The second case allows the list of Session IDs to be dynamically
configurable and shareable amongst two or more authentication handlers.
For instance, the web developer could set up one handler to dynamically
populate the shared table with Session IDs based on submitted HTML forms,
and then use the BasicAuthHandler to ensure that all other
requests have a valid Session ID based on the shared table. See
mapFile,
session,
ident
The format of the static file described in case (1) 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 format of the dynamic table described in case (2) above is a
Hashtable where the keys are the Base64 encoded strings
obtained from the Authentication header and the values are the associated
Session IDs. This Hashtable is accessed via the
SessionManager.getSession method, with the session
argument of null and the ident argument
specified by a configuration parameter.
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
- This handler will attempt to authenticate URLs beginning with
this string only. The default value is "/".
-
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 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 to get the table of valid sessions. The default value is
"authorized".
author:
Stephen Uhler (stephen.uhler@sun.com)
author:
Colin Stevens (colin.stevens@sun.com)
version:
1.27, 01/01/12 |
