[pkgsrc/trunk]: pkgsrc/www/ap-auth-external Initial commit of an external aut...

[sborrill <sborrill%pkgsrc.org@localhost>]

details:   https://anonhg.NetBSD.org/pkgsrc/rev/1a5e3482380e
branches:  trunk
changeset: 524132:1a5e3482380e
user:      sborrill <sborrill%pkgsrc.org@localhost>
date:      Fri Jan 19 09:00:24 2007 +0000

description:
Initial commit of an external authentication module provides a flexible
tool for creating authentication systems based on other databases.

The module can be used in either of two somewhat divergent ways:
1) External Authentication:
2) Hardcoded Authentication:

diffstat:

 www/ap-auth-external/DESCR    |   20 ++
 www/ap-auth-external/INSTALL  |  388 ++++++++++++++++++++++++++++++++++++++++++
 www/ap-auth-external/MESSAGE  |    9 +
 www/ap-auth-external/Makefile |   26 ++
 www/ap-auth-external/PLIST    |    2 +
 www/ap-auth-external/distinfo |    8 +
 6 files changed, 453 insertions(+), 0 deletions(-)

diffs (truncated from 477 to 300 lines):

diff -r 6fca1fe3e25b -r 1a5e3482380e www/ap-auth-external/DESCR
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/www/ap-auth-external/DESCR        Fri Jan 19 09:00:24 2007 +0000
@@ -0,0 +1,20 @@
+The Apache HTTP Daemon can be configured to require users to supply logins
+and passwords before accessing pages in some directories. Authentication is
+the process of checking if the password given is correct for a user. Apache
+has standard modules for authenticating out of several different kinds of
+databases. The external authentication module provides a flexible tool for
+creating authentication systems based on other databases.
+
+The module can be used in either of two somewhat divergent ways:
+1) External Authentication:
+
+When a user supplies a login and password, mod_auth*_external runs a program
+you write, passing it the login and password. Your program does whatever
+checking and logging it needs to, and then returns a Accept/Reject flag to
+Apache.
+
+2) Hardcoded Authentication:
+
+Some hooks have been inserted into mod_auth*_external to make it easy to
+replace the call to the external authentication program with a call to a
+hardcoded internal authentication routine that you write.
diff -r 6fca1fe3e25b -r 1a5e3482380e www/ap-auth-external/INSTALL
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/www/ap-auth-external/INSTALL      Fri Jan 19 09:00:24 2007 +0000
@@ -0,0 +1,388 @@
+How to install mod_auth_external.c into the Apache source tree.
+
+NOTES:
+
+ * If you want to use the HARDCODE function option follow the instructions
+   in the INSTALL.HARDCODE file in this directory before following these
+   instructions.
+
+ * These instructions are for Apache version 1.3.  I don't know if this version
+   of mod_auth_external is still compatible with older versions of Apache.
+
+ * There are two ways of installing mod_auth_external. 
+
+     (1) You can statically link it with Apache.  This requires rebuilding
+         Apache in such a way that mod_auth_external will be compiled in. 
+
+     (2) You can make mod_auth_external a dynamically loaded module.  If
+         your Apache has been built to support dynamically loaded modules
+        you can do this without rebuilding Apache, so it is pretty easy.
+        Performance may be slightly worse with this option.  For information
+        on dynamically loaded modules see http://www.apache.org/docs/dso.html
+
+   Instructions for both options are given here.
+
+ * If you are statically linking mod_auth_external into Apache, you must
+   rebuild Apache.  There are two methods of building Apache, the APACI
+   method and the manual method.  Instructions for both are given here.  The
+   configuration part is the same either way.
+
+ * There is also documentation in the README file, in the AUTHENTICATORS file
+   and at the front of the mod_auth_external.c source file.  If you find this
+   document unclear, reading those may help.
+
+
+INSTALL METHOD A: Dynamically Linking Mod_auth_external using apxs:
+-------------------------------------------------------------------
+
+Step 1:
+       Ensure that your Apache server is configured to handle dynamically
+       loaded modules.  Redhat Linux 6.1 does.  To check this, run Apache
+       server with the -l command flag, like
+
+              httpd -l
+
+       If mod_so.c is one of the compiled-in modules, then you are ready
+       to go.
+
+Step 2:
+       Compile the module using the following command in the mod_auth_external
+       distribution directory:
+
+               apxs -c mod_auth_external.c
+
+       'Apxs' is the Apache extension tool.  It is part of the standard
+       Apache installation.  If you don't have it, then your Apache server
+       is probably not set up for handling dynamically loaded modules.
+       This should create a file named 'mod_auth_external.so'.
+
+       AIX Note:  I'm told that on AIX the 'apxs' command above compiles
+          mod_auth_external.c into mod_auth_external.o correctly, but
+          generation of the shared library file fails with a message like
+          "No csects or exported symbols have been saved."  If this happens,
+          create a file in the current directory named mod_auth_external.exp
+          which contains the two lines below:
+
+                #! mod_auth_external.o
+                external_auth_module 
+
+           Then run 
+           
+               apxs -c mod_auth_external.c -bE:mod_auth_external.exp
+ 
+Step 3:
+       Install the module.  Apxs can do this for you too.  Do the following
+       command (as root so you can write to Apache's directories and config
+       files):
+
+              apxs -i -a mod_auth_external.so
+
+       This will copy mod_auth_external.so into the proper place, and add
+       appropriate AddModule and LoadModule commands to the configuration
+       files.  (Actually, it may get the LoadModule command wrong.  See
+       below.)
+
+Step 4:
+       Go to the CONFIGURATION instructions below.
+
+
+INSTALL METHOD B: Statically Linking by building Apache with APACI:
+-------------------------------------------------------------------
+
+Step 1:
+        Read the instructions on how to configure the Apache server in the
+        INSTALL file provided with the Apache source.
+
+Step 2:
+        When you run the ./configure script, include an --add-module flag,
+        giving the full pathname to the mod_auth_external.c file in this
+        distribution.  For example, if you have unpacked this distribution
+        in /usr/local/src/mod_auth_external and are building Apache for
+        installation in /usr/local/apache, you might do:
+
+        ./configure --prefix=/usr/local/apache \
+              --add-module=/usr/local/src/mod_auth_external/mod_auth_external.c
+
+        This will copy the mod_auth_external.c file into the correct place in
+        the Apache source tree and set things up to link it in.
+
+Step 3:
+       Type "make" to compile Apache and "make install" to install it.
+
+Step 4:
+       Go to the CONFIGURATION instructions below.
+
+
+INSTALL METHOD C:  Statically Linking by manually building Apache:
+------------------------------------------------------------------
+
+Step 1:
+       Read the instructions on how to configure the Apache server in the
+       src/INSTALL file provided with the Apache source.
+
+Step 2:
+       Copy the mod_auth_external.c file from this distribution into the
+       src/modules/extra subdirectory of the Apache source tree.
+
+Step 3:
+       Add the following line to the Apache 'Configuration' file:
+
+          AddModule modules/extra/mod_auth_external.c 
+
+Step 4:
+       Run "./Configure" and "make" and "make install" in the src directory
+       to configure, compile and install Apache.
+
+Step 4:
+       Go to the CONFIGURATION instructions below.
+
+CONFIGURATION:
+--------------
+
+There are two parts to doing the configuration.  First you define the
+external program and communication method to use in your httpd.conf file,
+identifying them with a keyword.  Then you set up specific directories to
+use that authenticator, referencing it by keyword.
+
+Step 1:
+       If you are using dynamic loading, you'll need to make sure that
+       there is a proper "LoadModule" command in the httpd.conf file.
+       This should have been put there by 'apxs' but, at least under
+       RedHat 6.1, it gets it wrong.  Basically, the 'LoadModule' command
+       should look a lot like all the other LoadModule commands.  Something
+       like
+
+           LoadModule external_auth_module modules/mod_auth_external.so
+
+        where the second part is the path from Apache's root directory
+       to the location where the module is stored.
+
+       Make sure that apxs didn't put this directive inside any inappropriate
+       <IfDefine> directives.  Under RedHat 7.1 it likes to put it inside
+       <IfDefine HAVE_PYTHON> which makes no sense.
+
+       Also, if you previously had mod_auth_external installed and are
+       installing a new version, apxs may have put a second LoadModule
+       command into httpd.conf.  You only need one.  Get rid of the extra.
+
+Step 2:
+       Check you httpd.conf file to see if there is a "ClearModuleList"
+       command.  If this exists, then you need to add a command like:
+
+           AddModule mod_auth_external.c
+
+       somewhere below "ClearModuleList" command (probably somewhere among
+       the dozens of other AddModule commands).  If you used 'apxs' to
+       install mod_auth_external, then this should already be done, but
+       it may again be stashed in an inappropriate <IfDefine>.
+
+       The standard Apache configuration files don't have a "ClearModuleList"
+       command and don't need an "AddModule" command.  However the standard
+       RedHat configuration files do.
+
+Step 3:
+       Add the following line(s) to your server's httpd.conf.
+       
+       If you are using virtual hosts, put them at the end of the
+       appropriate <VirtualHost> block.  The declarations must be *inside*
+       the <VirtualHost> block to work for a virtual host.  They are not
+       inherited from the primary host to the virtual hosts.  Note that most
+       Apache SSL servers are set up as virtual hosts, so you'll probably
+       need to put these definitions in the <VirtualHost> block for use with
+       an SSL server.
+       
+       Otherwise, just put them anywhere (just before the Virtual Hosts
+       section of the config file might make the most sense).
+
+       For external authentication programs:
+            AddExternalAuth <keyword> <path-to-authenticator>         
+            SetExternalAuthMethod <keyword> <method>
+
+       For HARDCODE functions:
+           AddExternalAuth <keyword> <type>:<path where config file is>
+            SetExternalAuthMethod <keyword> function
+
+       <keyword> is some name you choose.  You can configure multiple
+       different external authenticators by using different keywords for
+       them.
+
+       <path-to-authenticator> is normally the full path where you installed
+       your external authentication program.  If you put it in quotes, you
+       can include command-line arguments, but these arguments won't be
+       processed by a shell, so you can't use wildcards or I/O redirects
+       or anything like that.  If you need shell processing of arguments,
+       write an sh-script wrapper for your authenticator, and put the path
+       to that here.
+
+       <method> defines how the login and password are passed to the
+       external authenticator:
+          environment    get args from environment variables. (default)
+          pipe           read newline-terminated strings from stdin.
+         checkpassword  read null-terminated strings from file descriptor 3.
+          function       internal authenticator called as function.
+        Environment is the default for historical reasons, but it may be
+        insecure on some versions of Unix.  See the README file.
+
+       Examples:
+
+         ** For external authentication programs using environment variables:
+
+            AddExternalAuth archive_auth /usr/local/bin/authcheck
+            SetExternalAuthMethod archive_auth environment
+
+         ** For external authentication programs using a pipe:
+
+            AddExternalAuth archive_auth /usr/local/bin/authcheck
+            SetExternalAuthMethod archive_auth pipe
+
+         ** For external authenticators using the checkpassword protocol:
+
+            AddExternalAuth archive_auth "/bin/checkpassword /bin/true"
+            SetExternalAuthMethod archive_auth checkpassword
+
+          ** For HARDCODE functions with no configuration file:
+
+             AddExternalAuth archive_auth RADIUS:
+             SetExternalAuthMethod archive_auth function
+
+          ** For HARDCODE functions with a configuration file:
+
+             AddExternalAuth archive_auth RADIUS:/usr/local/raddb
+             SetExternalAuthMethod archive_auth function
+          
+Step 4:
+       If you want to use an external program to do group checking, add the 
+       following to your server's httpd.conf.
+
+        AddExternalGroup <keyword> <path-to-authenticator>         
+
+        SetExternalGroupMethod <keyword> <method>
+
+       <keyword> is some name you choose to identify this particular
+       group checking method.  The keywords for login authenticators and
+       group authenticators are separate name spaces, so it doesn't matter
+       if these keywords match any you defined in step 1.
+
+       <method> defines how the login and group names are passed to the
+       external authenticator:
+           environment - authenticator gets data from environment variables.
+           pipe - authenticator reads data from standard input.
+        Environment is the default.
+
+       Examples: