lib/Catalyst/Plugin/Authentication.pm

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