Introduction
This document describes the security implementation in AllegroGraph. See Security Overview for a description of overall security features in AllegroGraph.
Database security is primarily concerned with protecting the database from unauthorized access. This includes preventing unauthorized people from accessing data in any fashion (reading, adding, or deleting), and preventing authorized persons from doing things they are not authorized to do (preventing, for example, someone authorized only to read data from modifying data).
AllegroGraph uses industry-leading security features which allow you to protect your databases from unauthorized access and modification.
It does this by (1) only permitting registered users to access the system, (2) defining roles which grant specific permissions, and (3) assigning each user to one or more roles.
The distinction between authentication and authorization is important. users are authenticated when they access the database by providing a username and password which are known to AllegroGraph. Authorization is an aspect of a role: are users assigned to a role authorized to access, add, or modify specific data? Roles are defined by an administrator, as described below, and users assigned to a role have a specific list of permissions, as we describe below. A user may have more than one role.
Note that user security depends in part on users keeping their relevant information secure. If someone other than the actual user knows the username and password and has access to other relevant information, the AllegroGraph will not be able to prevent that person from accessing data. There is support for anonymous users. These usually have a single, typically limited role assigned to them
All administrators and users should note that security is a joint responsibility. AllegroGraph cannot protect against access when passwords are compromised or when people can access the machine running the AllegroGraph server when they should not.
Administrators can use the tools provided by AllegroGraph along with their own policies and common sense to protect data from unauthorized use and modification and to facilitate authorized users in performing their legitimate tasks.
What can a role specify?
AllegroGraph administrators can define roles, and assign each user to one or more roles.
Here is what can be done to an AllegroGraph database:
Triples can be examined. (This is usually done by queries, which ask for all triples which satisfy various conditions -- all triples that have object "employee" or all triples that have predicate "has salary", or all triples whose subjects are subjects of a triple with "is a" as the predicate and "employee" as the object, and whose predicate is "has salary" -- that is, return all triples which give salary data for employees.)
Triples can be added. (This is how new data is added.)
Triples can be deleted. (This is how data is removed and also, combined with an addition, how data is modified. If you get a raise, this fact can be reflected in the database by deleting the triple ("John Smith" [i.e. you] "has salary" "$50000") and adding ("John Smith" "has salary" "$55000").)
You can add or modify parameters and settings of the underlying database. This includes adding stored procedures.
If you can add or modify parameters and settings, then in fact you can do 1-3 as well. In general, only a few roles (typically assigned to users called superusers) should be authorized to do so.
For 1-3, it is desirable to be able in some fashion to limit which triples can be accessed. And the set of accessible triples might be different for examining, adding, or deleting. Suppose, for example, the database contains information about employees at a company. Here are some possible roles and permissions:
Any employee can access other employees name, extension, title, and supervisor.
Employees can choose to allow their personal address and phone number to be accessed by any employee.
People in payroll can view salary data.
People in human resources can access and modify all employee data. They are the only people who can modify data.
Implementing security
Security in AllegroGraph is implemented by:
Defining users. A user is given an username and a password and can only access the system using that username and password. A Guest user who logs in as anonymous may be allowed. They would not require a password and all individuals who log in as the Anonymous user have identical permissions. Each user has a set of permissions (from a system-defined list of available permissions).
Defining roles. A role is a collection of permissions. Roles are defined to make administration easier and more efficient. One could achieve the same end result by simply giving each user the permissions associated with the user's role(s). The permissions are Superuser, Start sessions, Evaluate arbitrary code, and Control replication. Further, read, write, or read/write permission can be set for each catalog and repository. We will discuss these permissions below.
Specifying filters. A security filter, described below, prevents roles or individual users from accessing (both reading and writing) triples with specified subject, object, predicate, and/or graph.
Classes of roles
Users can be grouped in various ways. Here are some suggested broad categories (these aren't AllegroGraph categories, just ideas about how you might classify your users):
Trusted expert roles: a trusted expert will usually be given all permissions. The administrator is (usually of necessity) a trusted expert and others may be as well. It is unusual for persons not part of your organization (in some broad sense) to be trusted. Users with all or most permissions have the ability to cause malicious damage.
Trusted ordinary roles: some users may be fully trusted but not programming experts. These persons usually are not given permissions which would allow them accidentally to compromise the system but are given all other permissions. (It is not easy to damage the system accidentally, but it is easier when you have direct access to the programming environment (via the ability to connect to the server via the Lisp client, for example). Those permissions may be denied to ordinary users, even though they are trusted.
General internal users: often you will have databases which members of your organization will need to access, perhaps reading only, perhaps able to read and write. These users will normally not be given the same permissions as the trusted users.
Outsider roles: you may want your database to be viewable by outsiders. You may even want some outsiders to have the ability to write data. As a rule of thumb, outsiders should never have general permissions. It is possible to enable anonymous access.
Accessing AllegroGraph
A typical way to access AllegroGraph is through the AGWebView interface. It can also be accessed using a Java or Python client, Gruff, or Lisp (see Lisp Quick Start). We will discuss AGWebView access security in this document.
Managing Users
To open an AllegroGraph repository in AGWebView, you must supply an AllegroGraph user name and password (except for the anonymous user, if that is allowed). AllegroGraph users can differ in terms of repository access, ability to manage other user accounts, and permission to create sessions and to run arbitrary code.
This section describes user-related tasks and how to perform them. Many of these tasks can be performed on the User Management page. See the description of that page for a list of the controls found on it.
Initial Superuser
An initial superuser is created during the AllegroGraph server installation. This user typically appears in AllegroGraph documentation as user "test", password "xyzzy".
You must change this password when you start using AllegroGraph for sensitive work. As stated, the initial password is mentioned in public documentation. Neglecting to change the password may allow access by unauthorized users. AllegroGraph does not itself vet passwords for safety and quality. Passwords, particularly the superuser password should be chosen so they cannot be discovered by simple guessing techniques.
This superuser can create and manage other users, can start sessions, can evaluate arbitrary code, and has read/write access to all repositories in all catalogs.
Note that you want to have at least one superuser at all times, because only an AllegroGraph superuser can manage permissions and access for other accounts.
Create a New User
When logged in as a superuser, on the AGWebView User Management page, click the add a user link. This opens a form for the user name and password of the new user. User names and passwords are case-sensitive. You are not allowed to create a user without also specifying a password (except for the anonymous user).
Set Permissions
Click the "edit" link next to the new user's name on the User Management page. You will see four checkboxes:
A Superuser automatically has all possible permissions and unlimited access. A superuser can also create, manage and delete other user accounts. Non-superusers cannot view or edit account settings.
A user with the Start Sessions permission can use features that require dedicated sessions, such as transactions and Social Network Analysis (SNA). If you try to use these features without the appropriate permission, you'll encounter authentication errors. This permission should be withheld from users who do not need it because it spawns back-end processes that occupy memory and consume CPU cycles.
A user with permission to Evaluate Arbitrary Code can run Prolog "select" queries. This user can also do anything else that allows executing Lisp code, such as defining Prolog select generators for SNA, or doing eval-in-server, as well as loading server-side files. This permission should be only be given to trusted users, and even then withheld from users who do not need it, because it opens a window to potential serious server-side mischief (someone with this permission can do whatever the (Unix) user id of the server can do).
A user with Control Replication permission can set up automatic replication of a triple-store across multiple servers. This allows AllegroGraph's warm standby and point-in-time recovery features.
It is typical for most users not to have any of these permissions enabled. Note again that Evaluate Arbitrary Code allows a malicious user to disable security by creating a backdoor entry to the server (among other things). Again, that permission should only be given to trusted users.
Access Control
You can specify which catalogs and repositories can be accessed by a role. For each catalog and repository, you can specify no access, read only, write only, or read/write. This is the primary way data are protected from unauthorized access. You can (see below control access at the triple level, so you can prevent a user or a role from, say, accessing any triple with has salary. But you can also put all such triples in a separate repository or catalog and restrict access to that repository or catalog.
Immediately under the permissions checkboxes you will find the Access Control form:
Select the access mode (read, write or both) and then select the catalog and repository. Asterisk (*) behaves as a wildcard in these fields. The forward slash (/) designates the root catalog. Click the "OK" link to add this permission. You can use the form repeatedly to add multiple permissions.
You will see the new permissions listed on the screen, just above the Access Control form:
The "remove" link deletes the permission.
Managing Roles
A "role" is a predefined set of permissions settings. Roles let us centrally manage the permissions of a class of users. Security experts prefer to manage access through roles because it makes managing many users easier and more rapid. For example, it lets them respond quickly to an emergency. A single mouse-click on a role can revoke permissions from scores of users at the same time. To make the same change in all the individual user accounts would take much more time.
Roles can be created on the User Management page. Click the "add a role" link. Enter the name of the new role in the resulting form. Note that role names should be descriptive and specific, because they become entries on a potentially long list of available roles.
Once the role has been created, give it permissions just as if it were a user account.
To apply a role to a user account, click the "edit" link for that account.
Select the role from the list and click the "OK" link. The user's local permissions and access indicators will not change, but he/she will have the full powers of the role.
Anonymous Access
If you create a user named "anonymous" (the case is significant, all lowercase), AGWebView will enable anonymous login. This is the only user account that can be created without a password.
On the User Management page, click the "add a user" link and type "anonymous" in the __Username__ field. Then click the "OK" button.
From this point on, AGWebView will automatically log in the anonymous user each time you connect to the server. This makes AGWebView available to anyone, but only within the limits imposed by the permissions and access settings of the anonymous account. Be sure to give the anonymous account read access to at least one repository or the visitors won't be able to see anything.
Anonymous access does not prevent you from logging in as another user. Look for the "User: anonymous > login" menu item in order to log in to your account.
Self-Enrollment
AGWebView can permit otherwise anonymous users to self-enroll by registering usernames and passwords for themselves. These self-enrolled users have the same permissions and access as the anonymous user, but they can also have private namespaces and their own saved queries.
A superuser enables this feature in the Site Settings section of the Root Catalog page, by clicking the "Allow" link.
When self-enrollment is allowed, there is a "User anonymous > register" menu item in the page banner. This link opens a form for creating a new user. The new user is automatically logged in after registration.
Ports
By default, the AllegroGraph server's HTTP API will open a random TCP port with a number greater than 1024 for new sessions (see the Sessions section in the HTTP Protocol - SPARQL Endpoint document). In order to allow a firewall more effective control over access to the AllegroGraph server, we recommend specifying a SessionPorts range in the agraph.cfg file, and then filtering only these ports.
Issues with transferring passwords etc. over the internet
When running an AllegroGraph server that is accessible from untrusted networks (e.g. the Internet), administrators need to be aware that passwords will be transferred in unencrypted form between AllegroGraph clients and the server. To avoid exposing users' AllegroGraph passwords to malicious third parties, you should open the AllegroGraph service to untrusted networks only on an SSLPort (using the correct SSLCertificate settings) or through a SSL-enabled reverse proxy such as pound or nginx.
Security filters
A security filter can be set by an administrator (a superuser). It can prevent access (both read and write) to triples with a specified value for subject, predicate, object and/or graph.
What threats do triple-level security filters prevent?
Security filters can prevent users from accessing (both reading and writing) privacy-sensitive data. When querying, triples filtered out by a security filter will appear as if they weren't in the store in the first place. In contrast, attempts to add them or remove filtered triples will result in an error.
The administrator must take care to allow users access only to those triples that are safe for these users to see; this can be hard to accomplish with only subject/predicate/object-based filters when there is deep graph structure involved. In these cases, it is advisable to put triples that should be (or should not be) accessed by a certain set of users into their own graph, and define a filter set using that graph.
Information that cannot be protected
Note that even though users do not see triples that are filtered and cannot access what filters apply to them, they may be able to infer how triples are filtered if they wish to. For example, if triples with predicate "has salary" are filtered, a user who has write permission in general can try to create a triple ("Nobody" "has salary" "0"). An error will be signaled and the user can then infer it was because of a filter. A few more tests will likely make clear it is triples with predicate "has salary" that the user cannot see. Similarly, using get-triple-by-id may show holes (ids 90-99 and 101-110 all work but id 100 returns nil).
A security filtered store does not maintain the illusion that parts of filtered-out triples are not present in the store. This means that a user using (get-triples :s !<filtered-out-part>) will get a cursor instance and T, indicating that the part !<filtered-out-part> was found in the store. The user might then be able to draw conclusions about certain names of resources that are filtered out, and might be present in the store.
Setting security filters for a user or a role
Security filters can be set by a superuser in the user administration screen of AllegroGraph WebView. If you assign filters to roles, these filters will be merged into a set of effective filters for each user with that role accessing a store.
Enter the criteria for the filter pattern in the subject, predicate, object, graph fields of the filter table (use the regular part syntax for URIs:
To remove a filter, click the X mark next to the filter pattern.
Updating the set of filter patterns takes effect only for new sessions; sessions that are running while you modify the set of filters will still use the same triple pattern as before.
Effect of "allowing" or "disallowing" a triple pattern
Each security filter pattern can specify to "allow" or "disallow" a certain pattern of triples. Both types of pattern can remove triples from the set of triples that a user will see:
- disallow will filter out all triples that match the filter pattern.
- allow will filter out all triples that do not match the filter pattern.
This makes allow the more restrictive of the two filter types: it will remove every triple that doesn't match the filter pattern, whereas disallow only removes those triples that exactly match.
Composing security filters
As security filters are based on set intersection and set difference, a filter set with both allow and disallow filters will always result in the same set of triples when applied to a store, no matter in which order the filters are applied to the store.
The composition of the filters:
- allow predicate:
- allow predicate:
- disallow subject:
will result in a store that appears to contain (from the perspective of the affected user/role) only triples with the predicates <http://example.com/#only-this> or <http://example.com/#or-only-this> and object <http://example.com/#with-this>, but will never contain any triples with the subject <http://example.com/#some-sensitive-data>.
Effect of security filters on local stores (security relevant)
Per-user and role security filters only affect HTTP clients, which does not include local Lisp clients. These have total access (read and write) to the store, no matter what security filters are in place.
