view release on metacpan or  search on metacpan

AuthCookieURL.pm  view on Meta::CPAN

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
required (no valid session key was sent by cookie or URL).  This login script can be a
CGI script, Apache::Registry script, or a mod_perl handler.

If set to `NONE' then AuthCookieURL will be in simple session management mode.
AuthCookieURL-E<gt>login will be called which calls authen_cred() to generate a session key.
authen_cred() should just return a session key without checking the credentials.

If you do not override AuthCookieURL::authen_cred(), then AuthCookieURL::authen_cred()
simply returns this for a session key.

    return time . $$ . int rand $$;

Example: PerlSetVar WhateverLoginScript /login.pl