Summary

Access to timothy can be controlled by authenticating each user through Apache.

Pieces of Timothy that can be secured

There are four scripts that can be called through your browser for differing parts of Timothy:

  1. retrieve.py downloads a particular document which is specified with the document's path. IE http://localhost/timothy/retrieve.py/MyCategory/MyDocument.
  2. ldt.py (Look Don't Touch) allows the user to browse the material available and to download files. The site itself cannot be changed.
  3. manager.py supplements browsing with the ability to create new categories, up load documents and drop either type of node.
  4. post_config.py is an administrative script for setting certain configuration items for Timothy.

Each script can have an set of users who may use the script by setting an appropriate <Location> in the configuration file. So that retrieve.py would be available to all users from all domains; ldt.py to internal users (perhaps from select domains); manager.py to certain users who maintain the site and post_config.py to certain administrators.

Timothy can be configured for multiple database instances for one installation. Accordingly, one or more instances may be limited to differing sets of users.

Apache Security

Apache provides a wide array of options to control access to a web site. We will focus on how to limit access based on <Location>, an Apache technique for determining access privileges from the URL from the client. We will couple this to the Alias command so that the same scripts can function in different environments.

The first step in security setup is choosing various authentication options available in Apache. All of these choices are associated with specific modules that must be loaded. Some require additional programs, for example use of an ldap database.

We recommend reading the Apache How-To/Tutorial, Authentication, Authorization and Access Control. We limit this discussion to an AuthType of Digest and the default authentication provider, mod_auth_default.

Step 1 load the required modules in Apache

We will use mod_auth_digest as the authentication type; mod_auth_file as the provider and mod_authz_groupfile for the Require directive. We test on a Debian system where Apache modules are include files in /etc/apache2/modes-enambled.

Step 2 set up Aliases to Timothy's cgi files

Use the ScriptAlias command to point Apache to timothy's cgi scripts. Use a <Directory> section to limit what Apache can do in the timothy cgi-directory and to set options consistent with cgi scripts. viz.:

ScriptAlias /timothy/ /opt/timothy/cgi-bin/ <Directory "/opt/timothy/cgi-bin/"> AllowOverride None Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch </Directory>

Step 3 Add authentication commands

Use a <Location> block to control authentication based on the URL of the request. Set the AuthType to Digest; create and point apache at the user file with AuthUserFile and group with AuthGroupFile. Finally identify the priviledge users with Require. viz.:

<Location "/timothy/" >
   Authtype Digest
   AuthUserFile /etc/apache2/htpasswd
   AuthGroupFile /etc/apache2/htgroup
   Require valid-user
   AuthName "Timothy"
   Order allow.deny
   Allow from all
</Location>

Note the AuthName command. This identifies the instance to the client browser. The Browser will display this name when asking for a username and password. On subsequent requests the browser will answer apache's challange with the Username and password given for this name.

Step 4 setup the password file

Use the shell command htpasswd to create and update the password file.

htpasswd -c NewPasswdFile FirstUser will first prompt (twice) for the FirstUser's password ad then create the file. Subsequent changes to the user's password can be done by htpasswd -f NewPasswdFile FirstUser. New users by htpasswd -f NewPasswdFile -a NewUser.

You may now require user FirstUser or require valid-user.

Optional Step 5 the group file

Apache group files look like a unix group file. There is a line for each group. The line starts with the group name, a semicolon and a comma separated list of users.

timothy:FirstUser,NextUser

You may now require group timothy.

Finer grained control

You may set up a location box for each of the four scripts in Timothy's cgi library.

For example <Location "/timothy/post_config.py"> would restrict access to Timothy's configuration to site administrators. A simliar <Location> block could be setup for /timothy/manager.py.

Apache matches the url to location blocks in the order thy appear in the configuration file so these finer grained items should appear before a general purpose <Location "/timothy/">.

Multiple Database Instances

In some environments multibple databases, with different user bases may be called for. Each instance would be accessed through a different url and configured for differing access.

Step 1 Configure Timothy

The Timothy Configuration file, timothy.conf ships with two sections, defaults and timothy by adding a new section pointing to a new database one creates a new instance of timothy. Each instance must declare the database, the operational user to log into postgress. During installation, the docmgr user is setup to create databases as well as access the timothy database. Generally only the defaults section and timothy section need declare the postgressql administrator.

So:

[AsecondIIns]
host=localhost
port=5432
database=Asecond
user=docmgr
password=995zk

Step 2 Create the database

Attach to postgres as the Timothy user, docmgr. Create and setup the database.

Handy tool -- newInstance.py

All of this can be accomplished by using newInstance.py which will create a new database, populate it with meta data and add a section to timothy.conf

Usage: newInstance.py [options]

Options:
  -h, --help            show this help message and exit
  -i INSTANCE, --instance=INSTANCE
                        name of the instance to create
  -d DATABASE, --database=DATABASE
                        the name of database to create
  -s SOURCE, --source=SOURCE
                        name of the instance to mimc
  -u USER, --user=USER  name of the database owner
  -p PASSWORD, --password=PASSWORD
                        User password
  -t HOST, --host=HOST  The name of the postgres host
  -r PORT, --port=PORT  The port to connect to postgres
  -g DEFAULT_DB, --default-db=DEFAULT_DB
                        A database that acutally exists for the initial
                        connection.

One must provide at a minimum the instance to be created. Timothy will create a database using the default credentials from timothy.conf. More extravgantly, one may supply the credentials individually on the command line.

Sample Apache Configuration

# Apache2 configuration settings for timothy.  Include this file in
# the apache configuration file after installing timothy.
# $Id: timothy-http.conf,v 1.2 2012/12/06 22:29:40 dalyw Exp $

	ScriptAlias /timothy/ /opt/timothy/cgi-bin/
	<Directory "/opt/timothy/cgi-bin/">
		AllowOverride None
		Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
	</Directory>
	Alias /DM-stylesheets/ /opt/timothy/stylesheets/
	<Directory "/opt/timothy/stylesheets/">
		Options Indexes FollowSymLinks MultiViews
		AllowOverride None
		Order allow,deny
		allow from all
	</Directory>

	Alias /DM-js/ /opt/timothy/js/
	<Directory "/opt/timothy/js/">
		Options Indexes FollowSymLinks MultiViews
		AllowOverride None
		Order allow,deny
		allow from all
	</Directory>
	Alias /DM-icons/ /opt/timothy/images/
	<Directory "/opt/timothy/images/">
		Options Indexes FollowSymLinks MultiViews
		AllowOverride None
		Order allow,deny
		allow from all
	</Directory>