view release on metacpan or  search on metacpan

AuthCookieURL.pm  view on Meta::CPAN

    # Disable cookies (only URL based sessions)
    #PerlSetVar WhateverNoCookie 1

    # Define a string that indicates to AuthCookieURL
    # what a session looks like
    # This can only be in main config
    #PerlSetVar SessionPrefix Session-


    # This block enables URL session handling
    PerlTransHandler  Apache::AuthCookieURLHandler->URLsession

    ErrorDocument 302 /MISSING
    ErrorDocument 301 /MISSING
    <Location /MISSING>
        SetHandler perl-script
        PerlHandler Apache::AuthCookieURLHandler->error_document
    </Location>



    <Location /protected>
        AuthType Apache::AuthCookieURLHandler
        AuthName Whatever
        PerlAuthenHandler Apache::AuthCookieURLHandler->authenticate
        PerlAuthzHandler Apache::AuthCookieURLHandler->authorize
        require valid-user
    </Location>


    # provide open access to some areas below
    <Location /protected/open>
        PerlSetVar DisableAuthCookieURL 1
    </Location>

    # or if the entire directory tree was protected
    <Location /images>
        PerlSetVar DisableAuthCookieURL 1
    </Location>


    # Make sure the login script can be run
    <Files login.pl>
         Options +ExecCGI
         SetHandler perl-script
         PerlHandler Apache::Registry
    </Files>

    # LOGIN is the action defined by the login.pl script

    <Files LOGIN>
         AuthType Apache::AuthCookieURLHandler
         AuthName Whatever
         SetHandler perl-script
         PerlHandler Apache::AuthCookieURLHandler->login
    </Files>

    # Note: If protecting the entire web site (from root down) then
    # the action *must* be C</LOGIN> as the module looks for this string.

    # better to just invalidate the session, of course
    <Files LOGOUT>
         AuthType Apache::AuthCookieURLHandler
         PerlSetVar WhateverLogoutURI /
         AuthName Whatever
         SetHandler perl-script
         PerlHandler Apache::AuthCookieURLHandler->logout
    </Files>

=head1 DESCRIPTION

** Warning: beta software.  This should be used for testing purposes only.
That said, there are a few people using it and I've been using it for a
few months without problem.  The interface may change (or disappear) without notice.
Please report any problems or comments back to Bill Moseley E<lt>moseley@hank.orgE<gt>.

This module is a modification of Ken Williams E<lt>ken@forum.swarthmore.eduE<gt> Apache::AuthCookie.
Please see perldoc Apache::AuthCookie for complete instructions.  As this is intended to be
a drop-in replacement for Apache::AuthCookie you may wish to install and test with Ken's
Apache::AuthCookie before trying AuthCookieURL.

Basically, this module allows you to catch any unauthenticated access and redirect to a
login script that you define.  The login script posts credentials (e.g. username and password)
and your module can then validate and provide a session key.  The session key is sent in a cookie,
and also in a munged URL and a redirect is issued and the process starts all over.

Typically, you will write your own module that will override methods in Apache::AuthCookieURL.
These methods are described completely in Ken's Apache::AuthCookie.  Your methods will be used
to generate and validate session keys.  You can use Apache::AuthCookieURL without overriding
its methods and then AuthCookieURL can be used as a simple session manager.

With this module you should be able to enable session management for an entire site
using E<lt>Location /E<gt>, and then allow access to, say, the images directory, and also require
password access to other locations.  One issue at this point is that the session key is
stripped from URLs in a Trans handler.  So you would need to use cookies to use different
session keys for different parts of your web tree.

Apache::AuthCookieURL adds the following features to Apache::AuthCookie.

=over 4

=item * URL munging

If the PerlTransHandler is enabled in httpd.conf the session key will also be placed in the URL.
The session will be removed from the URL if cookies are enabled
on the next request.  Typically, someone visiting your site with cookies enabled
will never see the munged URL.

To make URL sessions work you must use relative links in your documents so the client/browser
knows to place the session key on all links.  CGI scripts can also access the session
information via the environment.

=item * Simple Session Management

If the login script is set to `NONE' with PerlSetVar WhateverLoginScript NONE then
Apache::AuthCookeURL acts like a simple session manager:  your module will provide a new
session key if one is not provided with the request, or if the one provided is invalid.

=item * Really Simple Session Management

Apache::AuthCookieURL provides default authen_cred() and authen_ses_key() methods that
generates a (questionably) random session key.  This means you can use AuthCookieURL
directly without subclassing for really simple session management without any persistence of
session keys.

=back


Unless you are not subclassing this module (and using the default methods provide),
your own module must define two methods: authen_cred() and authen_ses_key(), and then
subclass by including Apache::AuthCookieURL in your module's @ISA array.
Again, please see Apache::AuthCookie for
complete documentation.

=over 4

=item * authen_cred()

This method verifies the credentials (e.g. username/password) and returns a session key.  If the credentials are
not acceptable then you can return a list, with the second element being an error message
that is placed in a cookie.  This allows your login script to display a failure reason.  This
method is needed since a redirect is done before your login script is executed again.  Of course,
this requires that the client has cookies enabled.

Another method is to return a session key that is really an error code and generate
messages based on that returned session (error) code.

=item * authen_ses_key()

This method's job is to validate and convert a session key into a username and return it.
AuthCookieURL places the returned value into $ENV{REMOTE_USER}.

=back

=head1 CONFIGURATION SETTINGS

Configuration settings are set with the PerlSetVar directive:

    PerlSetVar WhateverExpires +90d

"Whatever" is whatever the current AuthName is set.  I think I might remove this
and instead just use the settings as Apache dir_merge returns them.  In other words,
if you want a setting to override a global setting, then use it within a E<lt>directoryE<gt>,
E<lt>fileE<gt>, or E<lt>locationE<gt> section.

=over 4

=item * AuthCookieURLDebug

Sets the debugging level.  Since some debugging info is generated in the Trans
handler this needs to be set in the main httpd config.  Default is 0.

Example: PerlSetVar AuthCookieURLDebug 5

=item * SessionPrefix

SessionPrefix sets the prefix used by the Trans handler to recognize the session
in the URL (thus needs to be set in the main config), and to create the session ID.
Default is 'Session-'.

Example: PerlSetVar SessionPrefix ID-

=item * WhateverCache

UNLESS set then $r-E<gt>no_cache(1) will be called when processing the login and logout requests.
Defaults to unset and thus $r-E<gt>no_cache(1) IS called.

Example: PerlSetVar WhateverCache 1

=item * WhateverLogoutURI

Sets where you are redirected after requesting the logout URL (see SYNOPSIS).
Defaults to '/'.  

Example: PerlSetVar WhateverLogoutURI /gone.html

=item * DisableAuthCookieURL

This causes the Authen and Authz handlers to return OK.  In other words,

    <Location /protected/notprotected>
        PerlSetVar DisableAuthCookieURL 1
    </Location>

Allows full access to the notprotected directory.


=item * WhateverLoginScript

This sets the Login script to be executed when authorization is