README.pod

   1 =pod
   2
   3 =encoding UTF-8
   4
   5 =head1 NAME
   6
   7 Catalyst::Authentication::Store::Htpasswd - Authen::Htpasswd based user storage/authentication
   8
   9 =head1 VERSION
  10
  11 version 1.006
  12
  13 =head1 SYNOPSIS
  14
  15     use Catalyst qw/
  16       Authentication
  17     /;
  18
  19     __PACKAGE__->config(
  20         authentication => {
  21             default_realm => 'test',
  22             realms => {
  23                 test => {
  24                     credential => {
  25                         class          => 'Password',
  26                         password_field => 'password',
  27                         password_type  => 'self_check',
  28                     },
  29                     store => {
  30                         class => 'Htpasswd',
  31                         file => 'htpasswd',
  32                     },
  33                 },
  34             },
  35         },
  36     );
  37
  38     sub login : Global {
  39         my ( $self, $c ) = @_;
  40
  41         $c->authenticate({ username => $c->req->param("login"), password => $c->req->param("password") });
  42     }
  43
  44 =head1 DESCRIPTION
  45
  46 This plugin uses L<Authen::Htpasswd> to let your application use C<< .htpasswd >>
  47 files for it's authentication storage.
  48
  49 =head1 METHODS
  50
  51 =head2 new
  52
  53 Simple constructor, dies if the htpassword file can't be found
  54
  55 =head2 find_user
  56
  57 Looks up the user, and returns a Catalyst::Authentication::Store::Htpasswd::User object.
  58
  59 =head2 user_supports
  60
  61 Delegates to L<< Catalyst::Authentication::User->supports|Catalyst::Authentication::User/supports >> or an
  62 override in L<user_class|/user_class>.
  63
  64 =head2 from_session
  65
  66 Delegates the user lookup to L<find_user|/find_user>
  67
  68 =head1 CONFIGURATION
  69
  70 =head2 file
  71
  72 The path to the htpasswd file. If the path starts with a slash, then it is assumed to be a fully
  73 qualified path, otherwise the path is fed through C<< $c->path_to >> and so normalised to the
  74 application root.
  75
  76 Alternatively, it is possible to pass in an L<Authen::Htpasswd> object here, and this will be
  77 used as the htpasswd file.
  78
  79 =head2 user_class
  80
  81 Change the user class which this store returns. Defaults to L<Catalyst::Authentication::Store::Htpasswd::User>.
  82 This can be used to add additional functionality to the user class by sub-classing it, but will not normally be
  83 needed.
  84
  85 =head2 user_field
  86
  87 Change the field that the username is found in in the information passed into the call to C<< $c->authenticate() >>.
  88
  89 This defaults to I< username >, and generally you should be able to use the module as shown in the synopsis, however
  90 if you need a different field name then this setting can change the default.
  91
  92 Example:
  93
  94     __PACKAGE__->config( authentication => { realms => { test => {
  95                     store => {
  96                         class => 'Htpasswd',
  97                         user_field => 'email_address',
  98                     },
  99     }}});
 100     # Later in your code
 101     $c->authenticate({ email_address => $c->req->param("email"), password => $c->req->param("password") });
 102
 103 =head1 SEE ALSO
 104
 105 L<Authen::Htpasswd>.
 106
 107 =head1 SUPPORT
 108
 109 Bugs may be submitted through L<the RT bug tracker|https://rt.cpan.org/Public/Dist/Display.html?Name=Catalyst-Authentication-Store-Htpasswd>
 110 (or L<bug-Catalyst-Authentication-Store-Htpasswd@rt.cpan.org|mailto:bug-Catalyst-Authentication-Store-Htpasswd@rt.cpan.org>).
 111
 112 There is also a mailing list available for users of this distribution, at
 113 L<http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst>.
 114
 115 There is also an irc channel available for users of this distribution, at
 116 L<C<#catalyst> on C<irc.perl.org>|irc://irc.perl.org/#catalyst>.
 117
 118 =head1 AUTHOR
 119
 120 יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
 121
 122 =head1 CONTRIBUTORS
 123
 124 =for stopwords David Kamholz Tomas Doran Karen Etheridge Tom Bloor Christopher Hoskin Ilmari Vacklin
 125
 126 =over 4
 127
 128 =item *
 129
 130 David Kamholz <dkamholz@cpan.org>
 131
 132 =item *
 133
 134 Tomas Doran <bobtfish@bobtfish.net>
 135
 136 =item *
 137
 138 Karen Etheridge <ether@cpan.org>
 139
 140 =item *
 141
 142 Tom Bloor <t.bloor@shadowcat.co.uk>
 143
 144 =item *
 145
 146 Christopher Hoskin <christopher.hoskin@gmail.com>
 147
 148 =item *
 149
 150 Ilmari Vacklin <ilmari.vacklin@cs.helsinki.fi>
 151
 152 =back
 153
 154 =head1 COPYRIGHT AND LICENCE
 155
 156 This software is copyright (c) 2005 by יובל קוג'מן (Yuval Kogman).
 157
 158 This is free software; you can redistribute it and/or modify it under
 159 the same terms as the Perl 5 programming language system itself.
 160
 161 =cut