1Catalyst::AuthenticatioUns:e:rCrCeodnetnrCtiaibtaualtl:ey:dsRteP:me:orAtluet(Dh3oe)cnutmiecnattaitoino:n:Credential::Remote(3)
2
6 Catalyst::Authentication::Credential::Remote - Let the webserver (e.g.
7 Apache) authenticate Catalyst application users
8
10 # in your MyApp.pm
11 __PACKAGE__->config(
12 '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 );
33 # 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 # 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
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 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 enviroment) or even
63 the SSL authentication when users authenticate themself using their
64 client SSL certificates.
65 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
77 class
78 This config item is REQUIRED.
79 class is part of the core Catalyst::Plugin::Authentication module, it
81 contains the class name of the store to be used.
82 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 source
90 This config item is OPTIONAL - default is REMOTE_USER.
91 source contains a name of a variable passed from webserver that
93 contains the user identification.
94 Supported values: REMOTE_USER, SSL_CLIENT_*, CERT_*, AUTH_USER
96 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 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 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 deny_regexp
112 This config item is OPTIONAL - no default value.
113 deny_regexp contains a regular expression used for check against
115 WEBUSER (see details below)
116 allow_regexp
118 This config item is OPTIONAL - no default value.
119 deny_regexp contains a regular expression used for check against
121 WEBUSER.
122 Allow/deny checking of WEBUSER values goes in this way:
124 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 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 The order deny-allow is fixed.
134 cutname_regexp
136 This config item is OPTIONAL - no default value.
137 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 usefull 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 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 username_field
151 This config item is OPTIONAL - default is username
152 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
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 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
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 This module tries some workarounds when it detects an older version and
177 should work as well.
178perl v5.12.0 Cat2a0l0y9s-t1:0:-A1u7thentication::Credential::Remote(3)