view release on metacpan or  search on metacpan

lib/Apache2/Controller/Auth/OpenID.pm  view on Meta::CPAN

use version;
our $VERSION = version->new('1.001.001');

=head1 SYNOPSIS

 PerlLoadModule Apache2::Controller::Directives

 <Location /myapp>
     SetHandler modperl

     # uri to your login controller:
     A2C_Auth_OpenID_Login          login

     # uri to your logout controller:
     A2C_Auth_OpenID_Logout         logout

     # uri to your registration controller:
     A2C_Auth_OpenID_Register       register
     # you might want to put this outside the protected area, 
     # i.e. /other/register - you can use leading '/' for absolute uri

     # idle timeout in seconds, +2m, +3h, +4D, +6M, +7Y, or 'no timeout'
     # default is 1 hour.  a month is actually 30 days, a year 365.
     A2C_Auth_OpenID_Timeout        +1h

     # name of the openid table in database:
     A2C_Auth_OpenID_Table          openid
     
     # key of the username field in table:
     A2C_Auth_OpenID_User_Field     uname

     # key of the openid url field in table:
     A2C_Auth_OpenID_URL_Field      openid_url

     # if you use multiple DBI handles, name the one in pnotes
     # that you should use for reading the openid table:
     A2C_Auth_OpenID_DBI_Name       dbh

     # by default trust_root is the result of $r->construct_url(''),
     # i.e. the top of the site (see Apache::URI)
     A2C_Auth_OpenID_Trust_Root     http://myapp.tld/somewhere

     # set a random string used as salt with time() to sha secret
     A2C_Auth_OpenID_Consumer_Secret

     # but that random salt will be reset if you restart server,
     # which may cause current logins to die, so you can specify
     # your own constant salt of arbitrary length
     A2C_Auth_OpenID_Consumer_Secret    abcdefg1234567

     # if you do not want to preserve GET/POST params 
     # across redirects to the OpenID server, use this flag:
     # A2C_Auth_OpenID_NoPreserveParams

     # if you do not overload get_uname() (see below), then
     # PerlHeaderParserHandlers must be invoked in order
     # to set up the dbi handle before checking auth
     # with the default method.  In this example,
     # MyApp::DBI::Connector is an Apache2::Controller::DBI::Connector
     # and MyApp::Session is an Apache2::Controller::Session::Cookie...
     # see those modules for more info.

     PerlInitHandler            MyApp::Dispatch 
     PerlHeaderParserHandler    MyApp::DBI::Connector
     PerlHeaderParserHandler    MyApp::Session
     PerlHeaderParserHandler    Apache2::Controller::Auth::OpenID
 </Location>

=head1 DESCRIPTION

Implements an authentication mechanism for L<Apache2::Controller>
that uses OpenID.  

This is NOT an AuthenPerlHandler.  This is an implementation
of a simple cookie-based mechanism that shows the browser
a login page, where your controller should present and process an
HTML form for logging in.  

If you want an authentication handler that uses browser-based auth
(the pop-up dialog implemented by HTTP auth protocol) use 
L<Apache::Authen::OpenID>, which is not a part of Apache2::Controller
but should work for you anyway.

Natively this depends on L<Apache2::Controller::Session::Cookie>
and L<Apache2::Controller::DBI::Connector> being configured
correctly, but you could always subclass this and overload the
methods below to get information from other sources.

If no claimed ID is detected, the user is shown the login
page.  If an error occured, you'll find the L<Net::OpenID::Consumer>
error details in the session under C<< {a2c}{openid}{errtext} >>
and C<< {a2c}{openid}{errcode} >>.

=head2 REDIRECTION OR REDISPATCH?

Whether redirecting or redispatching, stuff has to be saved
in the session, so C<< $r->notes->{a2c}{session_force_save} >>
will be set.

=head3 INTERNAL LOGIN, LOGOUT AND REGISTER PAGES

=head4 RELATIVE URIS - REDISPATCH

If the uris for these pages are relative, not absolute, i.e.
they are handled by the same controller that we're going to
anyway, then it
tries setting the uri and re-dispatching by grabbing the dispatch
class name out of C<< $r->pnotes->{a2c}{dispatch_class} >> and 
instantiating a new dispatch handler object.

(Dispatch can't keep the handler
subref around in pnotes due to circular references, or reliably assume 
that we know at what location in
the C<< PerlInitHandler >> stack the dispatch handler coderef was
stored by Apache, so we just create a new one - this is assured
to be faster than creating an entire new request, which would
do that anyway.)

So in this case, the content for the login, logout, or register pages will
appear even though the browser uri still displays the requested
protected URI.

=head4 ABSOLUTE URIS - REDIRECT

If the uris for the internal pages are absolute, i.e.
they might be handled by a different controller than the
one that was dispatched, a redirect using Location HTTP header
is used.

=head3 EXTERNAL OPENID PAGES

Any time the browser needs to go to an external page (the openid server),
a redirect using a Location: HTTP header is used.

=head2 PRESERVATION OF INITIAL REQUEST

=head3 REQUESTED URI

When it goes to your login, or register page, it 
stashes the user's uri into the session as 
C<< {a2c}{openid}{previous_uri} >>
and should preserve this for the return url.  It uses
C<< $r->construct_url() >> as the trusted root.