Introduction

AllegroGraph allows specifying users and giving each user specific permissions which allows certain operations and forbids others. An initial superuser is created when AllegroGraph is installed. A superuser has full power to do anything to a running AllegroGraph. Additional superusers can be created and also users with less power. An anonymous user (who can log in without a password) can also be permitted.

Note that certain permissions (particularly the Evaluate arbitrary code permission) effectively allow a knowledgeable user to act like a superuser even without formal superuser privileges. These permissions are noted when they are described below.

AllegroGraph supports Role Based Access Control (RBAC). A role is a collection of permissions. A user who is assigned a particular role has all the permissions of that role (as well as, perhaps, additional permissions separate from the role). Roles are simply a convenience which allows a standard set of permissions to be quickly given to a user.

Managing users

Users have names and (except for anonymous users) passwords. They also have permissions which allow them to perform some actions and not perform others. They may have roles (see Managing roles below).

Users are managed primarily with AGWebView and agtool. The REST/HTTP interface can also be used to manage users and roles. In this document, we describe the AGWebView and agtool interfaces in detail and make only passing mention of the REST/HTTP interface.

Certain configuration directives affect users. These are listed in the Top-level directives for account management section of the Server Configuration and Control document. These affect things like password requirements, automatic suspension or disabling because of lack of use or apparent improper use, and specialized choices like SuperUserCanAccessAllData, which specifies whether superusers can access data by default or must first add access for themselves (an action that is added to the audit log if auditing is enabled). These options must be specified in the configuration file and cannot be changed in a running AllegroGraph server. To change these directives, edit the configuration file and then restart the server.

Allowable user and role names

User and role names may consist of any chacacters except \ (backslash), : (colon), / (forward slash), ~ (tilde), or those characters with code below 32 (that is control characters). The names "." and ".." are also not permitted.

Managing users with agtool: general comments

agtool users is the most powerful and flexible way to manage users (the REST/HTTP interface is as powerful but not as convenient, while the AGWebView interface lacks some features). 

agtool users help

displays the various operations. 

agtool users <operation> --help

displays usage for a specific operation. The general form is 

agtool users [--server SERVER_SPEC] <operation> [options] user

The --server argument defaults to 

--server http://127.0.0.1:10035

SERVER_SPEC can be 

HOSTNAME  
HOSTNAME:PORT  
SCHEME://HOSTNAME:PORT  
SCHEME://[user:password@]HOSTNAME:PORT

SCHEME can be http or https.

If the user who started the AllegroGraph server is executing agtool users on the machine on which AllegroGraph server is running, agtool users will then run under the same uid that the AllegroGraph server is running under. In that case, agtool users acts as if it is being run by a superuser if no user and password are specified (if a user and password are specified, the user must have superuser permission). This behavior is called OS authentication. It is common for production versions to be run this way, and it is also typical for users who are testing personal copies.

A superuser can run any agtool users operation. Other users can run some (generally those that provide information about themselves and in some cases set information, like passwords).

The list of operations include:

We describe adding/removing users, and granting and revoking permissions and access in separate sections below, and then other commands in an other operations section.

Managing users with AGWebView: general comments

Only a superuser can add or remove users and can change the permissions of a user. Superusers can also change a user's password, though that can also be done by the user if the PasswordChangeAllowed configuration directive is yes (the default).

Superusers have access to the Admin menu, and it includes a Users item which, when chosen, displays the Users Page.

The Admin menu with Users indicated

The User page displays a list of current users:

User list and Add a User link

AGWebView tools for managing users start on this page. In what follows, we assume things are being done by a superuser and the User page is displayed at the start of any set of instructions.

Adding and removing a user

When AllegroGraph is configured after installation (see Server Installation) a single user, with superuser privileges is created. Then, if agtool archive restore or agtool archive restore-settings is called (with appropriate arguments, see Repository Backup and Restore), existing users from an existing AllegroGraph (perhaps an earlier version) are added along with all their permissions and roles.

To add a new user or to remove a user, use AGWebView or agtool users as follows.

Adding a new user with AGWebView

Only a superuser can add a new user. When logged in as a superuser, display the Admin menu and choose Users to display the User page, which displays a list of current users, and a link after the list to add a new user:

User list and Add a User link

Clicking on that link displays a dialog asking for the new user name and password (we have filled in the name user3 and a value for the password):

New user dialog

clicking on Ok adds the new user. See below for information on specifying the permissions of the new user.

The User page displayed above already had three users (test, the initial superuser, and user1 and user2). Note that each has a [remove] link next to the username. Clicking on that will remove a user (after confirmation in a dialog box).

Adding a new user with agtool

The general form of the command for adding a user with agtool users is 

agtool users add [--server SERVER_SPEC] username [password]

A user with name username and password password is added. password is shown as optional but is required unless username is anonymous (the single username which can allow passwordless access).

The general for for removing a user with agtool users is 

agtool users remove [--server SERVER_SPEC] username

Anonymous access

A special user named anonymous can be created without a password. This can be done in AGWebView or with agtool users as described above, leaving out the password. anonymous (the case is significant, all lowercase) is the only user account that can be created without a password.

If such an account exists, anyone who can access the server machine over the Internet (such as machine:port) in a browser can log in as anonymous. They can then do whatever the permissions and access for anonymous allows (which is presumably not too much because otherwise this would be a security hole).

User Permissions and Access Controls

Permissions allow users to perform certain actions. Access controls control access to data in repositories (for reading, writing, or both). The general list of user permissions and access controls is displayed when the [Edit] button (which has been done for user1 in the illustration):

User permissions

There are seven general permissions. They are shown next to check boxes in the illustration above and are listed by 

agtool users permissions --help

Then there are access controls to individual catalogs and repositories and security filters, both described after the general permissions.

General permissions

The five general permissions are (each is listed with the name visible on the Users Page in AGWebView followed by, in parentheses, the name of the permission when using agtool users permissions):

In the illustration below, we have given user1 permission to Control replication and allowed user1 to specify user attributes via the HTTP header x-user-attributes and by the SPARQL PREFIX franzOption_userAttributes:

User1 permissions

Calling 

agtool users info --server SERVER_SPEC user1

(where SERVER_SPEC is either SCHEME://user1:user1-pw@HOST:PORT or SCHEME://user:user-pw@HOST:PORT where user has superuser privileges) prints 

Access:  
Roles:  
Permissions: 2pc replication user-attributes-prefix user-attributes-header

Only user1 and superusers can see user1's access, roles, and permissions.

Repository access controls

Users can be given permission to access data in repositories. The access can be read/write, or just read or just write.

Superusers typically have read/write access to all data unless the SuperUserCanAccessAllData configuration directive (described in the Top-level directives for account management section of the Server Configuration and Control document) has the value no (the default is yes). In that case, they must be given access to individual repositories just like all users, the only difference being they can give it to themselves (but that action appears in the audit log if auditing is enabled).

Here (from above) are the permissions for user1:

User1 permissions

No data access is allowed, as indicated by the statement No read/write access. Access can be granted to individual repositories or groups of repositories by using the 

Grant [read/write] on catalog [*   ] repository [*     ] [ok]

command.

The various choices are drop-down menus. The first shows the various types of access available:

User1 access

The choices are read/write, just read, just write, read-write with query results limit, and read with query results limit. See below for more information on query results limits.

Leaving the choice read/write and clicking [ok] with those specifications (read/write, * for catalog and repository) would grant read/write access on all repositories in all catalogs.

But as said above the catalog and repository boxes are also drop-down menus which can restrict the choice down to a specific repo. In the next illustration, the catalog is / (the root catalog) and the repository drop-down menu has choices * (all repos in the catalog), kennedy, and myrepo.

User1 access to repos

We allow read/write access for kennedy and read access for myrepo. Now the user1 profile looks like:

User1 access to repos granted

and agtool users info reports 

Access: root:kennedy:rw root:myrepo:r  
Roles:  
Permissions: 2pc replication user-attributes-prefix user-attributes-header

Access can be denied by clicking [remove] next the access permission in AGWebView.

Using agtool users, grant access with 

agtool users grant --server SERVER_SPEC USERNAME root:kennedy:rw root:myrepo:r

(repos and access are specified by catalog:repo:.) Access grants are additive so if the user has read (r) access to the root:myrepo repository, 

agtool users grant --server SERVER_SPEC USERNAME root:myrepo:w

adds write access to the existing read access. The catalog must be specified, the root catalog as root or / or the empty string (:myrepo:w).

Using agtool users, revoke access (read or r in this case) with 

agtool users revoke --server SERVER_SPEC USERNAME root:kennedy:rw root:myrepo:r

Security filters

The final user setting is specifying security filters. Note in release 7.3.0, security filters cannot be set or removed with agtool users.

Security filters are described in more detail in Security filtering in the Security Implementation document. In short, users can be prevented from seeing triples with certain specific content (such as any triple whose predicate is ) or allowed only to see triple with specific content (so user1 could be only allowed to see triples whose graph is ). See the discussion linked to above for further details.

Here (repeated from above) is the profile for user1 as shown in AGWebView. All the permissions and access granted above are shown.

User1 access to repos granted

To add security filters. click on [Add] next to Security Filters. The following dialog appears:

User1 add security filter

Select allow or disallow and specify the subject, predicate, object, and/or graph of interest - for example disallow triples with predicate as shown

Security filter choice

and click Add. Now the user1 profile in AGwebView is

User1 profile

Other operations on users

User suspension and disabling

User accounts can be suspended or disabled. These sound similar but are distinct. Both can be done by a superuser with agtool and AGWebView but both can occur automatically under certain circumstances. Suspensions might be removed automatically but a disabled account can only be re-enabled by a superuser.

User suspension: A suspended user cannot log in to their AllegroGraph account or issue any command via tools like agtool or the HTTP REST interface which requires a username and password. Superusers can unsuspend suspended users and in certain cases, suspensions are lifted automatically. See the Top-level directives for account management section of the Server Configuration and Control document. It describes the configuration directives MaxFailedLogins and AccountUnsuspendTimeout. An account is automatically suspended if there are MaxFailedLogins in a row. The account is unsuspended automatically after AccountUnsuspendTimeout seconds (regardless of whether suspension was caused by too many bad login attempts in a row or by superuser action). Only a superuser can unsuspend an account before AccountUnsuspendTimeout seconds have passed since suspension or if AccountUnsuspendTimeout is unset.

In AGWebView, users are suspended on the Users page (displayed by the Admin | Users menu item). A suspend button is available when the information on a user is displayed, as shown (for user1) in the illustration:

Buttons at the to of User information

Using agtool users, the following command suspends user1: 

agtool users suspend --server SERVER_SPEC user1

When a user is suspended, the button in AGWebView changes to unsuspend and the agtool users command to unsuspend is the same as that to suspend with suspend replaced by unsuspend.

Disabling a user: see the Top-level directives for account management section of the Server Configuration and Control document. It describes the configuration directives PasswordExpiry and PasswordExpiryGrace. An account is automatically disabled if a password expires and the grace period passes. Once an acount is disabled, it can only be re-enabled by an administrator (i.e. a supersuer). Disabled accounts are never automatically re-enabled (as suspended accounts might be).

In AGWebView, users are disabled on the Users page (displayed by the Admin | Users menu item). A disable button is available when the information on a user is displayed, as shown (for user1) in the illustration:

Buttons at the to of User information

Using agtool users, the following command disables user1: 

agtool users disable --server SERVER_SPEC user1

When a user is disabled, the button in AGWebView changes to enable and the agtool users command to enable is the same as that to disable with disable replaced by enable.

User password modification

See the section Usernames and passwords in the Security Implementation for more information on the security issues associated with passwords.

In AGWebView, here is the profile of user1 on the Users page displayed (for superusers) by the Admin | Users menu item:

User1 profile

Note [change password] next to the username and [expire password] in the list of actions just below the Roles line.

Clicking on [change password] displays a dialog allowing a new passord to be specified.

Clicking on [expire password] expires the password. The next time user1 tries to log in, this warning and dialog will appear:

Password expired dialog

There are a number of configuration directives that control passwords. They can, if set, specify password minimum length, that passwords must contain numbers or non-alphanumeric characters, how often a password must be changed, and so on. Users may also be prevented from changing their own passwords and have to contact a superuser for assistance when a password must be set.

See the Top-level directives for account management section of the Server Configuration and Control document. It lists the directives relating to passwords.

Limiting the results a user can see

Users can be restricted to a maximum number of results that will be produced by a query (separate from the LIMIT specified by the query or in AGWebView). The restriction also applies to exporting triples and exporting duplicate triples. Indeed, the limitation on export is the primary reason for the option.

The configuration directive QueryResultsLimit, default 1000, specifies the limit, which is the same for all users and repositories for which the query results limit is enabled via user access options.

Limiting results is just another access control option, as described above. We break it out just because it is somewhat different in kind from read and write access.

It can be set and unset with these agtool command: 

agtool users grant  --server SERVER-SPEC <username> <catalog>:<repo>:l  
agtool users revoke --server SERVER-SPEC <username> <catalog>:<repo>:l

The last letter is a lowercase L (not the number one). The catalog must be specified. The root catalog is specified root or / or with the empty string (so :repo-name:l). The user specified in the SERVER-SPEC must be a superuser. SERVER-SPECS are discussed in the Repository Specification document.

The following REST commands can also be used: 

PUT /user/<username>/access?query-results-limit=true&catalog=<catalog>&repository=<repository>  
DELETE /user/<username>/access?query-results-limit=true&catalog=<catalog>&repository=<repository>

The catalog specification can be omitted if it is the root catalog.

For SPARQL/Prolog queries the limit is enforced by applying the rule 

<query-limit> + <query-offset> <= <query-results-limit>

that is, if query asks for results beyond the results limit with its limit and offset modifiers, the new modifier values will be chosen to fit the above condition.

The limits apply to exporting triples and to exporting duplicate triples as well.

Roles

A role is a collection of permissions and access rights. When a user is assigned a role, all the role's permissions and access rights are given to the user. Roles have names. See Allowable user and role names above for allowable names.

Roles are simply a convenient shorthand for use when multiple users will be given the same set of permissions and access rights. Instead of editing the profile for each user in the set, you define a role with the desired permissions and access rights and assign the role to each user in the set.

In AGWebView, roles are defined and listed on the Users page displayed by the Admin|Users menu item, just like users. To add a role, click [add a role] at the bottom of the Roles section of the Users page.

Adding a role

That displays a dialog asking for a name for the new role:

Naming a role

Once the role is created, it is listed under Roles. Next to its name are boxes [remove] and [edit]. Clicking [remove] removes the role (after confirmation). Clicking [edit] displays the same collection of permissions and access rights as for a user.

Role profile

As we said, role permissions are identical to user permissions. See the sections starting with User permissions above for more information.

In the next picture, we have added some permissions and a security filter:

role with permissions

Then in the Users section, we add the tech1 role to user2:

user2 with tech1 role

Managing roles with agtool roles and agtool users

Roles are defined and managed with the agtool roles command: 

> agtool roles help  
Usage: agtool roles COMMAND [ OPTIONS ] ...  
 
where COMMAND is one of:  
* help - Display role usage.  
* info - Prints information about the role.  
* list - Prints a list of all roles.  
* remove - Deletes a role.  
* add - Creates a role.  
* permissions - Modifies a role by adding or removing permissions.  
* revoke - Revokes specified access rights for specified repos to a role.  
* grant - Grants specified access rights for specified repos to a role.

The OPTIONS include --server SERVER_SPEC which must specify a superuser. The list is similar to those agtool user commands dealing with permissions and access (and again, in this release, security filters cannot be managed with agtool role).

A role is added to a user with 

agtool users add-roles --server SERVER_SPEC user role-name

and removed with 

agtool users remove-roles --server SERVER_SPEC user role-name

In both cases, SERVER_SPEC must specify a superuser.

HTTP interface

See HTTP Protocol - SPARQL Endpoint for information on AllegroGraph's HTTP interface. The interface for managing users is here in that document.