DocDB Security Considerations

Security for DocDB is determined by three sets of permissions:

  1. File level permissions
    Depending on your installation, these may include both UNIX style permissions and AFS group directory permissions.
  2. Web permissions
  3. MySQL permissions

File permissions must be set correctly for the webserver to download documents into $file_root. See customizing DocDB for more.

DocDB Security Models

Currently DocDB has two possible security models. You have to pick one for each instance. (However, two instances may share the same MySQL data and document files. More on this later.)

Group based HTTP Basic Authorization

This is the easiest and simplest method of authorization. You have a number of groups which actually correspond to users in the HTTP authorization scheme. Access to the DocDB scripts is granted to each group with a unique password. DocDB controls which meta-info is shown to users based on the permissions of the group. Access to files within documents is controlled by requiring the username and password for a valid group. You should have at least two groups, one for those uploading and viewing documents and one for administering the database.

If you are using an apache webserver, web permissions are controlled with the .htaccess file. The .htaccess file is placed in the DocDB cgi-bin diretory. See customizing DocDB for more.

The htpassword command may be found at: /afs/fnal.gov/files/expwww/computing/home/docdb/auth/htpasswd/bin/htpasswd. To create a password file, cd to the directory in which the AuthUserFile resides (which is specified in the .htaccess file). Run the following command:

where username is the name of a read/write user for the xxx instance of DocDB.

To add a user to an existing password file, use this command:

To change the password of an existing user, use the command above. Users may be copied and pasted between .xxxpasswd files.

Certificate based Authorization

In this access method, access to DocDB scripts is granted not by a shared group password, but by an X.509 certificate you import into your web-browser. This certificate positively identifies you. Each user with a certificate has an entry, within DocDB, which determines which groups they belong too. While management of these certificates and user education is an additional work-load, there are a number of advantages too: Read access to files within documents is still controlled by shared group passwords.

Multi-mode access

Each instance must have an access method, but in the same way that you can set up a public area for publicly accessible documents, you can set up certificate and HTTP Basic areas. Either one can be made read-only, but in practice you'd want to set up the HTTP authorization as read-only. This allows you to require users uploading documents or changing meta-info to be authorized by a secure certificate, but allows users without a certificate (e.g. travelers using an Internet Cafe) to have read-only access to the data.

Administrators and Groups

The DocDB administrator (docdbadm in our case) must then log on to the DocDB instance and add the users created in the .htpasswd file. These users are stored in the "SecurityGroups" table of the MySQL database associated with the DocDB instance.

Within DocDB groups may be subordinate to other groups. A dominant group assumes all the privileges of a subordinate group. Thus, all groups must be made subordinate to docdbadm and all local groups are made subordinate to cdweb. This is done through the administrative functions of DocDB.

Never create documents as docdbadm or choose that group when creating documents. Only use docdbadm for administrative functions that cannot be done as cdweb or the instance user.

Finally, we come to MySQL permissions.

MySQL maintains its own permissions independent of DocDB, web and file system permissions. There are three important accounts for DocDB purposes, as well as the MySQL root account:

  1. docdbadm - administrative account for a particular document database. This is the account whose password you must type in DocDB when performing administrative functions. It is also used when directly manipulating the database.
  2. docdbrw - used for all write functions which modify the database.
  3. docdbro - used for public access to the database, when modification of the database is not possible.
The "root" account is used to set up new databases and set access permissions for the other three accounts.

In MySQL there is a default database named "mysql" which contains the security information for th edatabase server and each database on that server. To use root, you must access the database from localhost only, meaning using a secure SSH or Telnet connection (Kerberos) to connect to the machine hosting MySQL (flxd01.fnal.gov).

DO NOT ATTEMPT TO CHANGE THE MYSQL SECURITY SETTINGS UNLESS YOU ARE SURE ABOUT WHAT YOU ARE DOING!

docdbadm may connect to MySQL using a MySQL client from any machine in the fnal.gov domain. Nothing outside of this domain is permitted access. If you need to use docdbadm from a remote location, you must connect using the Fermilab VPN.

docdbrw and docdbro may access the database from any domain.

The docdbrw and dodbro usernames and passwords are explicitly contained in the CGI Perl script ProjectGlobals.pm. This is how the scripts are able to access the database.

Docdbadm and its password are NOT in the scripts. This is why you must type the administrator password every time you make an administrative change.

For convenience, the username docdbadm is the same for both the web interface for DocDB and the MySQL database. They DO NOT HAVE TO BE THE SAME. However, more typing would be required when using the administrator account.

DocDB License


Document Database