User Authentication and Access Control

• 1. Overview
• 2. Changing the Administrator Password
• 3. Creating Users
• 4. Resource Permissions
  • 4.1. Changing Resource Permissions
  • 4.2. Changing Resource Ownership
• 5. Authentication and Cocoon
• 6. Using XQuery Access Control
• 7. LDAP Security

1. Overview

In this section, we discuss eXist's security features and how to manage database users and groups. Beginning with version 0.9, the eXist database engine supports basic user authentication and access control. Unix users will find the format for these authentication and permission settings very similar to that of the Unix operating system. To make it easier to manage users and modify resource permissions, eXist provides an interactive interface to execute commands and perform administrative tasks, as discussed in the following sections. This interface is facilitated by the XML:DB service included with eXist.

Every eXist database user has an account with a username, password and other information that is stored in the database. Furthermore, every user belongs to one or more groups - and respectively, every resource in the database is owned by a user and by a group. By default, the owner is set to the user who created the resource, and his primary group, but eXist allows for different permissions for the owner, the owner's group and others. However, only the owner of the resource (or dba users) can change these permissions.

User and group information is found in the designated XML file /db/system/users.xml located in collection /db/system. This file is generated during database startup. The following is a simple example of a users.xml document:

<auth>
    <groups last-id="3">
        <group name="dba" id="1"/>
        <group name="guest" id="2"/>
        <group name="mygroup" id="3"/>
    </groups>
    <users last-id="3">
        <user name="admin" uid="1" home="">
            <group>dba</group>
        </user>
        <user name="guest" uid="2" password="e55d929cdbc8d5a7ce3bda044bc69f59" home="">
            <group>guest</group>
        </user>
        <user name="user-1" uid="3" password="7f0261c14d7d1b8e51680a013daa623e" home="my-collection">
            <group>my-group</group>
        </user>
    </users>
</auth>

As we see from this example, passwords are encrypted using an MD5 algorithm (e.g. user-1 has the MD5-encrypted password "7f0261c14d7d1b8e51680a013daa623e"). Therefore, whenever a user enters his or her password, the database generates an MD5 encryption and compares it to the encryption stored in users.xml. Since it is very difficult for users to guess the original password from the MD5 string, passwords in eXist should be sufficiently secure.

Note that the /db/system collection is (by default) only readable by dba users (although it is possible to make it accessible by other users). The dba group is specially reserved for database administrators, and only dba users are allowed to create or remove users, or change permissions for other users.

2. Changing the Administrator Password

When the database is started for the first time, two default users are created: "admin" and "guest". (The "admin" user is a member of the dba group, and therefore has administrative privileges; the "guest" user is a member of the group "guest" and is not an administrator). At this inital point, the "admin" password is set to null, and so access to the database is initially granted to everyone. To set restrictions on database access, you must first set a password for the "admin" user. To do this, use either the Admin Client or the administrative web interface. If eXist is used for applications intended for online web publications, or as an embedded library, it is exposed it to potential exploitation. It is therefore strongly advised that you first change the admin password. The Admin Client graphical user interface has a dialog box for user management. To open this dialog box, enter Ctrl-U or select Tools »Edit users. This will pop-up the dialog box as shown to the right. At the top, select the "admin" user in the table of users Type in your password into the corresponding fields Click the "Modify User" button to apply the changes

You can also set a new administrator password on the command-line in a console or shell. Enter the following at the command prompt:

Access control should now be enabled. To start the shell-mode client as an administrator, you must specify the -u option, following these steps:

The other default user, "guest", also has the password "guest". The guest identity is internally assigned to all clients which have not authenticated themselves. For example, the Xincon WebDAV interface does not support authentication, so "guest" is assumed for its users by default. Note that this aspect of WebDAV is a potential source of confusion, and you have to be careful about setting read/write permissions for this API.

3. Creating Users

It is easy to create new users using the Admin Client. In the Edit users dialog box, fill in the Username, Password, Password (repeat), and Home-collection fields, and assign a group (or groups) for the new user. Finally, select Create User. The new user will appear in the list of users in the top panel.

The adduser command also allows you to create additional users. The command asks for a password and a list of groups to which the user should belong. An example is shown below:

To check that the user has been added, use the command users to display a list of all known database users.

4. Resource Permissions

The default that is based on the UNIX read, write and execute flags for owner, group and world. For eXist, the execute is update.

Using the Admin Client or the command-line, You can list the permissions assigned to each resource (this assumes the permissions property in client.properties is set to true). An example listing is shown below:

As shown on the left-hand side, the Admin Client displays resource permissions in a similar format to the output of the Unix ls -l command: a ten-character code. The first character represents the type of resource: - [hyphen] for documents (files) and d for collections. The next three characters are the permissions for the user: a - [hyphen] is used for denied permissions, r for read, w for write, and u for update. The next three characters (five through seven) set the permissions for groups, and the last three for others (i.e. anyone else who can access the database). Given the previous example, we can see that all files except r_and_j.xml are owned by user "admin" and group "dba".

As mentioned in the previous section, the database root collection /db initially has permissions set to drwurwurwu, i.e. full access is granted to everyone. Also note that -rwur-ur-- is the default setting for all newly created resources, i.e. the group has read/update permissions, but not write permissions; others are only allowed to read.

Some XQuery functions expect to get the permissions as an octal number. The octal notation is quite common on Unix systems. In eXist, the first 3 bits correspond to the user permissions, the second 3 bits are for the group and the final 3 bits for others. In order to set the permissions to -rwur-ur-- you would need to specify 0754 in octal notation.

4.1. Changing Resource Permissions

Permissions can be changed using either the Edit Properties dialog box (shown on the right) in the Admin Client or the chmod command in the shell window. The Edit Properties dialog box is opened by selecting Files »Resource Properties from the menu, OR by clicking on the Properties Icon (image of checkboxes) in the toolbar. This dialog box shows permission settings for all database users and groups.

On the command-line, you can use the chmod command to change permissions. This command expects two parameters:

For example, to grant the write permission to the group and deny all to others, you may use:

If you do not specify a resource in the first argument of the chmod command, the permission string will be applied to the current collection. This is an important feature if you want to change permissions for the /db root collection, which would otherwise not be possible. For example, to deny write permissions to others for the entire database, change directory to the root collection (i.e. enter cd ..) and enter:

4.2. Changing Resource Ownership

Only the owner has full control over a resource, and it is sometimes important to change this ownership. The Admin Client provides the chown command to do this. The command expects three arguments:

For example, to change the owner of the file r_and_j.xml, you would do the following:

5. Authentication and Cocoon

Cocoon uses the XML:DB API to access eXist, and so has to authenticate the user like any other XML:DB based application. To make this easier, eXist contains a Cocoon action for this login task called XMLDBSessionLoginAction. The action presents a login interface page, checks the entered username and password against the database, and stores them in a newly created HTTP session variable. As long as the session remains valid, no further login is required. It is recommended you read Cocoon's documentation on actions for detailed information how actions work in this framework. The following snippet shows an example from Cocoon's sitemap.xmap configuration:

6. Using XQuery Access Control

Please see separate documentation on XACML in eXist.

7. LDAP Security

Please see separate documentation on LDAP Security.