view release on metacpan or  search on metacpan

lib/Apache/AppSamurai/AuthBasic.pm  view on Meta::CPAN

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


=head1 DESCRIPTION

This L<Apache::AppSamurai|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
L<RFC 2617|http://www.faqs.org/rfcs/rfc2617.html>).  In general, the
auth server is the same as the server Apache::AppSamurai is protecting,
though it does not have to be.

B<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.

=head1 USAGE

The basic L<Apache::AppSamurai::AuthBase|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, I<AuthBasic>.  For example, if you wish to set the
C<LoginUrl> value for the auth name "Jerry", you would use:

 PerlSetVar JerryAuthBasicLoginUrl "url"

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

=head2 I<LoginUrl> C<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 C<401 Authorization Required> response and a
C<WWW-Authenticate> header with C<Basic> listed as a supported type.
HTTPS is highly recommended.

=head2 I<UserAgent> C<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 C<header:HEADERNAME>
syntax, where C<HEADERNAME> is the name of a client request header to copy.

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

=head2 I<RequireRealm> C<NAME>

(Default: undef)
Require the auth server to return a specific basic auth "realm".  (This
is the value set by "realm=" inside the C<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.

=head2 I<KeepAuth> C<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.

B<Cross Server Warning:>
When I<KeepAuth> is enabled, B<all> the backend servers or apps protected
by the specific auth name will receive the authorization header.  B<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!>

B<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
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64> module configured as the session serialization
module.

=head2 I<PassBackCookies> C<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.  

B<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.

B<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
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64> module configured as the session serialization
module.

=head2 I<AllowRedirect> C<0|1>

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

B<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 C<openssl s_client -connect "SERVERNAME:PORT">
for SSL, or just C<telnet SERVERNAME PORT>), and request the page, it should
return a 401 code.