The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache-AppSamurai-1.01
River stage zero No dependents
++
/ Apache::AppSamurai::AuthBasic

NAME

Apache::AppSamurai::AuthBasic - Check credentials against backend web server using HTTP basic auth

SYNOPSIS

The module is selected and configured inside the Apache configuration.

 # Example with an authname of "fred" for use as part of an Apache config.

 # Configure as an authentication method
 PerlSetVar fredAuthMethods "AuthBasic"

 # The URL to send basic authentication checks to
 PerlSetVar fredAuthBasicLoginUrl "https://someserver/somepath/"

 # Use the special "HEADER:<field>" to pass the named header field from
 # the client to the backend authenticator directly. (Optional)
 PerlSetVar fredAuthBasicUserAgent "header:User-Agent"
 
 # Abort the check unless the "realm" returned by the server matches
 # this string. (Optional)
 PerlSetVar fredAuthBasicRequireRealm "Fred World Login"

 # Continue to send the same Authorization: header to the backend server
 # after login.  (Only use this when the AuthBasic check is run against
 # the backend server you are protecting)
 PerlSetVar fredAuthBasicKeepAuth 1

 # Collect cookies from AuthBasic check and send back to the user's browser
 # on login  (This is the default behaviour)
 PerlSetVar fredAuthBasicPassBackCookies 1

DESCRIPTION

This Apache::AppSamurai authentication module checks a username and password against a backend webserver, (referred to as the "auth server" below), using HTTP basic authentication (as defined in RFC 2617). In general, the auth server is the same as the server Apache::AppSamurai is protecting, though it does not have to be.

It is not recommended that you use AuthBasic as the only authentication method for an Apache::AppSamurai instance! There are various types of failures that could result in an erroneous login success. There are also inherent weaknesses in the HTTP basic auth system.

USAGE

The basic Apache::AppSamurai::AuthBase configuration options are supported. Additional options are described below. The following must be preceeded by the auth name and the auth module name, AuthBasic. For example, if you wish to set the LoginUrl value for the auth name "Jerry", you would use:

 PerlSetVar JerryAuthBasicLoginUrl "url"

The auth name and "AuthBasic" have been removed for clarity. See Apache::AppSamurai for more general configuration information, or the examples/conf/ directory in the Apache::AppSamurai distribution for examples.

LoginUrl URL

(Default: None. You must set this value.) Set to the full URL, (protocol, FQDN, and path), to authenticate against. This URL must return a 401 Authorization Required response and a WWW-Authenticate header with Basic listed as a supported type. HTTPS is highly recommended.

UserAgent AGENT

(Default: undef) Sets the user agent that will be reported to the auth server. This is optional. You may set either a static agent name, like "Mozilla/10.0 (Donkey Team Approved)", or use the special header:HEADERNAME syntax, where HEADERNAME is the name of a client request header to copy.

In most cases, you should be able to configure UserAgent as "header:User-Agent", which will just pass the client's field right through to the auth server.

RequireRealm NAME

(Default: undef) Require the auth server to return a specific basic auth "realm". (This is the value set by "realm=" inside the WWW-Authorization server header. This is also what shows across the top of the popup basic authentication login box if you go directly to the login URL.

KeepAuth 0|1

(Default: 0) If 1, saves the basic authentication header that is sent to the auth server by AuthBasic and continue to send the same header to the proxied server after login. This is almost always used when protecting a single basic auth backend webserver.

Cross Server Warning: When KeepAuth is enabled, all the backend servers or apps protected by the specific auth name will receive the authorization header. Do not enable this feature unless you are certain all the servers and applications being protected by this Apache::AppSapurai instance should be receiving users' usernames and passwords!

Session Storage Warning: By default Apache::AppSamurai uses AES (Rijndael) to encrypt session data before storing it to disk, greatly reducing the risk of keeping the basic auth header, If you use this feature, please leave the Apache::AppSamurai::Session::Serialize::CryptBase64 module configured as the session serialization module.

PassBackCookies 0|1

(Default: 0) If 1, collects set cookies from the auth server and, upon successful login, set them in the client web browser.

Even when using basic auth, many apps set cookies for various reasons. This feature is most useful then the auth server and the protected backend webserver are the same. It may also be useful in the case of using a ticket issuer of some sort as the auth server.

Cross Server Warning: This feature does not alter the domain or path of the cookie. It also does not filter the cookie domain or path, nor does it translate cookies in subsequent requests. For new applications, examine the cookie being set in the browser and ensure that it should be sent to the protected servers and applications for this Apache::AppSamurai instance.

Session Storage Warning: This feature temporarily stores the cookie in the session data store on the Apache::AppSamurai proxy server. By default Apache::AppSamurai uses AES (Rijndael) to encrypt session data before storing it to disk, greatly reducing the risk of keeping the cookie. If you use this feature, please leave the Apache::AppSamurai::Session::Serialize::CryptBase64 module configured as the session serialization module.

AllowRedirect 0|1

(Default: 0) If set to 1, allows the auth server to replay with a 302 Redirect code, following the redirect to its eventual destination.

This feature should almost never be used! Instead, try to find the eventual URL destination the auth server is expecting. If you connect to the auth server's port, (using openssl s_client -connect "SERVERNAME:PORT" for SSL, or just telnet SERVERNAME PORT), and request the page, it should return a 401 code.

(The skill of being a human web browser is a useful one to have for web work. http://www.esqsoft.com/examples/troubleshooting-http-using-telnet.htm gives a very quick look at how to do it. After that, check out http://en.wikipedia.org/wiki/HTTP or the HTTP RFCs for more info.)

SuccessCode CODE

(Default: 200) This is the numerical HTTP response code the auth module should expect from the auth server if the login was a success. 200 is usually correct.

Verifying this code is highly recommended! Some servers and apps return a 200 on various failures. (In part, thanks to Internet Explorer's "helpful" error handling feature that displays its usual generic "Uh, something happened!" error message on code 500 and other errors that return a page under a certain length.)

Timeout SECONDS

(Default: 10) The number of seconds to wait for the auth server to respond.

PassChars REGEX-CHARS

(Default: \w\d !\@\#\$\%\^\&\*,\.\?\-_=\+) This is actually a configuration item included in Apache::AppSamurai::AuthBase. It is mentioned here because the AuthBasic version overrides the usual default by removing the : character. (: is used to split the username and password inside the Base64 encoded authorization header.)

OTHERS

All other configuration items are inherited from Apache::AppSamurai::AuthBase. Consult its documentation for more information.

METHODS

Configure()

Other than the AuthBasic specific configuration options, (described in "USAGE"), this is just a wrapper for the AuthBase Configure().

Initialize()

Performs the following additional actions:

  • Creates %{$self->{alterlist}} to hold header and cookie alterlist rules. (See Apache::AppSamurai for alterlist information.)

  • Creates a LWP::UserAgent instance and saves it in $self->{client}.

  • Creates a HTTP::Request instance, containing the auth server URL, and saves it in $self->{request}.

  • If UserAgent is set, collects (if header: is used), then sets the User-Agent header in the request.

Authenticator()

Performs the following actions, logging error(s) and returning 0 if any actions fail:

  • Makes an initial connection to the auth server URL and checks for a 401 Authorization Required response code.

  • Checks that Basic is listed as a supported type.

  • If RequireRealm is configured, the realm returned by the auth server is checked against the RequireRealm value.

  • A second request is sent, this time with the username and password (credential) included.

  • The return code is checked against SuccessCode

  • If PassBackCookies is 1, the cookies set by the auth server are saved in the alterlist cookie hash with "passback" rules.

  • If KeepAuth is 1, the authorization header (containing the username and password) are saved in the alterlist header hash with an "add" rule.

  • If all checks have succeeded, 1 is returned.

EXAMPLES

See "SYNOPSIS" for a basic example, or configuration examples in examples/conf/ inside the Apache::AppSamurai distribution.

SEE ALSO

Apache::AppSamurai, Apache::AppSamurai::AuthBase, LWP::UserAgent, HTTP::Request

AUTHOR

Paul M. Hirsch, <paul at voltagenoir.org>

BUGS

See Apache::AppSamurai for information on bug submission and tracking.

SUPPORT

See Apache::AppSamurai for support information.

COPYRIGHT & LICENSE

Copyright 2008 Paul M. Hirsch, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.