Catalyst::AuthenticatiUserCContCatalyst::Authentication::Credential::Remote(3)NAMECatalyst::Authentication::Credential::Remote - Let the webserver (e.g.
Apache) authenticate Catalyst application users
SYNOPSIS
# in your MyApp.pm
__PACKAGE__->config(
'Plugin::Authentication' => {
default_realm => 'remoterealm',
realms => {
remoterealm => {
credential => {
class => 'Remote',
allow_regexp => '^(user.*|admin|guest)$',
deny_regexp => 'test',
},
store => {
class => 'Null',
# if you want to have some additional user attributes
# like user roles, user full name etc. you can specify
# here the store where you keep this data
}
},
},
},
);
# in your Controller/Root.pm you can implement "auto-login" in this way
sub begin : Private {
my ( $self, $c ) = @_;
unless ($c->user_exists) {
# authenticate() for this module does not need any user info
# as the username is taken from $c->req->remote_user and
# password is not needed
unless ($c->authenticate( {} )) {
# return 403 forbidden or kick out the user in other way
};
}
}
# or you can implement in any controller an ordinary login action like this
sub login : Global {
my ( $self, $c ) = @_;
$c->authenticate( {} );
}
DESCRIPTION
This module allows you to authenticate the users of your Catalyst
application on underlaying webserver. The complete list of
authentication method available via this module depends just on what
your webserver (e.g. Apache, IIS, Lighttpd) is able to handle.
Besides the common methods like HTTP Basic and Digest authentication
you can also use sophisticated ones like so called "integrated
authentication" via NTLM or Kerberos (popular in corporate intranet
applications running in Windows Active Directory environment) or even
the SSL authentication when users authenticate themself using their
client SSL certificates.
The main idea of this module is based on a fact that webserver passes
the name of authenticated user into Catalyst application as REMOTE_USER
variable (or in case of SSL client authentication in other variables
like SSL_CLIENT_S_DN on Apache + mod_ssl) - from this point referenced
as WEBUSER. This module simply takes this value - perfoms some
optional checks (see below) - and if everything is OK the WEBUSER is
declared as authenticated on Catalyst level. In fact this module does
not perform any check for password or other credential; it simply
believes the webserver that user was properly authenticated.
CONFIG
class
This config item is REQUIRED.
class is part of the core Catalyst::Plugin::Authentication module, it
contains the class name of the store to be used.
The classname used for Credential. This is part of
Catalyst::Plugin::Authentication and is the method by which
Catalyst::Authentication::Credential::Remote is loaded as the
credential validator. For this module to be used, this must be set to
'Remote'.
source
This config item is OPTIONAL - default is REMOTE_USER.
source contains a name of a variable passed from webserver that
contains the user identification.
Supported values: REMOTE_USER, SSL_CLIENT_*, CERT_*, AUTH_USER
BEWARE: Support for using different variables than REMOTE_USER does not
work properly with Catalyst 5.8004 and before (if you want details see
source code).
Note1: Apache + mod_ssl uses SSL_CLIENT_S_DN, SSL_CLIENT_S_DN_* etc.
(has to be enabled by 'SSLOption +StdEnvVars') or you can also let
Apache make a copy of this value into REMOTE_USER (Apache option
'SSLUserName SSL_CLIENT_S_DN').
Note2: Microsoft IIS uses CERT_SUBJECT, CERT_SERIALNUMBER etc. for
storing info about client authenticated via SSL certificate. AUTH_USER
on IIS seems to have the same value as REMOTE_USER (but there might be
some differences I am not aware of).
deny_regexp
This config item is OPTIONAL - no default value.
deny_regexp contains a regular expression used for check against
WEBUSER (see details below)
allow_regexp
This config item is OPTIONAL - no default value.
deny_regexp contains a regular expression used for check against
WEBUSER.
Allow/deny checking of WEBUSER values goes in this way:
1) If deny_regexp is defined and WEBUSER matches deny_regexp then
authentication FAILS otherwise continues with next step. If deny_regexp
is not defined or is an empty string we skip this step.
2) If allow_regexp is defined and WEBUSER matches allow_regexp then
authentication PASSES otherwise FAILS. If allow_regexp is not defined
or is an empty string we skip this step.
The order deny-allow is fixed.
cutname_regexp
This config item is OPTIONAL - no default value.
If param cutname_regexp is specified we try to cut the final usename
passed to Catalyst application as a substring from WEBUSER. This is
useful for example in case of SSL authentication when WEBUSER looks
like this 'CN=john, OU=Unit Name, O=Company, C=CZ' - from this format
we can simply cut pure usename by cutname_regexp set to 'CN=(.*),
OU=Unit Name, O=Company, C=CZ'.
Substring is always taken as '$1' regexp substring. If WEBUSER does not
match cutname_regexp at all or if '$1' regexp substring is empty we
pass the original WEBUSER value (without cutting) to Catalyst
application.
username_field
This config item is OPTIONAL - default is username
The key name in the authinfo hash that the user's username is mapped
into. This is useful for using a store which requires a specific
unusual field name for the username. The username is additionally
mapped onto the id key.
METHODS
new ( $config, $app, $realm )
Instantiate a new Catalyst::Authentication::Credential::Remote object
using the configuration hash provided in $config. In case of invalid
value of any configuration parameter (e.g. invalid regular expression)
throws an exception.
authenticate ( $realm, $authinfo )
Takes the username form WEBUSER set by webserver, performs additional
checks using optional allow_regexp/deny_regexp configuration params,
optionaly takes substring from WEBUSER and the sets the resulting value
as a Catalyst username.
COMPATIBILITY
It is strongly recommended to use this module with Catalyst 5.80005 and
above as previous versions have some bugs related to $c->engine->env
and do not support $c->req->remote_user.
This module tries some workarounds when it detects an older version and
should work as well.
perl v5.14.1Catalyst::Authentication::Credential::Remote(3)
