lib/Catalyst/Authentication/Store/Minimal.pm

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