Home

Apache Module for Citadel Authentication

Mod_auth_citadel is an Apache Web Server authentication module for the Citadel Groupware Server. This module allows system administrators to provide seamless authentication against the Citadel user database for apache-served content. This is invaluable for providing user-facing control panels for spam management, wiki authentication, and intranet services in a Citadel environment.

Mod_auth_citadel is founded upon an extraordinarily clean and well documented code base, which serves as an excellent tutorial for developers wishing to learn the structure and implementation of custom authentication modules for the Apache Web Server.

The module has been compiled and tested on various Linux distributions (Debian, Ubuntu, Centos, Red Hat Enterprise, Fedora, OpenSUSE) as well as FreeBSD.

Quick Links:

Features: 

  • Uses the native Citadel IPC protocol
  • SSL/TLS support for secure communications to the Citadel server
  • Clean design with a focus on security and reliability
  • Easy configuration and installation

Dependencies: 

The following libraries and includes must be available to compile the module. Primary dependencies include the Apache Portal Runtime (both apr and apr_util) as well as the OpenSSL libraries.

  • Apache Server Development Files (i.e. includes)
  • Apache Portable Runtime - libraries and development files: apr, apr_util
  • OpenSSL libraries and development files

Compilation and Installation: 

Autoconf is used to configure the build system. On many systems, the package may be built and installed (under /usr/local) using:

./configure && make && make install

to install the module in the default location (typically /usr/local). The build scripts will attempt to auto-resolve all dependency locations.

A list of options may be viewed by running:

./configure --help

Interesting options specifically related to the build of this module include:

--with-ssl
--with-apr
--with-apr-util
--with-apache-headers 

Usage:

The module must be loaded before use. Example:

LoadModule authn_citadel_module /usr/local/lib/libmod_authn_citadel.so

The path to the module on your system may vary, and should be adjusted accordingly. The following configuration directives are used to configure Citadel authentication in a valid Apache configuration block (i.e. location or directory):

  • CitadelServer <host>: The Citadel server to contact for authentication. Can be either a fully qualified hostname or an IP address.
  • CitadelPort <port>: The port that the Citadel server should be contacted on. This is port 504 in most installations. Defaults to 504.
  • CitadelTimeout <sec>: The number of seconds to time out communication. This currently defaults to 2. Not all communication routines are using this in current versions, but it will be used in future revisions.
  • CitadelUseSSL <y/n>:  Determines if the connection to Citadel will be encrypted with SSL. The value passed in <y/n> can be either "Yes" or "No". This should ALWAYS be set to Yes if the Citadel server is hosted on a remote server, or if the communication between the web server and Citadel are traveling across an insecure network which could be sniffed. Defaults to "yes".
  • CitadelMinLevel <l>:  The minimum access level required to be granted access. The value <l> can be any single-digit value between 0 and 6. Defaults to 1.

As this is a basic authentication module, The AuthType should be set to "basic" within the configuration block. The AuthBasicProvider is "citadel".

Example configuration:

<Directory /var/www/>
  AuthType basic
  AuthBasicProvider citadel 
  AuthName Citadel Server 
  Require valid-user 
  CitadelServer 127.0.0.1 
  CitadelPort 504 
  CitadelTimeout 2 
  CitadelUseSSL Yes 
  CitadelMinLevel 2 
  Options Indexes FollowSymLinks MultiViews 
  AllowOverride None 
  Order allow,deny 
  allow from all 
</Directory>

To-Do:

  • Use configuration option for all network timeouts
  • Migrate OpenSSL networking code to the apr_util functions

Developer:

  • Stuart Cianos <scianos@alphavida.com>