The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache2-AuthEnv-v1.3.8
River stage zero No dependents
++
/ Apache2::AuthEnv

NAME

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

SYNOPSIS

 ### In httpd.conf file (required to load the directives).
 PerlLoadModule Apache2::AuthEnv

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

 # turn on logging
 AuthEnvLogInfo On

 # Also possible is setting the remote user from a list 
 # of alternative environment variables or a default value.
 AuthEnvUser %{HTTP_XX_USER|HTTP_YY_USER:anon}

 # 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/

 # Load environment settings from a DBM database.
 AuthEnvDbImport   HTTP_EXTRA_ /etc/dbfile Key

 # 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=....'

 AuthEnvAllowAll
 AuthEnvDenyAll

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

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

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

Some systems may take authentication information from various sources and provide different environment variables for each source. So you can list alternative variables to use. AuthEnvUser %{HTTP_SOURCE1_NAME|HTTP_SOURCE2_NAME|HTTP_SOURCE3_NAME}

If nothing matches then you can set a default value (say 'anon') via AuthEnvUser %{HTTP_SOURCE_NAME|HTTP_SOURCE2_NAME:anon}

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_FOUND

FORMAT

The substitution format is composed of strings of characters and variable substitutions starting with '%{' and ending in '}'. Substitutions are of the following formats:

  • %{ENVIRONMENT_VARIABLE_NAME},

  • %{ENVIRONMENT_VARIABLE_NAME1|ENVIRONMENT_VARIABLE_NAME2|....}

  • %{ENVIRONMENT_VARIABLE_NAME:default}.

In the first case, the value of the environment variable is simply substituted. If a '|' separated list of variables is specified then each variable is checked in order, substituting the value of the first that is not empty. If no substitution succeeds and there is a default specified then that value is used instead.

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

    PerlLoadModule Apache2::AuthEnv

PerlLoadModule, rather than PerlModule, is required to load this module as it implements new Apache directives.

  • 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. Any prior authorisation lists are cleared.

    This directive is allowed in exactly the same contexts as the Require directive.

  • AuthEnvDbImport <prefix> <datebase-file> <key-format>

    This imports extra environment variables from a database for that particular value of the key-format. The database is created via the MLDBM and BerkeleyDB::Btree packages.

  • 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.

  • AuthEnvAllowFile <file>

  • AuthEnvDenyFile <file>

    These directives allow or deny, respectively, any users from the specified file.

  • AuthEnvAllowAll

    This directive allows any connection that hasn't been denied up to now. This is useful to allow all users to access the controlled area.

  • AuthEnvDenyAll

    This directive denies any connection that hasn't been allowed up to now. This is really the default action but included for completeness. It is useful when an area needs to be temporarily denied but the rest of the configuration needs to stay intact.

  • AuthEnvDenial UNAUTHORISED|UNAUTHORIZED|NOT_FOUND|FORBIDDEN

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

  • AuthEnvLogInfo On|Off

    Turn on or off extra logging about which users are getting allowed or denied by various rules. The default is no logging to reduce log sizes.

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).