INTRODUCTION
============

This document describes how to use the Apache DSO module mod_myauth.
This module let you store Apache authenitcation information in a 
MySQL database.

This module is for Apache 2 only and will not work with 1.3.x



MySQL TABLES
=============

In order to get MySQL authentication working, you will have to create two
tables (actually you may use existing tables as long as they contain the
required information). The SQL code to create the tables are listed below.


CREATE TABLE users (
	uname  VARCHAR(64) NOT NULL PRIMARY KEY,
	passwd VARCHAR(64) NOT NULL
);


CREATE TABLE groups (
	gname VARCHAR(32) NOT NULL,
	uname VARCHAR(64) NOT NULL,
	PRIMARY KEY (gname,uname)
);


If you are not using groups, you do not need the second table. Note that
it is perfectly ok to add more fields to both tables.




CONFIGURATION PARAMETERS
========================

MyAuthHost
    Default:        localhost
    Required:       NO
    Description:    Specifies the server (with MySQL) to connect to.

MyAuthPort
    Default:        Standard MySQL port
    Required:       NO
    Description:    Specifies the port to connect on.

MyAuthDB
    Default:        (no default value)
    Required:       YES
    Description:    Name of the database that holds the users and groups
                    tables. 

MyAuthDBUser
    Default:        (no default value)
    Required:       YES
    Description:    MySQL server login (for running queries). Must be a
                    user with read access to the users/groups tables.
					
MyAuthDBPassw
    Default:        (no default value)
    Required:       YES
    Description:    Password for login to MySQL.

MyAuthUserTable
    Default:        users
    Required:       NO
    Description:    Name of table holding usernames and passwords

MyAuthGroupTable
    Default:        groups
    Required:       NO
    Description:    Name of table holding group names

MyAuthUserField
    Default:        uname
    Required:       NO
    Description:    Name of field holding usernames in users table

MyAuthPasswordField
    Default:        password
    Required:       NO
    Description:    Name of field holding passwords in users table

MyAuthGroupField
    Default:        gname
    Required:       NO
    Description:    Name of field holding group names in group table

MyAuthEncryption    
    Default:        MySQL encryption
    Required:       NO
    Description:    Possible encryption types (PlainText,Crypt,MySQL,MD5Base64,
                    ALL). MD5Base64 will be honored only, if myauth has been
                    compiled with the --enable-openssl option.

MyAuthAuthoritative
    Default:        On
    Required:       NO
    Description:    If this flag is set to off, other authentication schemes
                    are allowed to authorize the user after this module
                    has denied access.

MyAuthPasswordQuery
    Default:       empty
    Required:      NO
    Description:   Allows experts to use a home grown SQL statement to obtain
                   the password for an user. This statement should have one,
                   and only one "'%s'" string, which gets replaced with the
                   user name logging in. The statement is used as C string,
                   so characters with a special meaning in C must be escaped.
                   If this option is used, the options MyAuthUserTable,
                   MyAuthUserField and MyAuthPasswordField are ignored.
                   E.g.: "SELECT passwd FROM users u WHERE u.login='%s'"

MyAuthGroupsQuery
    Default:       empty
    Required:      NO
    Description:   Allows experts to use a home grown SQL statement to obtain
                   all groups for an user. This statement should have one,
                   and only one "'%s'" string, which gets replaced with the
                   user name logging in. The statement is used as a C string,
                   so characters with a special meaning in C must be escaped.
                   If this option is used, the options MyAuthGroupTable and
                   MyAuthGroupField are ignored.
                   E.g.: SELECT r.name FROM users u LEFT JOIN user2role ru ON \
                             u.uid=ru.uid LEFT JOIN roles r on ru.gid=r.gid \
                             WHERE u.login='%s'


EXAMPLE .htaccess FILE
======================

In order for .htaccess files to work, you may have to change the AllowOverride
option for the htdocs directory in the Apache server configuration file. See
the Apache documentation on how to do this.

AuthName             "mod_myauth testing"
AuthType             Basic
MyAuthHost           localhost
MyAuthDB             auth
MyAuthDBUser         http_auth
MyAuthDBPassw        auth_pasw
MyAuthUserTable      member
MyAuthUserField      uname
MyAuthPasswordField  pword
MyAuthGroupTable     groups
MyAuthGroupField     gname
Require group        admin


=============================================================================
LNF NOTES:
=============================================================================

MODULE_USAGE:
-------------
To be able to use the mod_myauth module you need to enable it in your 
httpd.conf of course. E.g.:

LoadModule myauth_module modules/mod_myauth.so


MD5Base64 encoding
------------------
MD5Base64 encoding is a LNF addition to the myauth package, to have
a database and OS independ encryption available.

  With openssl one would say:
        echo -n "$msg" | openssl dgst -md5 -binary | openssl base64

  In java one could do:
        import java.security.MessageDigest;
        import sun.misc.BASE64Encoder;
        ...
        public String md5base64(String msg) {
            byte[] hash = java.security.MessageDigest.getInstance("MD5")
                .digest(msg.getBytes());
            BASE64Encoder encoder = new BASE64Encoder();
            return encoder.encode(hash);
        }
        ...

  In the JBoss Application Server one could use:
    java -classpath ./jbosssx.jar org.jboss.security.Base64Encoder j2ee MD5

    or in the server/*/conf/login-config.xml file:

    <application-policy name="secured-app">
        <authentication>
        <login-module
            code="org.jboss.security.auth.spi.DatabaseServerLoginModule"
            flag="required">
            <module-option name="dsJndiName">java:/MySqlDS</module-option>
            <module-option name="principalsQuery">
                SELECT password FROM users WHERE uname=?
            </module-option>
            <module-option name="hashAlgorithm">MD5</module-option>
            <module-option name="hashEncoding">base64</module-option>
            <module-option name="rolesQuery">
                SELECT gname,'Roles' FROM groups WHERE uname=?
            </module-option>
        </login-module>
        </authentication>
    </application-policy>

DB setup:
---------
mysql -u root -p
CREATE DATABASE jboss;
GRANT ALL PRIVILEGES ON jboss.* TO jboss@localhost IDENTIFIED BY 'jboss$1';
FLUSH PRIVILEGES;
USE jboss;
CREATE TABLE users (
    uname  VARCHAR(64) NOT NULL PRIMARY KEY,
    passwd VARCHAR(64) NOT NULL
) Type=InnoDB;
CREATE TABLE groups (
    gname VARCHAR(32) NOT NULL,
    uname VARCHAR(64) NOT NULL,
    PRIMARY KEY (gname,uname)
) Type=InnoDB;
# echo -n "masterpass" | openssl dgst -md5 -binary | openssl base64
# => 'qx5cuHvKgotUpKJMKzfqjw=='
INSERT INTO users VALUES('master','qx5cuHvKgotUpKJMKzfqjw==');
INSERT INTO groups VALUES('admin','master');
COMMIT;

Apache config:
--------------
<Directory "/opt/www/sites/www.spass.de/htdocs/schmutzigeWitze">
#   SSLRequireSSL
#   SSLOptions OptRenegotiate
    AuthName "Restricted Applications"
    AuthType Basic
    MyAuthHost      localhost
    MyAuthPort      3306
    MyAuthDB        jboss
    MyAuthDBUser    jboss
    MyAuthDBPassw   "masterpass"
    MyAuthUserTable     users
    MyAuthGroupTable    groups
    MyAuthUserField     uname
    MyAuthPasswordField passwd
    MyAuthGroupField    gname
    MyAuthEncryption    MD5Base64
    require group admin
    AllowOverride AuthConfig Limit
#   Order Allow,Deny
#
#   Allow from 127.0.0.1/32 192.168.1.0/24 
#   Deny from all
</Directory>