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

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