Cataly...Remote(3pm)

💅 NAME 💅

Okay so this is the User Contributed Perl Documentation page for Catalyst::Authentication::Credential::Remote — manual name Cataly...Remote(3pm), iykyk — and it's literally: Let the webserver (e.g. Apache) authenticate Catalyst application users. 💖

✨ SYNOPSIS ✨

First up, in your MyApp.pm, you set it up like this, bestie:

# 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
                }
            },
        },
    },

);

Then in your Controller/Root.pm you can implement "auto-login" like this:

# 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 an ordinary login action in any controller like this:

# or you can implement in any controller an ordinary login action like this
sub login : Global {
    my ( $self, $c ) = @_;
    $c->authenticate( {} );
}

🌸 DESCRIPTION 🌸

This module lets you authenticate the users of your Catalyst app on the underlying webserver. The complete list of authentication methods available via this module depends just on what your webserver (e.g. Apache, IIS, Lighttpd) is able to handle. No cap.

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 a Windows Active Directory environment) or even SSL authentication when users authenticate themselves using their client SSL certificates. It's giving range. ✨

The main idea of this module is based on a fact: the webserver passes the name of the authenticated user into the Catalyst application as the REMOTE_USER variable (or, in the 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, performs some optional checks (see below), and if everything is OK, the WEBUSER is declared as authenticated on the Catalyst level. In fact, this module does not perform any check for password or other credential; it simply believes the webserver that the user was properly authenticated. Periodt.

🎀 CONFIG 🎀

Okay, config time. Here's the whole menu, bestie. 🍓

class

REQUIRED, babes.

class is part of the core Catalyst::Plugin::Authentication module, and 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'. Slay.

source

OPTIONAL — default is REMOTE_USER.

source contains a name of a variable passed from the 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). Lowkey important.

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 a 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

OPTIONAL — no default value.

deny_regexp contains a regular expression used for check against WEBUSER (see details below). It's giving gatekeeper energy. 💅

allow_regexp

OPTIONAL — no default value.

The page's own line here says deny_regexp contains a regular expression used for check against WEBUSER — yes, that's the wording, we're keeping it, no cap. The actual allow/deny logic is below and it's the main character. 👑

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 it continues with the 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 it FAILS. If allow_regexp is not defined or is an empty string, we skip this step.

The order deny-allow is fixed. Periodt.

cutname_regexp

OPTIONAL — no default value.

If param cutname_regexp is specified, we try to cut the final username passed to the Catalyst application as a substring from WEBUSER. This is useful, for example, in the 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 the pure username by setting cutname_regexp to 'CN=(.*), OU=Unit Name, O=Company, C=CZ'.

The substring is always taken as the '$1' regexp substring. If WEBUSER does not match cutname_regexp at all, or if the '$1' regexp substring is empty, we pass the original WEBUSER value (without cutting) to the Catalyst application. No cap.

username_field

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 an invalid value of any configuration parameter (e.g. an invalid regular expression), it throws an exception. Iconic behavior. 💅

authenticate ( $realm, $authinfo )

Takes the username from WEBUSER set by the webserver, performs additional checks using the optional allow_regexp/deny_regexp configuration params, optionally takes a substring from WEBUSER, and then sets the resulting value as a Catalyst username. Fr fr.

💖 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. Ngl, it's trying its best. 🫶

🦋 USING WITH A REVERSE PROXY 🦋

If you're using a reverse proxy, then the WEBUSER will not be directly accessible by the Catalyst server. To use remote authentication, you'll have to modify the web server to set a header containing the WEBUSER. You'd then need to modify the PSGI configuration to map the header back to the WEBUSER variable.

For example, in Apache you'd add the configuration:

RequestHeader unset X-Forwarded-User
RewriteEngine On
RewriteCond %{LA-U:REMOTE_USER} (.+)
RewriteRule . - [E=RU:%1]
RequestHeader set X-Forwarded-User %{RU}e

You then need to create a Plack::Middleware module to map the header back to the WEBUSER:

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 '(null)'));

    my $res = $self->app->($env);

    return $res;
}

1;

Finally, you need to modify myapp.psgi to use the custom middleware:

use strict;
use warnings;

use MyApp;

use Plack::Builder;

my $app = Drain->apply_default_middlewares(Drain->psgi_app);

builder {
   enable "Plack::Middleware::MyRemote";
   $app;
};

That's the whole page, bestie. Sign-off time: perl v5.40.1, date-stamped 2026-05-22, manual name Cataly...Remote(3pm) — mwah 💋✨