lib/Catalyst/Plugin/Authentication/Store/Minimal.pm

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