view release on metacpan or  search on metacpan

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

=item *

B<Modular authentication> - Uses authentication sub-modules for the easy
addition custom authentication methods

=item *

B<Form based or Basic Auth login> - On the front end, supports standard
form based logins, or optionally Basic Auth login.  (For use with automated
systems that can not process a form.)

=item *

B<Apache::Session> - Used for session data handling

=item *

B<Session data encrypted on server> - By default, all session
data encrypted before storing to proxy's filesystem  (Uses custom
B<Apache::Session> compatible session generator and session serialization
modules)

=item *

B<Unified mod_perl 1 and 2 support> - One module set supports both
Apache 1.x/mod_perl 1.x and Apache 2.x/mod_perl 2.x

=back

=head1 SESSION STORAGE SECURITY

Server side session data may include sensitive information, including the basic
authentication C<Authorization> header to be sent to the backend server.
(This is just a Base64 encoded value, revealing the username and password
if stolen.)

To protect the data on-disk, Apache::AppSamurai includes
its own HMAC based session ID generator and encrypting session serializer.
(L<Apache::AppSamurai::Session::Generate::HMAC_SHA|Apache::AppSamurai::Session::Generate::HMAC_SHA>
and
L<Apache::AppSamurai::Session::Serialize::CryptBase64|Apache::AppSamurai::Session::Serialize::CryptBase64>
, respectively.)
These modules are configured by default and may be used directly with
Apache::Session, or outside of Apache::AppSamurai if desired.

=head1 USAGE

Almost all options are set using C<PerlSetVar> statements, and can be used
inside most configuration sections.

Each configuration option must be prefixed by the I<AuthName> for the
Apache::AppSamurai instance you wish to apply the option to.  This
I<AuthName> is then referenced within the protected area(s).   Most of setups
only require one I<AuthName>.  You can call it "BOB" or "MegaAuthProtection".
You can even call it "authname". 

B<IMPORTANT NOTE> - The I<AuthName> is omitted in the configuration
descriptions below for brevity.  "Example" is used as the I<AuthName> in the
L</EXAMPLES> section.

Most setups will include a set of global configuration values to setup the
Apache::AppSamurai instance.  Each protected area then points to a specific
AuthName and Apache::AppSamurai methods for authentication and
authorization.

=head2 GENERAL CONFIGURATION

=head3 I<Debug> C<0|1>

(Default: 0)
Set to 1 to send debugging output to the Apache logs.  (Note - you must have
a log configured to catch errors, including debug level errors, to see the
output.)

=head3 I<CookieName> C<NAME>

(Default:AUTHTYPE_AUTHNAME)
The name of the session cookie to send to the browser.

=head3 I<LoginScript> C<PATH>

(Default: undef)
The URL path (location) of the proxy's login page for form based login.
(Sample script provided with the Apache::AppSamurai distribution.)

=head3 I<Path> C<PATH>

(Default: /)
The URL path to protect.

=head3 I<Domain> C<DOMAIN>

(Default: not set)
The optional domain to set for all session cookies.  Do not configure this
unless you are sure you need it: A misconfigured domain can result in session
stealing.

=head3 I<Satisfy> C<All|Any>

(Default: All)
Set C<require> behaviour within protected areas.  Either C<All> to require all
authentication checks to succeed, or C<Any> to require only one to.

=head3 I<Secure> C<0|1>

(Default: 1)
Set to 1 to require the C<secure> flag to be set on the session cookie, forcing
the use of SSL/TLS.

=head3 I<HttpOnly> C<0|1>

(Default: 0)
Set to 1 to require the Microsoft proprietary C<http-only> flag to be set on
session cookies.

=head3 I<LoginDestination> C<PATH>

(Default: undef)
Set an optional hard coded destination URI path all users will be directed to
after login.  (While full URLs are allowed, a path starting in / is
recommended.)  This setting only applies so form based login.  Basic Auth

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

 <Directory "proxy:https://ex.amp.le/thaang/*">
 #*FOR MODPERL2 USE:
 #<Proxy "https://ex.amp.le/thaang/*">

  AuthType Basic
  AuthName "Example"
  PerlAuthenHandler Apache::AppSamurai->authenticate
  PerlAuthzHandler Apache::AppSamurai->authorize

  # Add some local overrides to this directory.  (Has
  # no affect on other directories/locations)

  # Switch from an inactivity timeout to a hard expiration
  PerlSetVar ExampleSessionExpire 3600
  PerlSetVar ExampleSessionTimeout 0

  # In lieu of cookies, calculate the session key using the
  # basic auth header from the client, and an argument called
  # "Sessionthing" from the request URL.  (NOTE - Keysource
  # should be used with care!  Do not use it unless you are
  # sure of what you are doing!!!)
  PerlAddVar ExampleKeysource header:Authorization
  PerlAddVar ExampleKeysource arg:Sessionthing

  Order deny,allow
  Allow from all
  require valid-user

 </Directory>
 #*FOR MODPERL2 USE:
 #</Proxy>


 # Do not allow forward proxying
 ProxyRequests Off
 
 # Proxy requests for /thing/* to  https://ex.amp.le/thing/*
 RewriteRule ^/thing/(.*)$ https://ex.amp.le/thing/$1 [P]

 # Similar for /thaang/*
 RewriteRule ^/thaang/(.*)$ https://ex.amp.le/thaang/$1 [P]

 # Redirect requests to / into our default app
 RewriteRule ^/?$ /thing/ [R,L]

 # Allow in AppSamurai requests to proxy server
 RewriteRule ^/AppSamurai -

 # Capture logout URL from app and send to a pseudo page mapped to logout() 
 RewriteRule ^/thing/logout\.asp$ /AppSamurai/LOGOUT

 # Block all other requests
 RewriteRule .* - [F]

 #*FOR MODPERL2 YOU MUST UNCOMMENT AND PUT THE FOLLOWING INSIDE
 # RELEVANT VirtualHost SECTIONS (For most Apache2 setups, this would be
 # the "<VirtualHost _default_:443>" section inside ssl.conf)
 #
 ## Enable rewrite engine inside virtualhost
 #RewriteEngine on
 ## Inherit rewrite settings from parent (global)
 #RewriteOptions inherit
 ## Enable proxy connections to SSL
 #SSLProxyEngine on


=head1 EXTENDING

Additional authentication modules, tracking features, and other options
can be added to Apache::AppSamurai.  In the case of authentication modules,
all that is required is creating a new module that inherits from
L<Apache::AppSamurai::AuthBase|Apache::AppSamurai::AuthBase>.

Other features may be more difficult to add.  (Apache::AppSamurai could
use some refactoring.)

Interface and utility methods are not documented at this time.  Please
consult the code, and also the L<Apache::AuthCookie|Apache::AuthCookie>
documentation.

=head1 FILES

=over 4

=item F<APPSAMURAI_CONTENT/>

Directory that holds Apache::AppSamurai login/logout pages and related
content.  This must be served by Apache and reachable.  (This is
generally mapped to B</AppSamurai/> on the server.)   When starting from
scratch, copy the contents of F</examples/htdocs/> from the Apache-AppSamurai
distribution into this directory.

=item F<APPSAMURAI_CONTENT/login.pl>

The default login mod_perl script.  Must be modified to match your setup.

=item F<APPSAMURAI_CONTENT/login.html>

The default HTML login form template.  (Split out from login.pl to ease
customization.)

=item F<APPSAMURAI_CONTENT/robots.txt>

Generic "deny all" robots file. (You don't want your login area appearing
on Google.  Note that the default login page also has a META tag to prevent
indexing.)

=item F<APPSAMURAI_CONTENT/images/>

Image files for login page.

=back

=head1 SEE ALSO

L<Apache::AppSamurai::Session>, L<Apache::AppSamurai::Tracker>,
L<Apache::AppSamurai::AuthBase>, L<Apache::AppSamurai::AuthBasic>,
L<Apache::AppSamurai::AuthRadius>, L<Apache::AppSamurai::AuthSimple>,
L<Apache::AppSamurai::Util>,L<Apache::AppSamurai::Session::Generate::HMAC_SHA>,
L<Apache::AppSamurai::Session::Serialize::CryptBase64>,
L<Apache::Session>