1 package Catalyst::Authentication::Credential::Remote;
6 use base 'Class::Accessor::Fast';
9 __PACKAGE__->mk_accessors(
10 qw/allow_re deny_re cutname_re source realm username_field/);
14 my ( $class, $config, $app, $realm ) = @_;
19 # we are gonna compile regular expresions defined in config parameters
20 # and explicitly throw an exception saying what parameter was invalid
21 if (defined($config->{allow_regexp}) && ($config->{allow_regexp} ne "")) {
22 eval { $self->allow_re( qr/$config->{allow_regexp}/ ) };
23 Catalyst::Exception->throw( "Invalid regular expression in ".
24 "'allow_regexp' configuration parameter") if $@;
26 if (defined($config->{deny_regexp}) && ($config->{deny_regexp} ne "")) {
27 eval { $self->deny_re( qr/$config->{deny_regexp}/ ) };
28 Catalyst::Exception->throw( "Invalid regular expression in ".
29 "'deny_regexp' configuration parameter") if $@;
31 if (defined($config->{cutname_regexp}) && ($config->{cutname_regexp} ne "")) {
32 eval { $self->cutname_re( qr/$config->{cutname_regexp}/ ) };
33 Catalyst::Exception->throw( "Invalid regular expression in ".
34 "'cutname_regexp' configuration parameter") if $@;
36 $self->source($config->{source} || 'REMOTE_USER');
38 $self->username_field($config->{username_field} || 'username');
43 my ( $self, $c, $realm, $authinfo ) = @_;
46 if ($self->source eq "REMOTE_USER") {
48 if (defined($c->engine->env)) {
49 # BEWARE: $c->engine->env was broken prior 5.80005
50 $remuser = $c->engine->env->{REMOTE_USER};
52 elsif ($c->req->can('remote_user')) {
53 # $c->req->remote_users was introduced in 5.80005; if not evailable we are
54 # gonna use $c->req->user that is deprecated but more or less works as well
55 $remuser = $c->req->remote_user;
57 elsif ($c->req->can('user')) {
58 # maybe show warning that we are gonna use DEPRECATED $req->user
59 if (ref($c->req->user)) {
60 # I do not know exactly when this happens but it happens
61 Catalyst::Exception->throw( "Cannot get remote user from ".
62 "\$c->req->user as it seems to be a reference not a string" );
65 $remuser = $c->req->user;
69 elsif ($self->source =~ /^(SSL_CLIENT_.*|CERT_*|AUTH_USER)$/) {
70 # if you are using 'exotic' webserver or if the user is
71 # authenticated e.g via SSL certificate his name could be avaliable
72 # in different variables
73 # BEWARE: $c->engine->env was broken prior 5.80005
74 my $nam=$self->source;
75 if ($c->engine->can('env')) {
76 $remuser = $c->engine->env->{$nam};
79 # this happens on Catalyst 5.80004 and before (when using FastCGI)
80 Catalyst::Exception->throw( "Cannot handle parameter 'source=$nam'".
81 " as runnig Catalyst engine has broken \$c->engine->env" );
85 Catalyst::Exception->throw( "Invalid value of 'source' parameter");
87 return unless defined($remuser);
88 return if ($remuser eq "");
90 # $authinfo hash can contain item username (it is optional) - if it is so
91 # this username has to be equal to remote_user
92 my $authuser = $authinfo->{username};
93 return if (defined($authuser) && ($authuser ne $remuser));
95 # handle deny / allow checks
96 return if (defined($self->deny_re) && ($remuser =~ $self->deny_re));
97 return if (defined($self->allow_re) && ($remuser !~ $self->allow_re));
99 # if param cutname_regexp is specified we try to cut the final usename as a
100 # substring from remote_user
102 if (defined($self->cutname_re)) {
103 if (($remuser =~ $self->cutname_re) && ($1 ne "")) {
108 $authinfo->{id} = $authinfo->{ $self->username_field } = $usr;
109 $authinfo->{remote_user} = $remuser; # just to keep the original value
110 my $user_obj = $realm->find_user( $authinfo, $c );
111 return ref($user_obj) ? $user_obj : undef;
122 Catalyst::Authentication::Credential::Remote - Let the webserver (e.g. Apache)
123 authenticate Catalyst application users
130 'Plugin::Authentication' => {
131 default_realm => 'remoterealm',
136 allow_regexp => '^(user.*|admin|guest)$',
137 deny_regexp => 'test',
141 # if you want to have some additional user attributes
142 # like user roles, user full name etc. you can specify
143 # here the store where you keep this data
151 # in your Controller/Root.pm you can implement "auto-login" in this way
152 sub begin : Private {
153 my ( $self, $c ) = @_;
154 unless ($c->user_exists) {
155 # authenticate() for this module does not need any user info
156 # as the username is taken from $c->req->remote_user and
157 # password is not needed
158 unless ($c->authenticate( {} )) {
159 # return 403 forbidden or kick out the user in other way
164 # or you can implement in any controller an ordinary login action like this
166 my ( $self, $c ) = @_;
167 $c->authenticate( {} );
172 This module allows you to authenticate the users of your Catalyst application
173 on underlaying webserver. The complete list of authentication method available
174 via this module depends just on what your webserver (e.g. Apache, IIS, Lighttpd)
177 Besides the common methods like HTTP Basic and Digest authentication you can
178 also use sophisticated ones like so called "integrated authentication" via
179 NTLM or Kerberos (popular in corporate intranet applications running in Windows
180 Active Directory enviroment) or even the SSL authentication when users
181 authenticate themself using their client SSL certificates.
183 The main idea of this module is based on a fact that webserver passes the name
184 of authenticated user into Catalyst application as REMOTE_USER variable (or in
185 case of SSL client authentication in other variables like SSL_CLIENT_S_DN on
186 Apache + mod_ssl) - from this point referenced as WEBUSER.
187 This module simply takes this value - perfoms some optional checks (see
188 below) - and if everything is OK the WEBUSER is declared as authenticated on
189 Catalyst level. In fact this module does not perform any check for password or
190 other credential; it simply believes the webserver that user was properly
197 This config item is B<REQUIRED>.
199 B<class> is part of the core L<Catalyst::Plugin::Authentication> module, it
200 contains the class name of the store to be used.
202 The classname used for Credential. This is part of L<Catalyst::Plugin::Authentication>
203 and is the method by which Catalyst::Authentication::Credential::Remote is
204 loaded as the credential validator. For this module to be used, this must be set
209 This config item is B<OPTIONAL> - default is REMOTE_USER.
211 B<source> contains a name of a variable passed from webserver that contains the
214 Supported values: REMOTE_USER, SSL_CLIENT_*, CERT_*, AUTH_USER
216 B<BEWARE:> Support for using different variables than REMOTE_USER does not work
217 properly with Catalyst 5.8004 and before (if you want details see source code).
219 Note1: Apache + mod_ssl uses SSL_CLIENT_S_DN, SSL_CLIENT_S_DN_* etc. (has to be
220 enabled by 'SSLOption +StdEnvVars') or you can also let Apache make a copy of
221 this value into REMOTE_USER (Apache option 'SSLUserName SSL_CLIENT_S_DN').
223 Note2: Microsoft IIS uses CERT_SUBJECT, CERT_SERIALNUMBER etc. for storing info
224 about client authenticated via SSL certificate. AUTH_USER on IIS seems to have
225 the same value as REMOTE_USER (but there might be some differences I am not
230 This config item is B<OPTIONAL> - no default value.
232 B<deny_regexp> contains a regular expression used for check against WEBUSER
237 This config item is B<OPTIONAL> - no default value.
239 B<deny_regexp> contains a regular expression used for check against WEBUSER.
241 Allow/deny checking of WEBUSER values goes in this way:
243 1) If B<deny_regexp> is defined and WEBUSER matches deny_regexp then
244 authentication FAILS otherwise continues with next step. If deny_regexp is not
245 defined or is an empty string we skip this step.
247 2) If B<allow_regexp> is defined and WEBUSER matches allow_regexp then
248 authentication PASSES otherwise FAILS. If allow_regexp is not
249 defined or is an empty string we skip this step.
251 The order deny-allow is fixed.
253 =head2 cutname_regexp
255 This config item is B<OPTIONAL> - no default value.
257 If param B<cutname_regexp> is specified we try to cut the final usename passed to
258 Catalyst application as a substring from WEBUSER. This is usefull for
259 example in case of SSL authentication when WEBUSER looks like this
260 'CN=john, OU=Unit Name, O=Company, C=CZ' - from this format we can simply cut
261 pure usename by cutname_regexp set to 'CN=(.*), OU=Unit Name, O=Company, C=CZ'.
263 Substring is always taken as '$1' regexp substring. If WEBUSER does not
264 match cutname_regexp at all or if '$1' regexp substring is empty we pass the
265 original WEBUSER value (without cutting) to Catalyst application.
267 =head2 username_field
269 This config item is B<OPTIONAL> - default is I<username>
271 The key name in the authinfo hash that the user's username is mapped into.
272 This is useful for using a store which requires a specific unusual field name
273 for the username. The username is additionally mapped onto the I<id> key.
277 =head2 new ( $config, $app, $realm )
279 Instantiate a new Catalyst::Authentication::Credential::Remote object using the
280 configuration hash provided in $config. In case of invalid value of any
281 configuration parameter (e.g. invalid regular expression) throws an exception.
285 =head2 authenticate ( $realm, $authinfo )
287 Takes the username form WEBUSER set by webserver, performs additional
288 checks using optional allow_regexp/deny_regexp configuration params, optionaly
289 takes substring from WEBUSER and the sets the resulting value as
296 It is B<strongly recommended> to use this module with Catalyst 5.80005 and above
297 as previous versions have some bugs related to $c->engine->env and do not
298 support $c->req->remote_user.
300 This module tries some workarounds when it detects an older version and should