lib/Catalyst/Plugin/Authentication/Store/Minimal.pm

   1 package Catalyst::Plugin::Authentication::Store::Minimal;
   2
   3 use strict;
   4 use warnings;
   5
   6 use Catalyst::Plugin::Authentication::User::Hash;
   7 use Scalar::Util ();
   8 use base qw/Class::Accessor::Fast/;
   9
  10 BEGIN {
  11     __PACKAGE__->mk_accessors(qw/userhash/);
  12 }
  13
  14 sub new {
  15     my ( $class, $config, $app) = @_;
  16
  17     bless { userhash => $config->{'users'} }, $class;
  18 }
  19
  20 sub from_session {
  21         my ( $self, $c, $id ) = @_;
  22
  23         return $id if ref $id;
  24
  25         $self->find_user( { id => $id } );
  26 }
  27
  28 ## this is not necessarily a good example of what find_user can do, since all we do is
  29 ## look up with the id anyway.  find_user can be used to locate a user based on other
  30 ## combinations of data.  See C::P::Authentication::Store::DBIx::Class for a better example
  31 sub find_user {
  32     my ( $self, $userinfo, $c ) = @_;
  33
  34     my $id = $userinfo->{'id'};
  35
  36     $id ||= $userinfo->{'username'};
  37
  38     return unless exists $self->userhash->{$id};
  39
  40     my $user = $self->userhash->{$id};
  41
  42     if ( ref $user ) {
  43         if (     Scalar::Util::blessed($user)
  44              and $user->isa('Catalyst::Plugin::Authentication::User::Hash') )
  45         {
  46             return $user;
  47         }
  48         if ( ref $user eq "HASH" ) {
  49             $user->{id} ||= $id;
  50             return bless $user, "Catalyst::Plugin::Authentication::User::Hash";
  51         }
  52         else {
  53             Catalyst::Exception->throw( "The user '$id' is a reference of type "
  54                   . ref($user)
  55                   . " but should be a HASH" );
  56         }
  57     }
  58     else {
  59         Catalyst::Exception->throw(
  60             "The user '$id' is has to be a hash reference or an object");
  61     }
  62
  63     return $user;
  64 }
  65
  66 sub user_supports {
  67     my $self = shift;
  68
  69     # choose a random user
  70     scalar keys %{ $self->userhash };
  71     ( undef, my $user ) = each %{ $self->userhash };
  72
  73     $user->supports(@_);
  74 }
  75
  76 ## Backwards compatibility
  77 #
  78 # This is a backwards compatible routine.  get_user is specifically for loading a user by it's unique id
  79 # find_user is capable of doing the same by simply passing { id => $id }
  80 # no new code should be written using get_user as it is deprecated.
  81 sub get_user {
  82     my ( $self, $id ) = @_;
  83     $self->find_user({id => $id});
  84 }
  85
  86 ## backwards compatibility
  87 sub setup {
  88     my $c = shift;
  89
  90     $c->default_auth_store(
  91         __PACKAGE__->new(
  92             $c->config->{authentication}, $c
  93         )
  94     );
  95
  96         $c->NEXT::setup(@_);
  97 }
  98
  99 __PACKAGE__;
 100
 101 __END__
 102
 103 =pod
 104
 105 =head1 NAME
 106
 107 Catalyst::Plugin::Authentication::Store::Minimal - Minimal
 108 authentication store.
 109
 110 =head1 SYNOPSIS
 111
 112     # you probably just want Store::Minimal under most cases,
 113     # but if you insist you can instantiate your own store:
 114
 115     use Catalyst::Plugin::Authentication::Store::Minimal;
 116
 117     use Catalyst qw/
 118         Authentication
 119     /;
 120
 121     __PACKAGE__->config->{authentication} =
 122                     {
 123                         default_realm => 'members',
 124                         realms => {
 125                             members => {
 126                                 credential => {
 127                                     class => 'Password',
 128                                     password_field => 'password',
 129                                     password_type => 'clear'
 130                                 },
 131                                 store => {
 132                                     class => 'Minimal',
 133                                         users = {
 134                                             bob => {
 135                                                 password => "s00p3r",
 136                                                 editor => 'yes',
 137                                                 roles => [qw/edit delete/],
 138                                             },
 139                                             william => {
 140                                                 password => "s3cr3t",
 141                                                 roles => [qw/comment/],
 142                                             }
 143                                         }
 144                                     }
 145                                 }
 146                         }
 147                     };
 148
 149
 150 =head1 DESCRIPTION
 151
 152 This authentication store lets you create a very quick and dirty user
 153 database in your application's config hash.
 154
 155 You will need to include the Authentication plugin, and at least one Credential
 156 plugin to use this Store. Credential::Password is reccommended.
 157
 158 It's purpose is mainly for testing, and it should probably be replaced by a
 159 more "serious" store for production.
 160
 161 The hash in the config, as well as the user objects/hashes are freely mutable
 162 at runtime.
 163
 164 =head1 CONFIGURATION
 165
 166 =over 4
 167
 168 =item class
 169
 170 The classname used for the store. This is part of
 171 L<Catalyst::Plugin::Authentication> and is the method by which
 172 Catalyst::Plugin::Authentication::Store::Minimal is loaded as the
 173 user store. For this module to be used, this must be set to
 174 'Minimal'.
 175
 176 =item users
 177
 178 This is a simple hash of users, the keys are the usenames, and the values are
 179 hashrefs containing a password key/value pair, and optionally, a roles/list
 180 of role-names pair. If using roles, you will also need to add the
 181 Authorization::Roles plugin.
 182
 183 See the SYNOPSIS for an example.
 184
 185 =back
 186
 187 =head1 METHODS
 188
 189 There are no publicly exported routines in the Minimal store (or indeed in
 190 most authentication stores)  However, below is a description of the routines
 191 required by L<Catalyst::Plugin::Authentication> for all authentication stores.
 192
 193 =over 4
 194
 195 =item new ( $config, $app )
 196
 197 Constructs a new store object, which uses the user element of the supplied config
 198 hash ref as it's backing structure.
 199
 200 =item find_user ( $authinfo, $c )
 201
 202 Keys the hash by the 'id' or 'username' element in the authinfo hash and returns the user.
 203
 204 ... documentation fairy stopped here. ...
 205
 206 If the return value is unblessed it will be blessed as
 207 L<Catalyst::Plugin::Authentication::User::Hash>.
 208
 209 =item from_session $id
 210
 211 Delegates to C<get_user>.
 212
 213 =item user_supports
 214
 215 Chooses a random user from the hash and delegates to it.
 216
 217 =back
 218
 219 =cut
 220
 221