#######################################################################
#  apache_mod_ae                                                      # 
#  =============                                                      #
#  Authentification Module for the apache web server. The module      #
#  can handle diffrent domains and caches the authentification        #
#  results. This makes it posible to use slow external                #
#  authentification systems.                                          #
#                                                                     #
#  Author's: it@guru.de                   Version V0.16 11/2007       #
#            holm@blauwaerme.de                                       #
#######################################################################
1.0 General

    1.1 ChangeLog

       1.1.1 Patch Makefile to work with solaris and remove use of function isbank()
       1.1.2 Apache2 extension

2.0  Installation
    2.1  Installation of the acache-Server
    2.2  Installation of Apache-Module 1.3
    2.3  Installation of Apache-Module 2.0
    2.4  Installation of a Dummy-Konfiguration

3.0  Apache Module parameters

4.0  Daemon acache configuration
    4.1  Structure of /etc/ae.conf
    4.2  Structure of /etc/aetools.conf

5.0  Apache configuration
    5.1  SSO config
        5.1.1 SSO bypass BasicAuth dialog in Browser

#######################################################################

1.0  General
============
Any filenames in this README are relativ to the directory, in whitch you
have unpack the apache-mod_ae-*.tgz tar-ball.

If you have installed the 'acache' Server, you should ensure that the acache
is running if you want to access Apache authorized-areas. I have put a sample
startup Script at contrib/startup.suse7.2.tgz .

If you use a Linux-Distribution that comes with many authentifikation modules,
you should disable all unnecessary auth-modules because some of them have
problems with account name syntax of mod_auth_ae (the / in the loginname
is sometimes the problem). In that case you can hadle the problem by
disabling the 'LoadModule' and the 'AddModule' commands in httpd.conf for
the problematic modules.

In some Distributions the 'apxs' command is not in the normal apache package.
If you don't have a 'apxs' command on your system, than check whether there
is a 'devel' or 'development' apache package is in your distribution. If
not you must bulid your own apache ;-{


2.0  Installation
================

2.1  Installation of the acache-Server
--------------------------------------
cd src
make clean
make
cp acache /usr/sbin

# If acache isn't in /etc/services:
echo "acache          800/tcp" >> /etc/services

# at the moment the acache server can only run at service 800/tcp .
# The entry in /etc/services is only necessary, if you want the correct
# output in commands like 'netstat -a'.


2.2  Installation of Apache-Module 1.3
--------------------------------------
dependency: apxs, gcc, apache, curl

cd apache
./apxs.config


2.3  Installation of Apache-Module 2.0
--------------------------------------
dependency: apxs2, gcc, apache2, curl

cd apache2
./apxs.config

 
2.4  Installation of a Dummy-Konfiguration
------------------------------------------
mkdir -p /usr/share/lib/acache
cp apache2/.libs/ae_module.so /usr/lib/apache2
cp src/client /usr/sbin/acache-client
cp contrib/authscripts/dummy.sh /usr/share/lib/acache
cp contrib/etc/init.d/* /etc/init.d/
cp contrib/etc/* /etc
echo "LoadModule ae_auth_module /usr/lib/apache2/modules/ae_module.so" \
> /etc/apache2/mods-available/mod_ae_auth.load
ln -s ../mods-available/mod_ae_auth.load /etc/apache2/mods-enabled/mod_ae_auth.load

now make your entries in /etc/rc for autostart acache 

if you have some trouble with /etc/init.d/acache, in the directory contrib/startup...
are startupscripts for different operating systems



3.0  Apache Module Parameters
----------------------

    aeUserFile             Filename for valid user list.
                           (Switch NOT availabel starting from Apache 2.4)
                           default: none
                           
    aeUserFileCheck        Flag to enable the reading of 
                           the z.B. user.txt (aeUserFile)
                           (Switch NOT availabel starting from Apache 2.4)
                           default: no

    aeAuthoritative        Sets the authoritative of ae_module.
                           (Switch NOT availabel starting from Apache 2.4)
                           default: on
                           
    aeAccountToLower       Flag to enable the lower-conversion of
                           the typed in account.
                           default: no

    aeDomainSeperator      List of characters that are valid to 
                           seperate doamin from username.
                           (Switch NOT availabel starting from Apache 2.4)
                           default: "/\_"

    aeSSOUser              Username to handle BasicAuth SSO Access
                           (Switch availabel starting from Apache 2.4)
                           default: none
                           
    aeSSOPass              Password to handle BasicAuth SSO Access
                           (Switch availabel starting from Apache 2.4)
                           default: none

    aeSSOHeaderUserAttr    Header Attribute with real Username from SSO
                           (Switch availabel starting from Apache 2.4)
                           default: none
  
    aeSSODomain            Domain-Prefix to add  real Username from SSO to
                           create a real Username to CGI Application
                           (Switch availabel starting from Apache 2.4)
                           default: none
                           

4.1  Structure of /etc/acache.conf
----------------------------------
HELPERS      = /etc/aetools.conf  # name of the domain configuration

MAXCACHETIME = 60                 # max seconds that a entry can life
                                    in the shared memory cache.


4.2  Structure of /etc/aetools.conf
-----------------------------------
The name of this config file can be changed in ae.conf. In the aetools.conf
file the list of valid domains are described.

Sample:

Domainname
|
|     white space seperator
|     |
|     | command to check the authentification
|     | |
V     V V
dummy   /usr/share/lib/acache/dummy.sh %U

The authentification command should exit 0 if the username/password is
valid. If no the exit code must be greater than 0.
The %U variable is replaced by the username on execute. The password 
must be readed from stdin from the authentification command.


5.0  Apache configuration
-------------------------

 Sample .htaccess:
 -----------------
 # 
 # The case of the account is in this configuration not relevant. To
 # the authentivication commands are only lower-case accounts are passed
 # to the %U variable.
 # 
 AuthType               Basic
 AuthName               "Domainlogin (z.B.:sued/vogler.hartmut)"
 aeAuthoritative        on
 aeAccountToLower       on

 <Limit GET PUT POST>
    require valid-user
 </Limit>

 Sample .htaccess:
 -----------------
 # 
 # In this configuration is only _ and / (/ is always valid) valid as 
 # seperator between the domain and the username. To the %U valiable
 # is alwas only the username passed.
 # All valid useres must be listed in user.txt file of the current
 # direcotry or any of the parrent directorys.
 # 
 AuthType               Basic
 AuthName               "Domainlogin (z.B.:sued/vogler.hartmut)"
 aeUserFileCheck        on
 aeAccountToLower       on
 aeAuthoritative        on
 aeUserFile             user.txt
 aeDomainSeperator      "_"

 <Limit GET PUT POST>
    require valid-user
 </Limit>

 Sample access.conf:
 -------------------
 # 
 # This is the sample configuration for web-applications (f.e. cgi) that
 # handles here own group/user validation (not authentification !).
 # To the web application are only valid usernames passed, which password
 # belongs to the typed in username.
 # The username ist passed in lower case to the REMOTE_USER enviroment
 # valiable at a cgi enviroment.
 # 
 # (in the example the cgi-application is installed at /opt/suncenter)
 # 
 <Directory /opt/suncenter>
   AuthType               Basic
   AuthName               "Login"
   aeAccountToLower on
   aeAuthoritative on
   Options +FollowSymLinks
   <Limit GET PUT POST>
      require valid-user
   </Limit>
 </Directory>

5.1  SSO config
---------------
SSO (SingleSignLogon) is at the first glance not compatible with
BasicAuth like in this module is propageted - but only at first glance: 

In Apache 2.4 Enviroments, it is posible to add WebSSO handling. To
allow WebSSO, you have to add these config variables:

  aeSSOUser           SSOUser
  aeSSOPass           SSOPass
  aeSSODomain         mydomain/
  aeSSOHeaderUserAttr ssouserid

In aeSSOUser:aeSSOPass a static credential must be negotiated
with your SSO provider. In aeSSOHeaderUserAttr your SSO
provider must send the authenticated userid as a specified
HTTP-Header variable.

If aeSSODomain is specifed, in front of the username from 
the aeSSOHeaderUserAttr field, the domain is specifed.

5.1.1  SSO bypass BasicAuth dialog in Browser
---------------------------------------------
If aeSSOBasicAuthUser is specified (space sperated list), this
Account will be granted without any password. f.e.:

  aeSSOBasicAuthUser  sso SSO

To redirect this Account to WebSSO Page, add this rewrite rule:

RewriteCond %{LA-U:REMOTE_USER} ^(sso|SSO)$
RewriteRule ^/(.*) https://websso.site.com/sso-namespace/$1 [R,END]

If this is configured, you can bypass the basic auth
dialog in Browser by specifiy SSO User direct in url:

https://SSO:@mylocal.site/direct/path/in/my/site

If Users access throw ...
https://mylocal.site/direct/path/in/my/site
... they can user username sso oder SSO and they will
be automatic redirected to SSO Login-Page (if the not 
already Logged in in SSO).

Attention: If you use aeSSOBasicAuthUser, it is mandatory
to add the rewrite rule as above! - If you don't do this,
the aeSSOBasicAuthUser will be passed to your application
as valid REMOTE_USER!


--