mod_authnz_ibmdb2(8) Apache module mod_authnz_ibmdb2(8)
NAME
mod_authnz_ibmdb2 - Apache authentication module for DB2
DESCRIPTION
mod_authnz_ibmdb2 is an Apache authentication module using IBM DB2 as
the backend database for storing user and group information.
The module is designed for Apache 2.2 and later. It supports several
encryption methods.
CONFIGURATION DIRECTIVES
These directives are used to control the behaviour of the authentica-
tion process.
AuthIBMDB2Database database
database name
AuthIBMDB2Hostname hostname
database server hostname (for uncataloged databases)
AuthIBMDB2Portnumber port number
database instance port
default value: 50000
AuthIBMDB2User username
user for connecting to the DB2 database
AuthIBMDB2Password password
password for connecting to the DB2 database
AuthIBMDB2UserTable usertable
name of the user table. If not fully qualified, the user that
was used to connect to the database is used as the schema name.
AuthIBMDB2GroupTable grouptable
name of the group table. If not fully qualified, the user that
was used to connect to the database is used as the schema name.
AuthIBMDB2NameField namefield
name of the username column within the user and group table
default value: username
AuthIBMDB2GroupField groupfield
name of the groupname column within the group table
default value: groupname
AuthIBMDB2PasswordField passwordfield
name of the password column within the user table
default value: password
AuthIBMDB2CryptedPasswords [On|Off]
If AuthIBMDB2CryptedPasswords is "On", then the passwords are
stored encrypted. You do not have to specify what kind of
encryption was used. Valid encryption methods are: normal md5
hash (32 chars as in php), seeded md5 value (as generated with
Apache's htpasswd utility or as in /etc/shadow), crypt. If
"Off", plaintext passwords are used.
default value: On
AuthIBMDB2KeepAlive [On|Off]
If AuthIBMDB2KeepAlive is "On", then the server instance will
keep the IBMDB2 server connection open.
default value: On
AuthIBMDB2Authoritative [On|Off]
If AuthIBMDB2Authoritative is "Off", then iff the user is not
found in the database, let other auth modules try to find the
user.
default value: On
AuthIBMDB2NoPasswd [On|Off]
If AuthIBMDB2NoPasswd is "On", then any password the user enters
will be accepted as long as the user exists in the database.
default value: Off
AuthIBMDB2UserCondition user_condition
Can be used to restrict queries made against the user table. The
value should be a string that you want to be added to the end of
the where-clause when querying the table. For example, if your
user table has an "active" field and you only want users to be
able to login if that field is 1, you could use a directive like
this: AuthIBMDB2UserCondition active=1
AuthIBMDB2GroupCondition group_condition
Can be used to restrict queries made against the group table.
The value should be a string that you want to be added to the
end of the where-clause when querying the table. For example, if
your group table has an "active" field and you only want users
to be able to login if that field is 1, you could use a direc-
tive like this: AuthIBMDB2GroupCondition active=1
AuthIBMDB2UserProc user_procedure_name
If set, the named stored procedure is responsible for returning
the password of the user in question to the module. It must
return exact one value - the password. If AuthIBMDB2NoPasswd is
"On", then the username has to be returned instead of the pass-
word. The stored procedure must have the following parameter
format:
CREATE PROCEDURE user_procedure_name ( IN VARCHAR, OUT VARCHAR )
AuthIBMDB2GroupProc group_procedure_name
If set, the named stored procedure is responsible for returning
the groups the user in question belongs to. It must return an
open cursor to the resultset. The stored procedure must have the
following parameter format:
CREATE PROCEDURE group_procedure_name ( IN VARCHAR )
AuthIBMDB2Caching [On|Off]
If AuthIBMDB2Caching is "On", the user credentials are cached in
a file.
default value: Off
AuthIBMDB2GroupCaching [On|Off]
If AuthIBMDB2GroupCaching is "On", the group information is
cached in a file that is named like the file specified in
AuthIBMDB2CacheFile but with the extension .grp
default value: Off
AuthIBMDB2CacheFile filename
defines the location and name of the cache file
default value: /tmp/auth_cred_cache
AuthIBMDB2CacheLifetime seconds
sets the expiration timeout in seconds of the cached elements
default value: 300
EXAMPLES
Example 1:
Let's say you want to protect http://yourserver/private. The database
where the users and groups are stored in is authdb. You want to use the
user db2user and the password db2pwd to connect to the database. The
name of the usertable is web.users and the name of the grouptable is
web.groups. The two tables look like this:
usertable:
USERNAME PASSWORD
------------------------------ --------------------------------
grouptable:
USERNAME GROUPNAME
------------------------------ --------------------------------
The passwords are stored encrypted and the database connection should
not be closed after the request. mod_authnz_ibmdb2 should be the only
authentication authority and a password is needed to be authenticated.
The users that are in the group admin should be allowed to access the
protected area.
With the above assumptions, your httpd.conf should look like this:
LoadModule authnz_ibmdb2_module modules/mod_authnz_ibmdb2.so
Alias /private "/data/private/"
<Directory "/data/private">
AuthName "DB2 Authentication for private"
AuthType Basic
AuthBasicProvider ibmdb2
AuthIBMDB2User db2user
AuthIBMDB2Password db2pwd
AuthIBMDB2Database authdb
AuthIBMDB2UserTable web.users
AuthIBMDB2NameField username
AuthIBMDB2PasswordField password
AuthIBMDB2CryptedPasswords On
AuthIBMDB2KeepAlive On
AuthIBMDB2Authoritative On
AuthIBMDB2NoPasswd Off
AuthIBMDB2GroupTable web.groups
AuthIBMDB2GroupField groupname
require group admin
AllowOverride None
</Directory>
You also could have ommitted the parameters
AuthIBMDB2NameField, AuthIBMDB2PasswordField,
AuthIBMDB2CryptedPasswords, AuthIBMDB2KeepAlive,
AuthIBMDB2Authoritative, AuthIBMDB2NoPasswd
AuthIBMDB2GroupField
because the default values are used in the above example.
Example 2:
In this example we use the same assumptions as in the first example,
except that we want to use stored procedures. For our example we add an
additional column to the group table:
grouptable:
USERNAME GROUPNAME ACTIVE
------------------------------ -------------------------------- --------
The two stored procedures have the following structure:
CREATE PROCEDURE db2user.user_sp
(IN v_username VARCHAR(128), OUT v_password VARCHAR(128))
LANGUAGE SQL
BEGIN
SELECT password INTO v_password FROM web.users
WHERE username = v_username;
END@
CREATE PROCEDURE db2user.group_sp
(IN v_username VARCHAR(128))
LANGUAGE SQL
DYNAMIC RESULT SETS 1
BEGIN
DECLARE res CURSOR WITH RETURN FOR
SELECT groupname FROM web.groups
WHERE username = v_username AND active = 1;
OPEN res;
END@
The stored procedures return the password and the list of groups of the
user passed to them. Furthermore we want the user and group information
to be cached. The directives in the httpd.conf should then look like
this:
<Directory "/data/private">
AuthName "DB2 Authentication for private"
AuthType Basic
AuthBasicProvider ibmdb2
AuthIBMDB2User db2user
AuthIBMDB2Password db2pwd
AuthIBMDB2Database authdb
AuthIBMDB2UserProc user_sp
AuthIBMDB2GroupProc group_sp
AuthIBMDB2Caching On
AuthIBMDB2GroupCaching On
require group admin
AllowOverride None
</Directory>
FILES
httpd.conf, .htaccess
AUTHOR
Written by Helmut K. C. Tessarek.
BUGS
Hopefully none :-) But if you find one, please report it at:
https://github.com/tessus/mod_authnz_ibmdb2/issues
WEB SITE
http://tessus.github.io/mod_authnz_ibmdb2
mod_authnz_ibmdb2 June 2015 mod_authnz_ibmdb2(8)