NAME

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

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

METHODS

COMPATIBILITY

This module tries some workarounds when it detects an older version and should work as well.

USING WITH A REVERSE PROXY

For example, in Apache you would 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;
  };