Apache-AuthCookie

 view release on metacpan or  search on metacpan

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

This method returns a modified version of the destination parameter
before embedding it into the response header. Per default it escapes
CR, LF and TAB characters of the uri to avoid certain types of
security attacks. You can override it to more limit the allowed
destinations, e.g., only allow relative uris, only special hosts or
only limited set of characters.

=head2 logout($r)

This is simply a convenience method that unsets the session key for
you.  You can call it in your logout scripts.  Usually this looks like
C<$r-E<gt>auth_type-E<gt>logout($r);>.

=head2 authenticate($r)

This method is one you'll use in a server config file (httpd.conf,
.htaccess, ...) as a PerlAuthenHandler.  If the user provided a
session key in a cookie, the C<authen_ses_key()> method will get
called to check whether the key is valid.  If not, or if there is no
key provided, we redirect to the login form.

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

access failed when a cookie is present, your C<authen_ses_key()>
method can set arbitrary entries in C<$r-E<gt>subprocess_env>.

=head1 THE LOGOUT SCRIPT

If you want to let users log themselves out (something that can't be
done using Basic Auth), you need to create a logout script.  For an
example, see t/htdocs/docs/logout.pl.  Logout scripts may want to take
advantage of AuthCookie's C<logout()> method, which will set the
proper cookie headers in order to clear the user's cookie.  This
usually looks like C<$r-E<gt>auth_type-E<gt>logout($r);>.

Note that if you don't necessarily trust your users, you can't count
on cookie deletion for logging out.  You'll have to expire some
server-side login information too.  AuthCookie doesn't do this for
you, you have to handle it yourself.

=head1 ENCODING AND CHARACTER SETS

=head2 Encoding

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

Unlike the sample AuthCookieHandler, you have you verify the user's
login and password in C<authen_cred()>, then you do something
like:

    my $date = localtime;
    my $ses_key = MD5->hexhash(join(';', $date, $PID, $PAC));

save C<$ses_key> along with the user's login, and return C<$ses_key>.

Now C<authen_ses_key()> looks up the C<$ses_key> passed to it and
returns the saved login.  I use Oracle to store the session key and
retrieve it later, see the ToDo section below for some other ideas.

=head2 TO DO

=over 4

=item *

It might be nice if the logout method could accept some parameters

lib/Apache/AuthCookie/Util.pm  view on Meta::CPAN

             or $ua =~ qr{\bIEMobile/10};            # Nokia Lumia 920, possibly others?

    return 1;
}

# return true if the given value is blank or not defined.
sub is_blank {
    return defined $_[0] && ($_[0] =~ /\S/) ? 0 : 1;
}

# returns true if the given value looks like a local destination
sub is_local_destination {
    my ($destination, $current_uri) = @_;

    # blank location is not considered "local"
    return 0 if is_blank($destination);

    # If the location does not start with a scheme or is not protocol relative,
    # then the location is local.
    # Scheme is defined in RFC 3986 as:
    #   ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )

lib/Apache2/AuthCookie.pm  view on Meta::CPAN

Of course, if you want to give more specific information about why
access failed when a cookie is present, your C<authen_ses_key()>
method can set arbitrary entries in C<$r-E<gt>subprocess_env>.

=head1 THE LOGOUT SCRIPT

If you want to let users log themselves out (something that can't be
done using Basic Auth), you need to create a logout script.  For an example,
see t/htdocs/docs/logout.pl.  Logout scripts may want to take advantage of
AuthCookie's C<logout()> method, which will set the proper cookie headers in
order to clear the user's cookie.  This usually looks like
C<$r-E<gt>auth_type-E<gt>logout($r);>.

Note that if you don't necessarily trust your users, you can't count
on cookie deletion for logging out.  You'll have to expire some
server-side login information too.  AuthCookie doesn't do this for
you, you have to handle it yourself.

=head1 ABOUT SESSION KEYS

Unlike the sample AuthCookieHandler, you have you verify the user's
login and password in C<authen_cred()>, then you do something
like:

    my $date = localtime;
    my $ses_key = MD5->hexhash(join(';', $date, $PID, $PAC));

save C<$ses_key> along with the user's login, and return C<$ses_key>.

Now C<authen_ses_key()> looks up the C<$ses_key> passed to it and
returns the saved login.  I use Oracle to store the session key and
retrieve it later, see the ToDo section below for some other ideas.

=head2 TO DO

=over 4

=item *

It might be nice if the logout method could accept some parameters

lib/Apache2/AuthCookie/Base.pm  view on Meta::CPAN

some known browsers which ignore HTML content for HTTP_FORBIDDEN responses
(e.g.: SymbianOS).  You can override this method to return custom codes.

Note that HTTP_FORBIDDEN is the most correct code to return as the given
request was not authorized to view the requested page.  You should only change
this if HTTP_FORBIDDEN does not work.

=head2 logout($r): void

This is simply a convenience method that unsets the session key for you.  You
can call it in your logout scripts.  Usually this looks like
C<$r-E<gt>auth_type-E<gt>logout($r)>.

=head2 params($r): Apache2::AuthCookie::Params

Get the GET/POST params object for this request.

=head2 recognize_user($r): int

If the user has provided a valid session key but the document isn't protected,
this method will set C<$r-E<gt>user> anyway.  Use it as a PerlFixupHandler,

lib/Apache2_4/AuthCookie.pm  view on Meta::CPAN

Of course, if you want to give more specific information about why access
failed when a cookie is present, your C<authen_ses_key()> method can set
arbitrary entries in C<$r-E<gt>subprocess_env>.

=head1 THE LOGOUT SCRIPT

If you want to let users log themselves out (something that can't be done using
Basic Auth), you need to create a logout script.  For an example, see
t/htdocs/docs/logout.pl.  Logout scripts may want to take advantage of
AuthCookie's C<logout()> method, which will set the proper cookie headers in
order to clear the user's cookie.  This usually looks like
C<$r-E<gt>auth_type-E<gt>logout($r);>.

Note that if you don't necessarily trust your users, you can't count on cookie
deletion for logging out.  You'll have to expire some server-side login
information too.  AuthCookie doesn't do this for you, you have to handle it
yourself.

=head1 ABOUT SESSION KEYS

Unlike the sample AuthCookieHandler, you have you verify the user's login and
password in C<authen_cred()>, then you do something like:

    my $date = localtime;
    my $ses_key = Digest::SHA::sha256_hex(join(';', $date, $PID, $PAC));

save C<$ses_key> along with the user's login, and return C<$ses_key>.

Now C<authen_ses_key()> looks up the C<$ses_key> passed to it and returns the
saved login.  I use a database to store the session key and retrieve it later.

=head1 FREQUENTLY ASKED QUESTIONS

=over 4

=item *

I upgraded to Apache 2.4 and now AuthCookie doesn't work!