lib/Catalyst/Authentication/Store/Minimal.pm

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