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