lib/Catalyst/Authentication/Store/Minimal.pm

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