lib/Catalyst/Plugin/Authentication.pm

   1 #!/usr/bin/perl
   2
   3 package Catalyst::Plugin::Authentication;
   4
   5 use base qw/Class::Accessor::Fast Class::Data::Inheritable/;
   6
   7 BEGIN {
   8     __PACKAGE__->mk_accessors(qw/user/);
   9     __PACKAGE__->mk_classdata(qw/default_auth_store/);
  10 }
  11
  12 use strict;
  13 use warnings;
  14
  15 sub set_authenticated {
  16     my ( $c, $user ) = @_;
  17
  18     $c->user($user);
  19
  20     if (    $c->isa("Catalyst::Plugin::Session")
  21         and $c->config->{authentication}{use_session} )
  22     {
  23         $c->session->{__user} = $user->for_session
  24           if $user->supperts("session");
  25         $c->session->{__user_class} = ref $user;
  26     }
  27 }
  28
  29 sub logout {
  30     my $c = shift;
  31
  32     $c->user(undef);
  33
  34     if (    $c->isa("Catalyst::Plugin::Session")
  35         and $c->config->{authentication}{use_session} )
  36     {
  37         delete @{ $c->session }{qw/__user __user_class/};
  38     }
  39 }
  40
  41 sub get_user {
  42     my ( $c, $uid ) = @_;
  43
  44     if ( my $store = $c->default_auth_store ) {
  45         return $store->get_user($uid);
  46     }
  47     else {
  48         Catalyst::Exception->throw(
  49                 "The user id $uid was passed to an authentication "
  50               . "plugin, but no default store was specified" );
  51     }
  52 }
  53
  54 sub prepare {
  55     my $c = shift->NEXT::prepare(@_);
  56
  57     if (    $c->isa("Catalyst::Plugin::Session")
  58         and $c->config->{authentication}{use_session}
  59         and !$c->user )
  60     {
  61         if ( $c->sessionid and my $user = $c->session->{__user} ) {
  62             $c->user( $c->session->{__user_class}->from_session( $c, $user ) );
  63         }
  64     }
  65
  66     return $c;
  67 }
  68
  69 sub setup {
  70     my $c = shift;
  71
  72     my $cfg = $c->config->{authentication};
  73
  74     %$cfg = (
  75         use_session => 1,
  76         %$cfg,
  77     );
  78
  79     $c->NEXT::setup(@_);
  80 }
  81
  82 __PACKAGE__;
  83
  84 __END__
  85
  86 =pod
  87
  88 =head1 NAME
  89
  90 Catalyst::Plugin::Authentication -
  91
  92 =head1 SYNOPSIS
  93
  94         use Catalyst qw/
  95                 Authentication
  96                 Authentication::Store::Foo
  97                 Authentication::Credential::Password
  98         /;
  99
 100 =head1 DESCRIPTION
 101
 102 The authentication plugin is used by the various authentication and
 103 authorization plugins in catalyst.
 104
 105 It defines the notion of a logged in user, and provides integration with the
 106
 107 =head1 METHODS
 108
 109 =over 4
 110
 111 =item logout
 112
 113 Delete the currently logged in user from C<user> and the session.
 114
 115 =item user
 116
 117 Returns the currently logged user or undef if there is none.
 118
 119 =item get_user $uid
 120
 121 Delegate C<get_user> to the default store.
 122
 123 =item default_auth_store
 124
 125 Returns C<< $c->config->{authentication}{store} >>.
 126
 127 =back
 128
 129 =head1 INTERNAL METHODS
 130
 131 =over 4
 132
 133 =item set_authenticated $user
 134
 135 Marks a user as authenticated. Should be called from a
 136 C<Catalyst::Plugin::Authentication::Credential> plugin after successful
 137 authentication.
 138
 139 This involves setting C<user> and the internal data in C<session> if
 140 L<Catalyst::Plugin::Session> is loaded.
 141
 142 =item prepare
 143
 144 Revives a user from the session object if there is one.
 145
 146 =item setup
 147
 148 Sets the default configuration parameters.
 149
 150 =item
 151
 152 =back
 153
 154 =head1 CONFIGURATION
 155
 156 =over 4
 157
 158 =item use_session
 159
 160 Whether or not to store the user's logged in state in the session, if the
 161 application is also using the L<Catalyst::Plugin::Authentication> plugin.
 162
 163 =back
 164
 165 =cut
 166
 167