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