Security

DocDB Security Considerations

Security for DocDB is determined by three sets of permissions:

1. File level permissions - These depend on your operating system
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 four 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.

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: htpasswd/bin/htpasswd -c .xxxpasswd username 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: htpasswd/bin/htpasswd xxxpasswd username

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:

• Access can be revoked for a single user without changing a shared group password.
• A user can be a member of multiple groups which don't overlap (In DocDB, one group can be a sub-group of two different sub-groups without quitting the browser, a user would have to know the password for a group that was the master group of both sub-groups.
• The user is positively identified and the password cannot be sniffed.

Read access to files within documents is still controlled by shared group.

Shibboleth

This access mode is provided as an example and is customized to use at CERN with the Shibboleth single sign on (SSO) scheme used at CERN. However, it could be easily adapted for other installations. Group membership for individuals is almost exclusively determined by the SSO system and those groups are mapped into DocDB groups.

Fermilab SSO

Also provided as an example. This is similar to Shibboleth, however Fermilab has a large user base with certificates, so there are parts of this setup that also set groups by determining which certificate(s) belong to the same user.

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 a combination of SSO, 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 method, but allows users without a such a method (e.g. reviewers or 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.

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 the database server and each database on that server.

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 username and password every time you make an administrative change.

For convenience, these examples use docdbadm as usernames for both the web interface for DocDB and the MySQL database. They do not have to be the same.