Authenticating DSpace Users

The DSpace documentation lists several options for authenticating users: basic password access; Shibboleth; LDAP; IP Address; and X509. These can be combined in an authentication “stack” in which a set of authentication options are tried until one succeeds.

Our authentication stack allows four levels of access:

  • anonymous – users who don't log in to the system, but can browse the communities and collections and download any publicly available data on the system;
  • eecs – users from the School of Electronic Engineering and Computer Science (EECS) users can log in with their EECS credentials for access to a wider range of data;
  • users added by administrators – this allows external users (e.g. research collaborators) additional rights within the repository;
  • administrators – to set up communities and collections and to manage users when required.

In addition, users on the QMUL network are automatically placed in a “QMUL” group in DSpace based on their IP address. This allows “intranet” type material to be controlled in the system.

In order to apply these levels of access, we use three of the DSpace authentication options: basic password access; LDAP; and IP Address.

Password authentication
Password authentication is the basic authentication setup when DSpace is installed and verifies login details against those stored in the DSpace database.

From the command-line, the DSpace command

dspace create-administrator

allows a new administrator account to be set up. The user is prompted for the administrator's email address, first and last names and password and a DSpace account is created.

Generally, new users are set up in DSpace by registering their email addresses in the system through the web interface.
Administrators can add new users, or users can enter their own details into DSpace (“self registering”). Passwords for new users are set in response to a password reset email, therefore DSpace must be configured, via dspace.cfg, to be able to send email if non-administrative accounts are required. Users can change their own password online, but even administrators cannot set passwords for other users – administrators can send “password reset” emails to registered email addresses.

The DSpace authentication-password.cfg configuration file allows self-registration to be limited to specific email addresses (by restricting the right-most part of the email address) e.g. we can restrict self-registration to users from within the QMUL School Of Electronic Engineering And Computer Science by specifying:

domain.valid = @eecs.qmul.ac.uk

All users with emails that match that domain would then be allowed to set up an account within our DSpace instance.
Control over which email addresses can self-register is not as fine grained as we would like – the repository is for a specific research group within the School and therefore we would like to be able to control access for that group. Additionally, users should not be required to use a new login and password for the repository – it is college system and should use a standard college sign-on. We therefore looked at other authentication options within DSpace.

However, a new non-administrative user does not automatically get any rights within the repository – that depends upon permissions being set to communities and collections.

By specifying that all users that use password authentication should be added to a specific group, it is possible to create default permissions for those users. Creating the group passwordControlledUsers in DSpace and modifying the authentication-password.cfg to contain the line

login.specialgroup = passwordControlledUsers

will add users that login using a DSpace password to the passwordControlledUsers group. Specifying that this group has download access to a collection then allows all users that can log in to the system using a password to download files from the collection.

LDAP Authentication

The Lightweight Directory Access Protocol (LDAP) is a TCP/IP protocol for accessing directory data. Data is represented as a Directory Information Tree (DIT) of entries branching from a common root entry. Each entry is identified by a Distinguished Name (DN, basically the path through the tree from the entry to the root entry). Entries can relate to users, computers, groups etc. the specific contents depending upon the intended purpose of the LDAP instance.

Within the School, there is an LDAP service for access control. This allows a single username and password to be used to access various school-wide services (e.g. the intranet and email). Configuring DSpace to link to the LDAP directory allows us to verify users as members of the School and avoids them having to remember another username and password (or have their internal password used independently for DSpace).

DSpace supports authentication of users using LDAP simple authentication and there are two versions of the LDAP authentication scheme available: LDAP Authentication and Hierarchical LDAP Authentication.

The standard LDAP Authentication binds to a specified LDAP entry (the “object context” DN) to verify the supplied username and password and then retrieves the user details (name, email, phone number) from another entry (the “search context” DN - possibly different to the object context, possibly the same).

The Hierarchical LDAP Authentication plug-in extends the LDAP processing. Hierarchical LDAP searches a subset of the LDAP tree for the entry under which the user is listed (either anonymously or by using an administrator login). The user details are accessed from that LDAP entry. User authentication is then carried out by binding to the DN found for the user.

For both versions, we need to supply:

  • the URL to the LDAP service;
  • the search context DN;
  • the attribute names for the username, email address, first name, surname, and phone number;
  • the DSpace group into which all LDAP authenticated users should be placed (optional).

Additionally, basic LDAP requires the object context DN, and Hierarchical LDAP can optionally use:

  • a search username and password (if the server doesn't allow anonymous access);
  • the number of levels in the LDAP tree to search.

The basic parameters having been provided by system administrators, it is easiest to use LDAP tools to browse the LDAP tree and confirm attribute names and DNs. We have used the Ubuntu “LDAP Administration” tool and the open-source cross-platform Java application Jxplorer to confirm LDAP settings.

Within EECS, the LDAP server contains users in a single “people” structure containing the details of everyone in the department and a separate “groups” structure listing groups and, within each group, its members. Each user has a “uid” identifier, and group members are identified by their “memberUid”. Sadly, DSpace doesn't allow us to use this structure to restrict access to members of the research group – DSpace assumes that the same field name will be used for both the search and object access.

We have not looked into why two entirely separate LDAP plugins are provided, but it seems that the differences in functionality are minimal and that rather than requiring two very similar pieces of code, either a single plugin or two plugins based on a common parent would make sense. A more generic LDAP plugin with an understanding of groups would add a powerful tool for managing users in DSpace.

Although we allow DSpace accounts to be created automatically for users that are authenticated through LDAP, it is not until an administrator assigns them privileges that they gain the ability to affect the repository. LDAP authenticated users can automatically be added to a group in the same manner as password authenticated users i.e. by adding the line

login.specialgroup = ldapControlledUsers

to authentication-ldap.cfg and creating the group ldapControlledUsers in DSpace. This then allows users authenticated by the college LDAP system the privileges granted to that group.

IP Authorisation

In addition to authentication of users as anonymous, LDAP or password controlled, we can add users to DSpace groups based on their IP address. This means that computers with IP addresses within the QMUL network can be automatically given additional privileges for data access (e.g. for data for QMUL internal use only) or that specific computers, identified by their IP addresses could be allowed full access to the system (e.g. a stand-alone remote machine for browsing repository contents).

In order to implement this, the authorisation stack needs to include the IPAuthentication plugin and the authenticate-ip.cfg file needs to be set up. The configuration file is straightforward, consisting of multiple lines of the form

ip.[GROUPNAME] = [ADDRESSPROFILE]

with [GROUPNAME] being the name of a group in DSpace and [ADDRESSPROFILE] indicating valid (and invalid) IP addresses. Both IPv4 and IPv6 addresses can be specified, and various forms of address masking are available. However, in our attempts to set up IP authorisation we could not get either netmask or CIDR style masking to work – although specifying a partial IP address did work i.e. specifying the IP address as 10.1.2.3/24 or 10.1.2.3/255.255.255.0 did not work, but using 10.1.2 did.

Conclusion

DSpace offers a number of options for user authorisation, these allow a flexible approach, combining single-signon for internal users with specified usernames and passwords for invited "guest" users. However, many elements are only supported in specific ways: LDAP support is restricted to specific approaches to LDAP authentication and doesn't support assigning privileges based on LDAP group memberships; IP Authorisation works with partial IP addresses but doesn't seem to support netmasks. That said, DSpace is open source, and if facilities are needed rather than just "nice to have", then participation in the DSpace project would allow desired features to be developed and bugs to be fixed.