NAME

Apache2::AuthEnv - Perl Authentication and Authorisation via Environment Variables.

SYNOPSIS

 ### In httpd.conf file (required to load the directives).
 PerlOptions +GlobalRequest
 PerlModule Apache2::AuthEnv

 ### In httpd.conf or .htaccess: ################
 # Set the remote user and trigger the auth* stages
 AuthEnvVar %{REMOTE_ADDR}@%{SOME_ENV_VAR}

 # Set extra environment variables.
 AuthEnvSet     HTTP_AE_SERVER  %{SERVER_ADDR}:%{SERVER_PORT}

 # Allow and Deny access based on environment.
 # The default is to deny access.
 # Allow and deny rules are evaluated based on their order in this file.
 AuthEnvAllowUser       fred@here.org
 AuthEnvDenyUser        george@here.org
 AuthEnvAllowMatch      %{HTTP_USER_AGENT}      ^Mozilla
 AuthEnvDeny            %{REMOTE_ADDR}          192.168.2.3
 AuthEnvDenyMatch       %{HTTP_USER_AGENT}      Fedora
 AuthEnvAllow           %{SERVER_PORT} 80

 AuthEnvDenial          UNAUTHORISED|UNAUTHORIZED|NOT_FOUND|FORBIDDEN

DESCRIPTION

Apache2::AuthEnv allows you to promote a string composed of CGI environment variables to act as an authenticated user. The format is set via the AuthEnvVar command and the result is placed in the environment variable REMOTE_USER.

This module is for use only when another Apache module pre-authenticates and pre-authorises a user but does not provide authentication nor authorisation controls within Apache.

This module, once loaded, is triggered by the Apache directive AuthEnvVar setting a format from the environment for the remote user name. Authorisation is controlled by AuthEnvAllow* and AuthEnvDeny* directives. The default is to deny authorisation to everyone.

  AuthEnvVar            %{HTTP_SSO_USER}@%{HTTP_SSO_ORG}
  AuthEnvAllowUser      fred@ORG

Such a system is Computer Asscoiates' SiteMinder (c) Single Sign On solution. Only pre-authenticated and pre-authorised users are allowed through to protected URLs. However there is no local control by the local web server. SiteMinder sets various environment variables including HTTP_SM_USER and HTTP_SM_AUTHDIRNAME. So a reasonable setting would be

  AuthEnvVar            %{HTTP_SM_USER}@%{HTTP_SM_AUTHDIRNAME}
  AuthEnvAllowUser      fred@ORG

Another example is AuthEnvVar %{HTTP_UI_PRINCIPAL_NAME} AuthEnvAllowUser fred@ORG.org AuthEnvAllow %{HTTP_UI_DEPARTMENT} sales

For nested directives, configurations are inherited from one configuration file to the next. AuthEnvVar directives overwrite each other as do collections of AuthEnvAllow* rules. Each individual AuthEnvSet, unless overwriten, is inherited.

The default denial code returned to the browser is FORBIDDEN. The directive AuthEnvDenial can be used to change the return code. For example,

  AuthEnvDenial         NOT_FOUND

METHODS

• handler()

  This is the method used as augument to the PerlAuthenHandler or the PerlAuthzHandler directives in .htaccess and httpd.conf files.

• authenticate()

  This is the method used as augument to the the PerlAuthenHandler directive in .htaccess and httpd.conf files.

• authorise()

  This is the method used as augument to the the PerlAuthzHandler directive in .htaccess and httpd.conf files.

APACHE DIRECTIVES

In the Apache configuration file httpd.conf, the module must be loaded

PerlOptions +GlobalRequest

PerlModule Apache2::AuthEnv

• AuthEnvVar <format>

  This turns on the authentication and authorisation stages and sets the format for the remote user name, which is filled in during authentication.

• AuthEnvSet <variable> <format>

  This sets the specified environment variable using the sepcified format.

• AuthEnvAllowUser <user>

• AuthEnvDenyUser <user>

  These allow or deny the specified user.

• AuthEnvAllow <format> <value>

• AuthEnvAllowMatch <format> <regex>

• AuthEnvDeny <format> <value>

• AuthEnvDenyMatch <format> <regex>

  These directives allow or deny depending on the environment variables. Those that end in Match match the environment against a Perl regular repression and the others require exact matches.

  These allow or deny the specified user.

• AuthEnvAllowSplit <format> <split> <value>

• AuthEnvAllowSplitMatch <format> <split> <regex>

• AuthEnvDenySplit <format> <split> <value>

• AuthEnvDenySplitMatch <format> <split> <regex>

  These directives allow or deny depending on the environment variables. The formatted string is first split according to the regular expression split and then each component is considered separately. Those that end in Match match the environment against a Perl regular repression and the others require exact matches.

  This is useful for environment variables that are really lists of values delimited with a specific value.

• AuthEnvDenial UNAUTHORISED|UNAUTHORIZED|NOT_FOUND|FORBIDDEN

  This directive sets the HTTP denial code returned to the browser if authorisation fails. The default is FORBIDDEN.

AUTHOR

Anthony R Fletcher arif@cpan.org

COPYRIGHT

Copyright (c) 2008 Anthony R Fletcher. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. It is supplied on an-is basis and there is no warrenty of any kind.

SiteMinder (c) is owned by Computer Asscoiates. This module does not rely on or use any part of SiteMinder and works purely via the environemnt within mod_perl.

SEE ALSO

perl(1), mod_perl(1), Apache(1).