nginx_auth_mysql
----------------

nginx_auth_mysql allows you to do basic authentication against
a MySQL database.

== INSTALLATION ==

To install, compile nginx with the following option:

  --add-module=/path/to/nginx_auth_mysql
  
If mysqlclient or any of the other libraries are in non-standard locations,
you can add them to CORE_LIBS in the `config` file. Also you may need to
add CORE_INCS for include files. Here is how these two lines look in order
to compile it on Mac OS X using mysqlclient from darwinports:

CORE_LIBS="$CORE_LIBS -lcrypto -lmysqlclient -L/opt/local/lib/mysql5/mysql/"
CORE_INCS="$CORE_INCS /opt/local/include/mysql5/mysql/"

Note: every time you change the `config` file, you have to run the ./configure
magic line again.
  
== CONFIGURATION ==
  
It is activated by adding several configuration options:

- auth_mysql_realm: HTTP basic authentiaction realm. Required.
- auth_mysql_host: the host of the MySQL server. Default is 127.0.0.1.
- auth_mysql_port: on which port to connect to the MySQL server. Default is 3306.
- auth_mysql_user: username for connection to the MySQL server. Default is root.
- auth_mysql_password: password for connection to the MySQL server. Default is empty.
- auth_mysql_database: name of the database. Required.
- auth_mysql_table: name of the table, which holds the user record.
    You can have more than one table separated by comas. Default is users.
- auth_mysql_user_column: name of the username column. Default is username.
- auth_mysql_password_column: name of the password column. Default is password.
- auth_mysql_conditions: Additional SQL conditions. They will be placed after and AND.
    Default is empty string.
- auth_mysql_group_table: name of the table, which holds the groups information.
    You can have more than one table separated by comas. Default is the users table.
- auth_mysql_group_column: name of the group name column. Default is name.
- auth_mysql_group_conditions: Additional SQL conditions applied only in group queries.
    They will be placed after an AND. Default is empty string.
- auth_mysql_encryption_type: the format of the password field. Should be one of:
    * none: the password is stored in plaintext in the database;
    * md5: in the database is stored a md5 hash of the password;
    * phpass: a portable php hash of the password is stored. See:
        http://www.openwall.com/phpass/ for more information.
    The default is md5.
- auth_mysql_allowed_users: whitespace delimited list of allowed users.
- auth_mysql_allowed_groups: whitespace delimited list of allowed groups.
    If both allowed_users and allowed_groups are defined, either of them has to satisfied.
    
== SAMPLE CONFIGURATION ==

location / {
            root   html;
            index  index.html index.htm;
            auth_mysql_realm "My Secret Website:";
            auth_mysql_host "db.acme.com";
            auth_mysql_user "root";
            auth_mysql_password "secretsanta";
            auth_mysql_database "acme_production";
            auth_mysql_table "acme_users";
            auth_mysql_password_column "pass";
            auth_mysql_user_column "user";
            auth_mysql_encryption_type "phpass";
            # only these two usernames will be accepted
            auth_mysql_allowed_users "roadrunner coyote";
            # either the usernames above will be acceped
            # or any user from the groups below
            auth_mysql_allowed_groups "omg-bbq-admins";

        }   

# groups example
location / {
            root   html;
            index  index.html index.htm;
            auth_mysql_realm "My Secret Website with Groups:";
            auth_mysql_database "acme_production";
            auth_mysql_group_table "groups, users_groups"
            auth_mysql_group_column "groups.name"
            auth_mysql_group_conditions "users.id = users_groups.user_id AND users_groups.group_id = groups.id"
            auth_mysql_allowed_users "roadrunner coyote";
            # either the usernames above will be acceped
            # or any user from the groups below
            auth_mysql_allowed_groups "omg-bbq-admins";
        }   


== HOW IT WORKS ==

- The query for retrieving the password is in the form:
    SELECT
        `password`
    FROM user_table [, group_table]
    WHERE
        `username` = '<username-from-HTTP-request>'
        [AND conditions]
        [AND group_conditions]
        [AND group_column IN (<groups-from-allowed-users-clause>)]

You should add an index on your username column.

== BUGS ==

msp_users.ID = msp_bp_groups_members.user_id

== WRITING A NEW ECNRYPTION TYPE ==

Add an entry in the `ngx_http_auth_mysql_enctypes` array. It has to be a struct
with two elements:
    - ngx_str_t id
    
        The name under which it should be referenced in the config file
        
    - ngx_uint_t (*checker)(ngx_http_request_t *r, ngx_str_t sent_password, ngx_str_t actual_password)
    
        A function, which given the request (mostly used for logging and memory allocation through its r->pool),
    the password sent by the user and the password in the database has to determine whether they match.
    If they match it should return NGX_OK, if they don't it should return NGX_DECLINED. If other error
    occures, it should log it and return NGX_ERR.    
    Currently salts aren't supported, but if there are schemes, which require them it is quite easy.
    
Questions/patches may be sent to Nikolay Bachiyski, nikolay@automattic.com