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
AuthEnvUser %{REMOTE_ADDR}@%{SOME_ENV_VAR}
# Set extra environment variables.
AuthEnvSet HTTP_AE_SERVER %{SERVER_ADDR:unknown}:%{SERVER_PORT:unknown}
AuthEnvChange HTTP_AE_SERVER s/:/!/g
AuthEnvChange HTTP_AE_SERVER tr/a-z/A-Z/
# 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
AuthEnvAllowSplit %{HTTP_MEMBEROF} '\^' 'CN=....'
AuthEnvDenial UNAUTHORISED|UNAUTHORIZED|NOT_FOUND|FORBIDDENDESCRIPTION
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 AuthEnvUser 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 AuthEnvUser 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.
AuthEnvUser %{HTTP_SSO_USER}@%{HTTP_SSO_ORG}
AuthEnvAllowUser fred@ORGSuch 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
AuthEnvUser %{HTTP_SM_USER}@%{HTTP_SM_AUTHDIRNAME}
AuthEnvAllowUser fred@ORGAnother example is AuthEnvUser %{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. AuthEnvUser directives overwrite each other as do collections of AuthEnvAllow* rules. Each individual AuthEnvSet and AuthEnvChange directive, 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_FOUNDFORMAT
The substitution format is composed of strings of characters and variable substitutions starting with '%{' and ending in '}'. The substitution are either %{ENVIRONMENT_VARIABLE_NAME} or %{ENVIRONMENT_VARIABLE_NAME:default}. In the former case, the environment variable is simply substituted. In the latter, if the environment variable doesn't exist then the default string following the colon is used.
To use formats with spaces in the .htaccess file, enclose the format in double quotes.
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
AuthEnvUser <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.
AuthEnvSet <variable> <perl-substitution>
This changes the specified environment variable according to the following Perl substitution. Modifications to REMOTE_USER are allowed.
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.
Note that the <split> string is a regular expression and needs to be escaped appropiately; e.g. split on '\^' not on '^' as the latter just splits on the beginning of the string and is probably not what you want.
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.