NAME

CatalystX::Controller::Auth - A config-driven Catalyst authentication controller base class.

VERSION

Version 0.22

SYNOPSIS

This is a Catalyst controller for handling registering, logging in/out, forgotten/resetting passwords, and changing passwords.

This controller was essentially born out of HTML::FormHandlerX::Form::Login (which it uses), though that form does not want to become dependant on Catalyst.

See CatalystX::SimpleLogin for an alternative approach.

Ensure you include the Catalyst::Plugin::StatusMessage in MyApp.pm.

 use Catalyst qw/
    ...
    StatusMessage
    ... 
 /;

Extend this base controller class for your own authentication controller, then modify your config as required.

The configs for action_after_register, action_after_login, and action_after_change_password will all need specifying in your own config since they will be specific to your app.

 package MyApp::Controller::Auth;
 
 use Moose;
 use namespace::autoclean;
 
 BEGIN { extends 'CatalystX::Controller::Auth'; }
 
 __PACKAGE__->meta->make_immutable;
 
 1;

Configure it as you like ...

 <Controller::Auth>
 
         form_handler                           HTML::FormHandlerX::Form::Login
         
         view                                   TT
         model                                  DB::User
    
         login_id_field                         email
         login_id_db_field                      email
     
         enable_register                        1
         enable_sending_register_email          1
     
         register_template                      auth/register.tt
         login_template                         auth/login.tt
         change_password_template               auth/change-password.tt
         forgot_password_template               auth/forgot-password.tt
         reset_password_template                auth/reset-password.tt
 
         email_stash_key                        email_template

         forgot_password_email_view             Email::Template
         forgot_password_email_from             "MyApp" <somebody@example.com>
         forgot_password_email_subject          Password Reset
         forgot_password_email_template_plain   reset-password-plain.tt

         register_email_view                    Email::Template
         register_email_from                    "MyApp" <somebody@example.com>
         register_email_subject                 Registration Success
         register_email_template_plain          register-plain.tt
 
         register_successful_message            "You are now registered"
         register_exists_failed_message         "That username is already registered."
         login_required_message                 "You need to login."
         already_logged_in_message              "You are already logged in."
         login_successful_message               "Logged in!"
         logout_successful_message              "You have been logged out successfully."
         login_failed_message                   "Bad username or password."
         password_changed_message               "Password changed."
         password_reset_message                 "Password reset successfully."
         forgot_password_id_unknown             "Email address not registered." 
    
         token_salt                             'tgve546vy6yv%^$fghY56VH54& H54&%$uy^5 Y^53U&$u v5ev'
    
         auto_login_after_register              1
     
         action_after_register                  /admin/index
         action_after_login                     /admin/index
         action_after_change_password           /admin/index
 
 </Controller::Auth>

Override actions as necessary (hopefully not too much, otherwise I have not built this right).

All feedback and patches are always welcome.

CHAINS

base ( mid-point: / )

The controller currently chains/bases off /base, ie, the base chain in your Root controller.

 sub base :Chained('/base') :PathPart('') :CaptureArgs(0)

If you wish to chain off any other mid-point, and/or change the PathPart (by default empty), you can override this action...

 sub base :Chained('/my_base') :PathPart('users') :CaptureArgs(0)
 {
         my ( $self, $c ) = @_;
 
         $self->next::method( $c );
 }

authenticated ( mid-point: / )

Chain off this action to make sure the user is logged in.

 sub authenticated :Chained('base') :PathPart('') :CaptureArgs(0)

not_authenticated

This method is called if the user is not currently logged in.

By default it redirects (and detaches) to the URI for the login action with an error message of login_required_message.

An instance method that is also passed the Catalyst context object $c.

register ( end-point: /register )

If the user is already logged in, it redirects (and detaches) to the URI for action_after_login with status message already_logged_in_message.

Upon registering, an attempt is made to call auto_create() on your model (DB::User if using the default configs above).

A change is coming in May 2012 to this approach, to fallback to simply calling create() if there is no auto_create method in your model.

In the meantime, if you do not wish to take advantage of this hook, you will need to create the method to simply call the create() method of your model...

 sub auto_create
 {
     my $self = shift;
     
     $self->create( @_ );
 }

send_register_email

Uses Catalyst::View::Email::Template by default.

An instance method that is also passed the Catalyst context object $c, along with a hash of extra parameteres, specifically the user object.

post_register

Called after a user has successfully registered, and the register email has been sent (unless you have overridden send_register_email).

An instance method that is also passed the Catalyst context object $c.

By default this method redirects to the URI for action_after_register with status message register_successful_message.

 sub login :Chained('base') :PathPart :Args(0)

post_login

Called after a successfull login.

An instance method that is also passed the Catalyst context object $c.

By defualt redirects (and detaches) to the URI for action_after_login with a status message of login_successful_message.

logout ( end-point: /logout )

Logs out, and redirects back to /login.

 sub logout :Chained('base') :PathPart :Args(0)

post_logout

Called after logging out.

An instance method that is also passed the Catalyst context object $c.

By default redirects (and detaches) to the URI for the login action with a status message of logout_successful_message.

forgot_password ( end-point: /forgot-password/ )

Send a forgotten password token to reset it. This method uses the built-in features from HTML::FormHandlerX::Form::Login for handling the token, etc.

 sub forgot_password :Chained('base') :PathPart('forgot-password') :Args(0)

send_password_reset_email

Uses Catalyst::View::Email::Template by default.

An instance method that is also passed the Catalyst context object $c, along with a hash of extra parameteres, specifically the user object.

reset_password ( end-point: /reset-password/ )

Reset password using a token sent in an email.

 sub reset_password :Chained('base') :PathPart('reset-password') :Args(0)

post_reset_password

After successfully resetting a users password.

An instance method that is also passed the Catalyst context object $c.

By default redirects (and detaches) to the URI for the login action with a status message of password_reset_message.

get ( mid-point: /auth/*/ )

Get a user (by capturing the ID) and puts them in the stash.

If no matching user is found, redirects to the URI for the login action.

 sub get :Chained('base') :PathPart('auth') :CaptureArgs(1)

change_password ( end-point: /auth/*/change-password/ )

Change your password.

 sub change_password :Chained('get') :PathPart('change-password') :Args(0)

post_change_password

After changing a password.

An instance method that is also passed the Catalyst context object $c.

By default redirects (and detaches) to the URI for action_after_change_password with status message password_changed_message.

TODO

Damn more tests!

AUTHOR

Rob Brown, <rob at intelcompute.com>

BUGS

Please report any bugs or feature requests to bug-catalystx-controller-auth at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CatalystX-Controller-Auth. I will be notified, and then you will automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc CatalystX::Controller::Auth

You can also look for information at:

RT: CPAN's request tracker (report bugs here)

http://rt.cpan.org/NoAuth/Bugs.html?Dist=CatalystX-Controller-Auth
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/CatalystX-Controller-Auth
CPAN Ratings

http://cpanratings.perl.org/d/CatalystX-Controller-Auth
Search CPAN

http://search.cpan.org/dist/CatalystX-Controller-Auth/

ACKNOWLEDGEMENTS

t0m: Tomas Doran <bobtfish@bobtfish.net>

castaway: Jess Robinson (OpenID support)

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

NAME

VERSION

SYNOPSIS

CHAINS

base ( mid-point: / )

authenticated ( mid-point: / )

not_authenticated

register ( end-point: /register )

send_register_email

post_register

login ( end-point: /login )

post_login

logout ( end-point: /logout )

post_logout

forgot_password ( end-point: /forgot-password/ )

send_password_reset_email

reset_password ( end-point: /reset-password/ )

post_reset_password

get ( mid-point: /auth/*/ )

change_password ( end-point: /auth/*/change-password/ )

post_change_password

TODO

AUTHOR

BUGS

SUPPORT

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT