lib/Catalyst/Authentication/Store/Minimal.pm

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