NAME

Bio::Das::ProServer::Authenticator::http - authenticates DAS requests by issuing requests to a remote authority

VERSION

$LastChangedRevision: 558 $

SYNOPSIS

To authenticate a request:

my $auth = Bio::Das::ProServer::Authenticator::http->new({
  'config' => {
               'authurl'     => 'http://my.example.com/is_root?query=%token',
              },
});

my $allow = $auth->authenticate({
  'peer_addr' => $, # packed
  'request'   => $, # HTTP::Request object
  'cgi'       => $, # CGI object
  ...
});

DESCRIPTION

Authenticates DAS requests by connecting to a remote authentication HTTP server. An authentication token is parsed from the DAS request. By default this should be in an 'Authorization' header, but the authenticator can be configured to look in a cookie, CGI parameter or a header with a different name.

The authentication token is referred to a remote server to ask a yes/no question (e.g. "Is this user in a certain group of users?"). The server, for which the URL is configurable, should return a status code of either 200 (OK) or a denial response that will be forwarded to the client. For example if the remote wishes to deny the request, it could respond with a status code of 403, textual content for explanation and any necessary custom headers.

Authentication results are cached for 30 minutes in order to minimise the number of requests issued to the remote server. Internal Server Error responses (code 500) are not cached.

This module may be easily overridden to parse the authentication token in different ways.

SUBROUTINES/METHODS

authenticate : Applies authentication to a request.

Requires: a hash reference containing details of the DAS request
Returns:  either nothing (allow) or a HTTP::Response (deny)

my $allow = $oAuth->authenticate({
  'peer_addr' => $, # packed
  'request'   => $, # HTTP::Request object
  'cgi'       => $, # CGI object
  ...
});

The method follows this procedure:
1. Parse an authentication token from the DAS request (parse_token method).
2. Check for cached results for this token.
3. If not found, query the remote server.
4. Store the response in the cache, unless it is a server error (500)
4. If the response code is 200 allow the request, otherwise deny.

parse_token : Parses the DAS request to extract an authentication token

Requires: a hash reference containing details of the DAS request
Returns:  a string authentication token

my $token = $oAuth->parse_token({
  'peer_addr' => $, # packed
  'request'   => $, # HTTP::Request object
  'cgi'       => $, # CGI object
  ...
});

Depending on configuration, the authentication token is extracted from:
1. a named cookie
2. a named CGI parameter
3. a named request header
4. the 'Authorization' request header (default)

This method may be overridden to extract the token in a different manner.

DIAGNOSTICS

my $auth = Bio::Das::ProServer::Authenticator::http->new({
  ...
  'debug'  => 1,
});

CONFIGURATION AND ENVIRONMENT

The URL to use for remote authentication is configured in the source INI section. Any instances of "%token" will be replaced by the value of the authentication token parsed from the DAS request.

[mysource]
authenticator = http
authurl       = http://auth.example.com/is_allowed?query=%token
; Optionally define location of auth token (default is 'Authorization' header)
; authcookie    = cookiename
; authheader    = headername
; authparam     = cgiparamname

An HTTP proxy may be specified in the shell environment.

DEPENDENCIES

Carp

Bio::Das::ProServer::Authenticator

LWP::UserAgent

BUGS AND LIMITATIONS

This authenticator implementation may only be used to ask yes/no questions, such as "does this token identify a user with sufficient privileges?". Questions such as "which user does this token identify?" have additional security implications and are therefore not supported.

INCOMPATIBILITIES

None reported.

AUTHOR

Andy Jenkinson <andy.jenkinson@ebi.ac.uk>

LICENSE AND COPYRIGHT

Copyright (c) 2008 EMBL-EBI

cpanm Bio::Das::ProServer

perl -MCPAN -e shell
install Bio::Das::ProServer