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, $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 ) {
  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 authentication store
 108
 109 =head1 SYNOPSIS
 110
 111     # you probably just want Store::Minimal under most cases,
 112     # but if you insist you can instantiate your own store:
 113
 114     use Catalyst::Plugin::Authentication::Store::Minimal;
 115
 116     use Catalyst qw/
 117         Authentication
 118     /;
 119
 120     __PACKAGE__->config->{authentication} =
 121                     {
 122                         default_realm => 'members',
 123                         realms => {
 124                             members => {
 125                                 credential => {
 126                                     class => 'Password',
 127                                     password_field => 'password',
 128                                     password_type => 'clear'
 129                                 },
 130                                 store => {
 131                                     class => 'Minimal',
 132                                         users = {
 133                                             bob => {
 134                                                 password => "s00p3r",
 135                                                 editor => 'yes',
 136                                                 roles => [qw/edit delete/],
 137                                             },
 138                                             william => {
 139                                                 password => "s3cr3t",
 140                                                 roles => [qw/comment/],
 141                                             }
 142                                         }
 143                                     }
 144                                 }
 145                         }
 146                     };
 147
 148
 149 =head1 DESCRIPTION
 150
 151 This authentication store lets you create a very quick and dirty user
 152 database in your application's config hash.
 153
 154 You will need to include the Authentication plugin, and at least one Credential
 155 plugin to use this Store. Credential::Password is reccommended.
 156
 157 It's purpose is mainly for testing, and it should probably be replaced by a
 158 more "serious" store for production.
 159
 160 The hash in the config, as well as the user objects/hashes are freely mutable
 161 at runtime.
 162
 163 =head1 CONFIGURATION
 164
 165 =over 4
 166
 167 =item class
 168
 169 The classname used for the store. This is part of
 170 L<Catalyst::Plugin::Authentication> and is the method by which
 171 Catalyst::Plugin::Authentication::Store::Minimal is loaded as the
 172 user store. For this module to be used, this must be set to
 173 'Minimal'.
 174
 175 =item users
 176
 177 This is a simple hash of users, the keys are the usenames, and the values are
 178 hashrefs containing a password key/value pair, and optionally, a roles/list
 179 of role-names pair. If using roles, you will also need to add the
 180 Authorization::Roles plugin.
 181
 182 See the SYNOPSIS for an example.
 183
 184 =back
 185
 186 =head1 METHODS
 187
 188 There are no publicly exported routines in the Minimal store (or indeed in
 189 most authentication stores)  However, below is a description of the routines
 190 required by L<Catalyst::Plugin::Authentication> for all authentication stores.
 191
 192 =head2 new( $config, $app, $realm )
 193
 194 Constructs a new store object, which uses the user element of the supplied config
 195 hash ref as it's backing structure.
 196
 197 =head2 find_user( $authinfo, $c )
 198
 199 Keys the hash by the 'id' or 'username' element in the authinfo hash and returns the user.
 200
 201 ... documentation fairy stopped here. ...
 202
 203 If the return value is unblessed it will be blessed as
 204 L<Catalyst::Plugin::Authentication::User::Hash>.
 205
 206 =head2 from_session( $id )
 207
 208 Delegates to C<get_user>.
 209
 210 =head2 user_supports( )
 211
 212 Chooses a random user from the hash and delegates to it.
 213
 214 =cut
 215
 216