DownloadingThe latest version of mod_auth_pamacea is available here.
Copyright and LicenseCopyright (c) 2003 - 2007, The Trustees of Columbia University in the City of New York.
Benjamin Oshrin, Columbia University Information Technology
This product includes software developed by the Apache Software Foundation (http://www.apache.org/).
This notice is part of the version 3.0 release of mod_auth_pamacea.
mod_auth_pamacea is free software; you can redistribute and/or modify version 3.0 (including any bug fix releases of this version, identified by a lowercase letter appended to the version number) under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
mod_auth_pamacea is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
Overviewmod_auth_pamacea is an Apache 2 module that performs PAM based authentication using a customizable login form. Specifically, Basic Auth is not used because there is no feasible logout mechanism from a Basic Auth session, short of closing the browser. Limited authorization support is also provided.
There is no Apache 1 version of this module.
mod_auth_pamacea was written to replace a much older, home grown Apache 1 module that nobody understood anymore. While mod_auth_pamacea is also homegrown, it attempts to use whatever standards it can to increase the likelihood that others will find it useful, or at least minimally to ensure that somebody will be able to understand it in the future.
Is It Really A Pamacea?No. There are no known pamaceas.
BuildingBuilding the module is relatively straightforward, but requires Apache 2 to already be installed. Untar the distribution, select a language and a session manager, and let Apache's apxs do all the work.
Selecting a LanguageUnder certain circumstances, the module will need to generate a message, usually an error message. By default, these messages will appear in English. To change the default, remove the texts.h symlink and create a new link pointing to the file containing the appropriate language.
% rm texts.h % ln -s texts_LL_CC.h texts.hNote: As of this version, no other languages are included with the distribution. To create a new language file, copy texts_en_US.h to an appropriately named file and change the string definitions.
Selecting a Session ManagerBecause the module does not use Basic Auth, it must maintain session information. By default the file-based session manager is used. The file-based session manager is suitable for low volume servers where a client will always (or for the length of the session) talk to the same server. While it is possible to use the file-based session manager across multiple servers, this configuration is not recommended. See installing the session manager for more information.
To change the default, remove the session_manager.c symlink and create a new link pointing to the file containing the appropriate session manager.
% rm session_manager.c % ln -s session_manager_XX.c session_manager.cNote: As of this version, no other session managers are included with the distribution. To create a new session manager, copy session_manager_file.c to an appropriately named file and reimplement the functions defined in session_manager.h.
Compiling the ModuleTo compile the module, simply cd into the distribution directory and type make. apxs must be in your $PATH, or else the full path to it must be set in Makefile's APXS= line. (apxs can normally be found in the sbin or bin subdirectory of the Apache 2 installation.)
Note: There are several options that may be changed at compile time in mod_auth_pamacea.h, including the name of the .htaccess AuthType directive that invokes the module.
Note for HP-UX: If you see errors about pam_getenv, pam_putenv, and pam_getenvlist being unresolved symbols, you can try defining _WITHOUT_PAMENV in mod_auth_pamacea.h. This should allow the module to compile, however the PamaceaGroupSource PAMEnv, PamaceaPAMConfirmUserFile, and PamaceaSetEnv PAMEnv directives will be disabled.
InstallingInstallation consists of installing the module, setting up the session manager, and adding the appropriate directives to httpd.conf.
Important: If you install this module, please subscribe to the pamacea-announce mailing list. Notification of security updates will be made to this list.
Installing the ModuleTo install the module, as root type make install. Alternately, copy .libs/mod_auth_pamacea.so to the modules subdirectory of the Apache 2 installation.
Installing the Session Manager
File-Based Session ManagerOn the web server, create the directory /var/pamacea (or, if PAMACEA_STATEDIR was changed in session_manager_file.h, whatever it was changed to). Make the directory writable by the user that the Apache web server runs as and inaccessible by everybody else. For example,
# mkdir /var/pamacea # chown www /var/pamacea # chmod 700 /var/pamaceaIf there are multiple web servers in a pool, sharing this directory by NFS should work, but is not recommended.
Preparing the Required Web PagesThere are four special pages that mod_auth_pamacea knows about. These pages should be prepared and installed before the module is installed. Samples of each page are provided in the samples directory of the distribution.
Note: These pages should be placed in a directory that is not protected by mod_auth_pamacea (ie: that has no .htaccess file). Additionally, any files or images these pages reference should also not be protected by the module.
<META HTTP-EQUIV="Expires" CONTENT="-1"> <META HTTP-EQUIV="Pragma" CONTENT="no_cache"> <META HTTP-EQUIV="Cache-Control" CONTENT="no cache">See also PamaceaNoCache for information on browsers caching content documents.
Editing pam.confThe module can use any service name for performing PAM authentication. Either define a new service in /etc/pam.conf (or /etc/pam.d/, as appropriate) or select an existing service to be used. The module can use more than one service name, on a per-directory basis.
Note: Because mod_auth_pamacea collects the username and password from a web page, the PAM must be configured to not prompt for them. Normally, this is done by setting the use_first_pass flag for the PAM module used by the selected service name. However, due to the implementation of Linux PAMs, this flag should not be used under Linux (or Darwin). (mod_auth_pamacea implements a workaround instead.)
For installations where more than one PAM service may be used, see PamaceaSingleSignOnMode.
Editing httpd.confMinimally, the following directives should be added to httpd.conf:
LoadModule auth_pamacea_module modules/mod_auth_pamacea.so PamaceaLoginPage /pamacea/login.html PamaceaLogoutPage /pamacea/logout.html PamaceaErrorPage /pamacea/error.html PamaceaNoCookieURI /pamacea/nocookie.html PamaceaPermittedPAMService secureweb PamaceaPAMService securewebAfter restarting Apache, look in Apache's error log for any information regarding configuration errors.
For installations where one server is used to serve both HTTP and HTTPS, see PamaceaNoSSL, which may need to be set to Decline.
Editing .htaccessMinimally, the following directives need to be added to any .htaccess file using mod_auth_pamacea:
AuthType Pamacea AuthName "test" Require valid-userRemember that AllowOverride AuthConfig must be specified in an appropriate Directory segment of httpd.conf, or Apache will ignore the .htaccess file.
Configuration File DirectivesUnless otherwise noted, these directives may only be placed in the server's httpd.conf file.
PamaceaAuthLogLevelUsage: PamaceaAuthLogLevel [level]
Example: PamaceaAuthLogLevel notice
Log authentication logic (including user logins, etc) to the specified log level, which may be any of the levels supported by the Apache LogLevel directive. Setting this to the same or higher value as the LogLevel directive will allow authentication information to be logged without having to enable debugging output. (Logging will go to the error_log.)
PamaceaErrorPageUsage: PamaceaErrorPage [relative path to file]
Example: PamaceaErrorPage /pamacea/error.html
When the module encounters a non-authentication related error, it will deliver or redirect the browser to this page. See Preparing the Required Web Pages for more information.
PamaceaGroupSourceUsage: PamaceaGroupSource [source] [argument]
Example: PamaceaGroupSource PAMEnv AUTHZ_GROUPS
The module can implement authorization via require group directives in .htaccess. In order to do so, a group source must be specified. The following group sources are supported:
PamaceaIdleTimeUsage: PamaceaIdleTime [number]
The length of inactivity, in seconds, after which a login session is expired. The time cannot logically exceed the time specified by PamaceaSessionLength. A length of 0 disables idle timeouts.
PamaceaInternalRedirectUsage: PamaceaInternalRedirect [On|Off]
The module can handle redirects, which are used to generate and process login requests, among other tasks, either internally or externally. The default is externally.
PamaceaLoginPageUsage: PamaceaLoginPage [relative path to file]
When the module requires authentication, it will deliver or redirect the browser to this page. See Preparing the Required Web Pages for more information.
PamaceaLogoutPageUsage: PamaceaLogoutPage [relative path to file]
When this page is retrieved, the client's current session is expired. See Preparing the Required Web Pages for more information.
PamaceaNoCacheUsage: PamaceaNoCache [On|Off]
PamaceaNoCacheMSIEThis directive may also be placed in .htaccess.
Usage: PamaceaNoCacheMSIE [On|Off]
When delivering content to Microsoft browsers, send headers indicating that the content should not be cached. This will prevent pages from being visible via the browser's back button after logout. However, it will also break file downloads. (This is a "feature", not a bug.)
PamaceaNoCookieURIUsage: PamaceaNoCookieURI [relative path to file]
When the module detects that the client does not have cookies enabled, this page will be delivered or redirected to instead of whatever was originally requested. See Preparing the Required Web Pages for more information.
PamaceaNoIPCheckUsage: PamaceaNoIpCheck [On|Off]
When validating a session presented to the module, the IP address of the requesting client is matched against the IP address of the originally authenticated client. If this directive is enabled, the IP validation is skipped.
PamaceaNoSSLUsage: PamaceaNoSSL [Decline|Forbid|OK]
When a non-SSL connection is established, this directive controls how the module behaves.
PamaceaPAMConfirmUserFileUsage: PamaceaPAMConfirmUserFile [varname]
Example: PamaceaPAMConfirmUserFile HTPASSWD_REALM
When PamaceaUserFile is in use, confirm which userfile was used by retrieving the specified environment variable from the PAM handle.
This option is recommended when multiple PAMs are stacked for the same service, including at least one which uses userfiles and one which does not, and PamaceaSingleSignOnMode is set to UserFile for that service.
PamaceaPAMServiceThis directive may also be placed in .htaccess.
Usage: PamaceaPAMService [pamservice]
The argument provided to this directive is used as the service argument to pam_start(), and corresponds to the service name field in pam.conf.
The argument provided to this directive in httpd.conf selects the default service name used. When placed in .htaccess, the per-directory value overrides the default name.
Note: In order for a service name to be valid, it must be allowed by a PamaceaPermittedPAMService directive. This applies for the default value set in httpd.conf as well as any used in any .htaccess.
PamaceaPAMUserFileServiceUsage: PamaceaPAMUserFileService [pamservice] [...]
Example: PamaceaPAMService htpasswd
PamaceaPermittedPAMServiceUsage: PamaceaPermittedPAMService [pamservice] [...]
Example: PamaceaPAMService secureweb skey
The arguments provided to this directive are then permitted to be used as arguments for the PamaceaPAMService directive.
PamaceaPruneFrequencyUsage: PamaceaPruneFrequency [number]
Whenever a new session is inserted into the session manager, the module can call the session manager's cleanup function to remove any stale sessions. This directive controls how frequently the cleanup function is called.
The frequency is 1/n, where n is the argument provided. For example, setting the value to 5 will call the cleanup function approximately once for every five new sessions. (The actual implementation is via random number generation.) The value should not be set higher than 127. If set to 0, no cleanup will happen.
PamaceaSessionLengthUsage: PamaceaSessionLength [number]
The length, in seconds, of a login session. This is an absolute timeout, not an idle timeout (which can be specified by PamaceaIdleTime), so reauthentication will always be required when this period has expired. A length of 0 indicates that sessions will not timeout.
PamaceaSetEnvThis directive may also be placed in .htaccess.
Usage: PamaceaSetEnv [source] [varname]
The module can set environment variables for use by dynamic content producers (eg: CGI based applications). The following sources are supported:
PamaceaSingleSignOnModeUsage: PamaceaSingleSignOnMode [service] [mode]
Example: PamaceaSingleSignOnMode htpasswd UserFile
This directive controls when single sign on is in effect. There are three possible modes, each defined PAM service can operate in a different mode.
See the NOTES file in the distribution for a more detailed explanation of Single Sign On vs namespaces and modes vs realms.
PamaceaSingleSignOnRealmUsage: PamaceaSingleSignOnRealm [uriprefix] [realm]
Example: PamaceaSingleSignOnRealm /~ Personal
This directive defines single sign on realms. A realm is a collection
of documents with a common URI prefix. Whenever a new realm is
encountered, the current session will be expired and new
authentication required (regardless of PamaceaSingleSignOnMode).
See the NOTES file in the distribution for a more detailed
explanation of Single Sign On modes vs realms.
Usage: PamaceaUserFile [filename]
The argument provided to this directive is passed to the PAM
infrastructure during authentication to allow verification of
identities in the usual htpasswd format. This assumes
a PAM module capable of understanding this format. The included
pam_htpasswd is capable of this.
The userfile name is passed to the PAM via the PAM environment variable
Note: The name of this directive may be changed in
Usage: PamaceaWhatTheUserTyped [On|Off]
If enabled, mod_auth_pamacea will set $REMOTE_USER
to be whatever the user typed into the login form, regardless of
whether or not the PAM stack modifies the username as part of the
See also PamaceaSetEnv.
See the NOTES file in the distribution for a more detailed explanation of Single Sign On modes vs realms.
Usage: PamaceaUserFile [filename]
The argument provided to this directive is passed to the PAM infrastructure during authentication to allow verification of identities in the usual htpasswd format. This assumes a PAM module capable of understanding this format. The included pam_htpasswd is capable of this. The userfile name is passed to the PAM via the PAM environment variable USERFILE.
Note: The name of this directive may be changed in mod_auth_pamacea.h.
Usage: PamaceaWhatTheUserTyped [On|Off]
If enabled, mod_auth_pamacea will set $REMOTE_USER to be whatever the user typed into the login form, regardless of whether or not the PAM stack modifies the username as part of the authentication process.
See also PamaceaSetEnv.
AuthNameUsage: AuthName [realm]
Example: AuthName internalnews
AuthTypeUsage: AuthType Pamacea
This directive invokes mod_auth_pamacea.
When a directory containing this directive is encountered, the client's current session is expired. No other protection is performed, so the contents of the directory will be publically accessible.
PamaceaNoCacheMSIEUsage: PamaceaNoCacheMSIE [On|Off]
Default: Global configuration file value
See the documentation for the configuration file directive.
PamaceaPAMServiceSee the documentation for the configuration file directive.
PamaceaSetEnvSee the documentation for the configuration file directive.
PamaceaUserFileSee the documentation for the configuration file directive.
RequireUsage: Require [method] [validname [...]]
Example: Require valid-user
Example: Require user jsmith
Example: Require group group1
Restrict who has access to the contents of the directory. The following authorizations are supported:
pam_htpasswdpam_htpasswd is a PAM module that understands Apache's user password file format. Although it is included with mod_auth_pamacea, it is not enabled by default.
To build the PAM module, simply
% cd mod_auth_pamacea/pam_htpasswd % make # make installThis will also build a test program pam that can be used to verify if the module is correctly installed.
To configure the PAM, edit /etc/pam.conf or add an entry to /etc/pam.d/, according to your local system. A sample pam.conf entry will look like
htpasswd auth required /lib/security/pam_htpasswd.so.1 use_first_passThe utility pam in the pam_htpasswd directory can be used to test the PAM configuration. Provide it with the PAM service name, the full path to the desired userfile, a username, and a password.
% ./pam htpasswd /home/jsmith/htpasswd jsmith goodpw Go (userfile = /home/jsmith/htpasswd) % ./pam htpasswd /home/jsmith/htpasswd jsmith badpw No go (The number in brackets indicates the PAM error code returned, as defined in pam_appl.h.)
After successful authentication, pam_htpasswd will store the userfile used for authentication in the PAM environment variable HTPASSWD_REALM.
The following mod_auth_pamacea directives should be used in httpd.conf when pam_htpasswd is used:
PamaceaPAMUserFileService htpasswd PamaceaPAMConfirmUserFile HTPASSWD_REALMAdditionally, the PamaceaUserFile directive must be specified in relevant .htaccess files.
Change Logv3.0 (23 January 2007)
Important: The format of the state information maintained by the file-based session manager has changed. It is recommended that any existing state files be cleared when upgrading to v3.0.
v2.1 (9 September 2004)
Important: The format of the state information maintained by the file-based session manager has changed. It is recommended that any existing state files be cleared when upgrading from v2.0 to v2.1.
Important: The format of the state information maintained by the file-based session manager has changed. It is recommended that any existing state files be cleared when upgrading from v1.0 to v2.0.
Common ErrorsIf every request returns "Permission denied", you are probably accessing via http and not https, and have not set "PamaceaNoSSL OK" in httpd.conf. Verify this by retrieving the login page directly (assuming it has @ERRORTEXT@ in it somewhere).
Bug ReportsBug reports, including errors in documentation, are appreciated. While we will attempt to take action, due to limited staff resources no assurance of acknowledgement or investigation can be made. Please submit reports anyway.
Enter bug reports via the mod_auth_pamacea Bugzilla.
Please include the following information in any bug report:
$Date: 2007/01/23 03:10:55 $
$Revision: 1.13 $
AcIS Development Projects