view release on metacpan or  search on metacpan

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

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.

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

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

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

=head2 I<Timeout> C<SECONDS>

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

=head2 I<PassChars> C<REGEX-CHARS>

(Default: C<< \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 C<:> character.  (C<:> is used to split the username
and password inside the Base64 encoded authorization header.)

=head2 OTHERS

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

=head1 METHODS

=head2 Configure()

Other than the AuthBasic specific configuration options, (described in
L</USAGE>), this is just a wrapper for the AuthBase C<Configure()>.

=head2 Initialize()

Performs the following additional actions:

=over 4

=item *

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

=item *