1Catalyst::AuthenticatioUns:e:rCrCeodnetnrCtiaibtaualtl:ey:dsRteP:me:orAtluet(Dh3oe)cnutmiecnattaitoino:n:Credential::Remote(3)
2
3
4

NAME

6       Catalyst::Authentication::Credential::Remote - Let the webserver (e.g.
7       Apache) authenticate Catalyst application users
8

SYNOPSIS

10           # in your MyApp.pm
11           __PACKAGE__->config(
12
13               'Plugin::Authentication' => {
14                   default_realm => 'remoterealm',
15                   realms => {
16                       remoterealm => {
17                           credential => {
18                               class        => 'Remote',
19                               allow_regexp => '^(user.*|admin|guest)$',
20                               deny_regexp  => 'test',
21                           },
22                           store => {
23                               class => 'Null',
24                               # if you want to have some additional user attributes
25                               # like user roles, user full name etc. you can specify
26                               # here the store where you keep this data
27                           }
28                       },
29                   },
30               },
31
32           );
33
34           # in your Controller/Root.pm you can implement "auto-login" in this way
35           sub begin : Private {
36               my ( $self, $c ) = @_;
37               unless ($c->user_exists) {
38                   # authenticate() for this module does not need any user info
39                   # as the username is taken from $c->req->remote_user and
40                   # password is not needed
41                   unless ($c->authenticate( {} )) {
42                     # return 403 forbidden or kick out the user in other way
43                   };
44               }
45           }
46
47           # or you can implement in any controller an ordinary login action like this
48           sub login : Global {
49               my ( $self, $c ) = @_;
50               $c->authenticate( {} );
51           }
52

DESCRIPTION

54       This module allows you to authenticate the users of your Catalyst
55       application on underlaying webserver. The complete list of
56       authentication method available via this module depends just on what
57       your webserver (e.g. Apache, IIS, Lighttpd) is able to handle.
58
59       Besides the common methods like HTTP Basic and Digest authentication
60       you can also use sophisticated ones like so called "integrated
61       authentication" via NTLM or Kerberos (popular in corporate intranet
62       applications running in Windows Active Directory environment) or even
63       the SSL authentication when users authenticate themself using their
64       client SSL certificates.
65
66       The main idea of this module is based on a fact that webserver passes
67       the name of authenticated user into Catalyst application as REMOTE_USER
68       variable (or in case of SSL client authentication in other variables
69       like SSL_CLIENT_S_DN on Apache + mod_ssl) - from this point referenced
70       as WEBUSER.  This module simply takes this value - perfoms some
71       optional checks (see below) - and if everything is OK the WEBUSER is
72       declared as authenticated on Catalyst level. In fact this module does
73       not perform any check for password or other credential; it simply
74       believes the webserver that user was properly authenticated.
75

CONFIG

77   class
78       This config item is REQUIRED.
79
80       class is part of the core Catalyst::Plugin::Authentication module, it
81       contains the class name of the store to be used.
82
83       The classname used for Credential. This is part of
84       Catalyst::Plugin::Authentication and is the method by which
85       Catalyst::Authentication::Credential::Remote is loaded as the
86       credential validator. For this module to be used, this must be set to
87       'Remote'.
88
89   source
90       This config item is OPTIONAL - default is REMOTE_USER.
91
92       source contains a name of a variable passed from webserver that
93       contains the user identification.
94
95       Supported values: REMOTE_USER, SSL_CLIENT_*, CERT_*, AUTH_USER
96
97       BEWARE: Support for using different variables than REMOTE_USER does not
98       work properly with Catalyst 5.8004 and before (if you want details see
99       source code).
100
101       Note1: Apache + mod_ssl uses SSL_CLIENT_S_DN, SSL_CLIENT_S_DN_* etc.
102       (has to be enabled by 'SSLOption +StdEnvVars') or you can also let
103       Apache make a copy of this value into REMOTE_USER (Apache option
104       'SSLUserName SSL_CLIENT_S_DN').
105
106       Note2: Microsoft IIS uses CERT_SUBJECT, CERT_SERIALNUMBER etc. for
107       storing info about client authenticated via SSL certificate. AUTH_USER
108       on IIS seems to have the same value as REMOTE_USER (but there might be
109       some differences I am not aware of).
110
111   deny_regexp
112       This config item is OPTIONAL - no default value.
113
114       deny_regexp contains a regular expression used for check against
115       WEBUSER (see details below)
116
117   allow_regexp
118       This config item is OPTIONAL - no default value.
119
120       deny_regexp contains a regular expression used for check against
121       WEBUSER.
122
123       Allow/deny checking of WEBUSER values goes in this way:
124
125       1) If deny_regexp is defined and WEBUSER matches deny_regexp then
126       authentication FAILS otherwise continues with next step. If deny_regexp
127       is not defined or is an empty string we skip this step.
128
129       2) If allow_regexp is defined and WEBUSER matches allow_regexp then
130       authentication PASSES otherwise FAILS. If allow_regexp is not defined
131       or is an empty string we skip this step.
132
133       The order deny-allow is fixed.
134
135   cutname_regexp
136       This config item is OPTIONAL - no default value.
137
138       If param cutname_regexp is specified we try to cut the final usename
139       passed to Catalyst application as a substring from WEBUSER. This is
140       useful for example in case of SSL authentication when WEBUSER looks
141       like this 'CN=john, OU=Unit Name, O=Company, C=CZ' - from this format
142       we can simply cut pure usename by cutname_regexp set to 'CN=(.*),
143       OU=Unit Name, O=Company, C=CZ'.
144
145       Substring is always taken as '$1' regexp substring. If WEBUSER does not
146       match cutname_regexp at all or if '$1' regexp substring is empty we
147       pass the original WEBUSER value (without cutting) to Catalyst
148       application.
149
150   username_field
151       This config item is OPTIONAL - default is username
152
153       The key name in the authinfo hash that the user's username is mapped
154       into.  This is useful for using a store which requires a specific
155       unusual field name for the username.  The username is additionally
156       mapped onto the id key.
157

METHODS

159   new ( $config, $app, $realm )
160       Instantiate a new Catalyst::Authentication::Credential::Remote object
161       using the configuration hash provided in $config. In case of invalid
162       value of any configuration parameter (e.g. invalid regular expression)
163       throws an exception.
164
165   authenticate ( $realm, $authinfo )
166       Takes the username form WEBUSER set by webserver, performs additional
167       checks using optional allow_regexp/deny_regexp configuration params,
168       optionaly takes substring from WEBUSER and the sets the resulting value
169       as a Catalyst username.
170

COMPATIBILITY

172       It is strongly recommended to use this module with Catalyst 5.80005 and
173       above as previous versions have some bugs related to $c->engine->env
174       and do not support $c->req->remote_user.
175
176       This module tries some workarounds when it detects an older version and
177       should work as well.
178

USING WITH A REVERSE PROXY

180       If you are using a reverse proxy, then the WEBUSER will not be directly
181       accessible by the Catalyst server.  To use remote authentication, you
182       will have to modify the web server to set a header containing the
183       WEBUSER.  You would then need to modify the PSGI configuration to map
184       the header back to the WEBUSER variable.
185
186       For example, in Apache you would add the configuration
187
188         RequestHeader unset X-Forwarded-User
189         RewriteEngine On
190         RewriteCond %{LA-U:REMOTE_USER} (.+)
191         RewriteRule . - [E=RU:%1]
192         RequestHeader set X-Forwarded-User %{RU}e
193
194       You then need to create a Plack::Middleware module to map the header
195       back to the WEBUSER:
196
197         package Plack::Middleware::MyRemote;
198
199         use parent qw( Plack::Middleware );
200
201         use Plack::Util;
202
203         sub call {
204             my ($self, $env) = @_;
205
206             my $user = $env->{HTTP_X_FORWARDED_USER} // "";
207
208             $env->{REMOTE_USER} = $user
209               if ($user && ($user ne '(null)'));
210
211             my $res = $self->app->($env);
212
213             return $res;
214         }
215
216         1;
217
218       Finally, you need to modify myapp.psgi to use the custom middleware:
219
220         use strict;
221         use warnings;
222
223         use MyApp;
224
225         use Plack::Builder;
226
227         my $app = Drain->apply_default_middlewares(Drain->psgi_app);
228
229         builder {
230            enable "Plack::Middleware::MyRemote";
231            $app;
232         };
233
234
235
236perl v5.32.1                   Cat2a0l2y1s-t0:1:-A2u6thentication::Credential::Remote(3)
Impressum