File Coverage

blib/lib/Catalyst/Plugin/Authentication/Store/HTTP.pm
Criterion Covered Total %
statement 7 9 77.7
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 10 12 83.3


line stmt bran cond sub pod time code
1             package Catalyst::Plugin::Authentication::Store::HTTP;
2 1     1   28478 use strict;
  1         2  
  1         38  
3 1     1   6 use warnings;
  1         2  
  1         40  
4              
5             our $VERSION = '0.05';
6              
7 1     1   507 use Catalyst::Exception;
  0            
  0            
8             use Catalyst::Plugin::Authentication::Store::HTTP::Backend;
9              
10             =head1 NAME
11              
12             Catalyst::Plugin::Authentication::Store::HTTP - Remote HTTP authentication storage
13              
14             =head1 SYNOPSIS
15              
16             # load plugins
17             use Catalyst qw/
18             Session
19             Session::State::Cookie
20             Session::Store::FastMmap
21              
22             Authentication
23             Authentication::Store::HTTP
24             Authentication::Credential::Password
25             # or Authentication::Credential::HTTP
26             /;
27              
28             # configure your authentication host
29             MyApp->config(
30             authentication => {
31             http => {
32             auth_url => 'http://example.com/',
33             },
34             },
35             );
36              
37             # and in action
38             sub login : Global {
39             my ( $self, $c ) = @_;
40              
41             $c->login( $username, $password );
42             }
43              
44             =head1 DESCRIPTION
45              
46             This module is Catalyst authentication storage plugin that
47             authenticates based on a URL HTTP HEAD fetch using the supplied
48             credentials. If the fetch succeeds then the authentication succeeds.
49              
50             L<LWP::UserAgent> is used to fetch the URL which requires authentication,
51             so any authentication method supported by that module can be used.
52              
53             Remote authentication methods known to work are:-
54              
55             =over 4
56              
57             =item *
58              
59             Basic
60              
61             =item *
62              
63             Digest
64              
65             =item *
66              
67             NTLM - but see notes below
68              
69             =back
70              
71             This is re-implementation of L<Catalyst::Plugin::Authentication::Basic::Remote>.
72              
73             =head1 CONFIGURATION
74              
75             Configuration is done in the standard Catalyst fashion. All
76             configuration keys are under C<authentication/http>.
77              
78             The supported keys are:-
79              
80             =over 4
81              
82             =item auth_url
83              
84             The URL that is fetched to demonstrate that the supplied credentials
85             work. This can be any URL that L<LWP::UserAgent> will support and
86             that will support a C<HEAD> method. This item must be supplied.
87              
88             =item keep_alive
89              
90             A boolean value that sets whether keep alive is used on the URL
91             fetch. This must be set for NTLM authentication - and the I<ntlm>
92             configuration key forces it to be set.
93              
94             =item domain
95              
96             An optional domain value for authentication. If set the presented
97             username for authentication has this domain prepended to it - this is
98             really of use only for NTLM authentication mode.
99              
100             =item ntlm
101              
102             A boolean value that should be set if NTLM authentication is
103             required. If this is set then I<domain> must be set and I<keep_alive>
104             is forced on.
105              
106             =back
107              
108             =head1 EXTENDED METHODS
109              
110             =head2 setup
111              
112             Checks the configuration information and sets up the
113             C<default_auth_store>. This method is not intended to be called
114             directly by user code.
115              
116              
117             =cut
118              
119             sub setup {
120             my $c = shift;
121              
122             unless ($c->config->{authentication}{http}{auth_url}) {
123             Catalyst::Exception->throw(
124             message => q/Require auth_url for Authentication::Store::HTTP/);
125             }
126              
127             if ($c->config->{authentication}{http}{ntlm}) {
128              
129             # force keep_alive to be set
130             $c->config->{authentication}{http}{keep_alive} ||= 1;
131              
132             #
133             # domain needs to be set
134             unless ($c->config->{authentication}{http}{domain}) {
135             Catalyst::Exception->throw(message =>
136             q/Require domain to be set in NTLM mode for Authentication::Store::HTTP/
137             );
138             }
139             }
140              
141             $c->default_auth_store(
142             Catalyst::Plugin::Authentication::Store::HTTP::Backend->new(
143             $c->config->{authentication}{http}
144             )
145             );
146              
147             $c->NEXT::setup(@_);
148             }
149              
150             =head1 SEE ALSO
151              
152             L<Catalyst::Plugin::Authentication>.
153              
154             =head1 AUTHOR
155              
156             Daisuke Murase <typester@cpan.org>
157              
158             Nigel Metheringham <nigelm@cpan.org>
159              
160             =head1 COPYRIGHT
161              
162             This program is free software; you can redistribute it and/or modify
163             it under the same terms as Perl itself.
164              
165             The full text of the license can be found in the LICENSE file included
166             with this module.
167              
168             =cut
169              
170             1;
171