.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Catalyst::Authentication::Credential::Remote 3pm"
.TH Catalyst::Authentication::Credential::Remote 3pm "2023-01-22" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Catalyst::Authentication::Credential::Remote \- Let the webserver (e.g. Apache)
authenticate Catalyst application users
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    # in your MyApp.pm
\&    _\|_PACKAGE_\|_\->config(
\&
\&        \*(AqPlugin::Authentication\*(Aq => {
\&            default_realm => \*(Aqremoterealm\*(Aq,
\&            realms => {
\&                remoterealm => {
\&                    credential => {
\&                        class        => \*(AqRemote\*(Aq,
\&                        allow_regexp => \*(Aq^(user.*|admin|guest)$\*(Aq,
\&                        deny_regexp  => \*(Aqtest\*(Aq,
\&                    },
\&                    store => {
\&                        class => \*(AqNull\*(Aq,
\&                        # 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( {} );
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "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, \s-1IIS,\s0 Lighttpd)
is able to handle.
.PP
Besides the common methods like \s-1HTTP\s0 Basic and Digest authentication you can
also use sophisticated ones like so called \*(L"integrated authentication\*(R" via
\&\s-1NTLM\s0 or Kerberos (popular in corporate intranet applications running in Windows
Active Directory environment) or even the \s-1SSL\s0 authentication when users 
authenticate themself using their client \s-1SSL\s0 certificates.
.PP
The main idea of this module is based on a fact that webserver passes the name
of authenticated user into Catalyst application as \s-1REMOTE_USER\s0 variable (or in 
case of \s-1SSL\s0 client authentication in other variables like \s-1SSL_CLIENT_S_DN\s0 on
Apache + mod_ssl) \- from this point referenced as \s-1WEBUSER.\s0 
This module simply takes this value \- perfoms some optional checks (see
below) \- and if everything is \s-1OK\s0 the \s-1WEBUSER\s0 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.
.SH "CONFIG"
.IX Header "CONFIG"
.SS "class"
.IX Subsection "class"
This config item is \fB\s-1REQUIRED\s0\fR.
.PP
\&\fBclass\fR is part of the core Catalyst::Plugin::Authentication module, it 
contains the class name of the store to be used.
.PP
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'.
.SS "source"
.IX Subsection "source"
This config item is \fB\s-1OPTIONAL\s0\fR \- default is \s-1REMOTE_USER.\s0
.PP
\&\fBsource\fR contains a name of a variable passed from webserver that contains the 
user identification.
.PP
Supported values: \s-1REMOTE_USER,\s0 SSL_CLIENT_*, CERT_*, \s-1AUTH_USER\s0
.PP
\&\fB\s-1BEWARE:\s0\fR Support for using different variables than \s-1REMOTE_USER\s0 does not work 
properly with Catalyst 5.8004 and before (if you want details see source code).
.PP
Note1: Apache + mod_ssl uses \s-1SSL_CLIENT_S_DN,\s0 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 \s-1REMOTE_USER\s0 (Apache option 'SSLUserName \s-1SSL_CLIENT_S_DN\s0').
.PP
Note2: Microsoft \s-1IIS\s0 uses \s-1CERT_SUBJECT, CERT_SERIALNUMBER\s0 etc. for storing info
about client authenticated via \s-1SSL\s0 certificate. \s-1AUTH_USER\s0 on \s-1IIS\s0 seems to have
the same value as \s-1REMOTE_USER\s0 (but there might be some differences I am not
aware of).
.SS "deny_regexp"
.IX Subsection "deny_regexp"
This config item is \fB\s-1OPTIONAL\s0\fR \- no default value.
.PP
\&\fBdeny_regexp\fR contains a regular expression used for check against \s-1WEBUSER\s0 
(see details below)
.SS "allow_regexp"
.IX Subsection "allow_regexp"
This config item is \fB\s-1OPTIONAL\s0\fR \- no default value.
.PP
\&\fBdeny_regexp\fR contains a regular expression used for check against \s-1WEBUSER.\s0
.PP
Allow/deny checking of \s-1WEBUSER\s0 values goes in this way:
.PP
1) If \fBdeny_regexp\fR is defined and \s-1WEBUSER\s0 matches deny_regexp then 
authentication \s-1FAILS\s0 otherwise continues with next step. If deny_regexp is not 
defined or is an empty string we skip this step.
.PP
2) If \fBallow_regexp\fR is defined and \s-1WEBUSER\s0 matches allow_regexp then 
authentication \s-1PASSES\s0 otherwise \s-1FAILS.\s0 If allow_regexp is not 
defined or is an empty string we skip this step.
.PP
The order deny-allow is fixed.
.SS "cutname_regexp"
.IX Subsection "cutname_regexp"
This config item is \fB\s-1OPTIONAL\s0\fR \- no default value.
.PP
If param \fBcutname_regexp\fR is specified we try to cut the final usename passed to
Catalyst application as a substring from \s-1WEBUSER.\s0 This is useful for 
example in case of \s-1SSL\s0 authentication when \s-1WEBUSER\s0 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'.
.PP
Substring is always taken as '$1' regexp substring. If \s-1WEBUSER\s0 does not
match cutname_regexp at all or if '$1' regexp substring is empty we pass the
original \s-1WEBUSER\s0 value (without cutting) to Catalyst application.
.SS "username_field"
.IX Subsection "username_field"
This config item is \fB\s-1OPTIONAL\s0\fR \- default is \fIusername\fR
.PP
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 \fIid\fR key.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS "new ( $config, $app, $realm )"
.el .SS "new ( \f(CW$config\fP, \f(CW$app\fP, \f(CW$realm\fP )"
.IX Subsection "new ( $config, $app, $realm )"
Instantiate a new Catalyst::Authentication::Credential::Remote object using the
configuration hash provided in \f(CW$config\fR. In case of invalid value of any 
configuration parameter (e.g. invalid regular expression) throws an exception.
.ie n .SS "authenticate ( $realm, $authinfo )"
.el .SS "authenticate ( \f(CW$realm\fP, \f(CW$authinfo\fP )"
.IX Subsection "authenticate ( $realm, $authinfo )"
Takes the username form \s-1WEBUSER\s0 set by webserver, performs additional 
checks using optional allow_regexp/deny_regexp configuration params, optionaly 
takes substring from \s-1WEBUSER\s0 and the sets the resulting value as
a Catalyst username.
.SH "COMPATIBILITY"
.IX Header "COMPATIBILITY"
It is \fBstrongly recommended\fR to use this module with Catalyst 5.80005 and above
as previous versions have some bugs related to \f(CW$c\fR\->engine\->env and do not 
support \f(CW$c\fR\->req\->remote_user.
.PP
This module tries some workarounds when it detects an older version and should
work as well.
.SH "USING WITH A REVERSE PROXY"
.IX Header "USING WITH A REVERSE PROXY"
If you are using a reverse proxy, then the \s-1WEBUSER\s0 will not be
directly accessible by the Catalyst server.  To use remote
authentication, you will have to modify the web server to set a header
containing the \s-1WEBUSER.\s0  You would then need to modify the \s-1PSGI\s0
configuration to map the header back to the \s-1WEBUSER\s0 variable.
.PP
For example, in Apache you would add the configuration
.PP
.Vb 5
\&  RequestHeader unset X\-Forwarded\-User
\&  RewriteEngine On
\&  RewriteCond %{LA\-U:REMOTE_USER} (.+)
\&  RewriteRule . \- [E=RU:%1]
\&  RequestHeader set X\-Forwarded\-User %{RU}e
.Ve
.PP
You then need to create a Plack::Middleware module to map the
header back to the \s-1WEBUSER:\s0
.PP
.Vb 1
\&  package Plack::Middleware::MyRemote;
\&
\&  use parent qw( Plack::Middleware );
\&
\&  use Plack::Util;
\&
\&  sub call {
\&      my ($self, $env) = @_;
\&
\&      my $user = $env\->{HTTP_X_FORWARDED_USER} // "";
\&
\&      $env\->{REMOTE_USER} = $user
\&        if ($user && ($user ne \*(Aq(null)\*(Aq));
\&
\&      my $res = $self\->app\->($env);
\&
\&      return $res;
\&  }
\&
\&  1;
.Ve
.PP
Finally, you need to modify \fImyapp.psgi\fR to use the custom middleware:
.PP
.Vb 2
\&  use strict;
\&  use warnings;
\&
\&  use MyApp;
\&
\&  use Plack::Builder;
\&
\&  my $app = Drain\->apply_default_middlewares(Drain\->psgi_app);
\&
\&  builder {
\&     enable "Plack::Middleware::MyRemote";
\&     $app;
\&  };
.Ve