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 )
Register, unless the enable_register option has been turned off (on by default).
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.
login ( end-point: /login )
Login, redirect if already logged in.
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::AuthYou 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
CPAN Ratings
Search CPAN
ACKNOWLEDGEMENTS
t0m: Tomas Doran <bobtfish@bobtfish.net>
castaway: Jess Robinson (OpenID support)
LICENSE AND COPYRIGHT
Copyright 2012 Rob Brown.
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.