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.
In version 8.0.0 of AllegroGraph a capability was added to allow one to define a set of users and roles with one command. Also you can export all the current user and roles definitions in one command. See Bulk Loading of users and roles below.
Managing users
Users have names and may have passwords (the anonymous user never has a password). If a non-anonymous user doesn't have a password one cannot log in as that user unless the database administrator has specified external authentication and the LDAP server referenced has a password for the user.
Users 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 traditional AGWebView and new WebView, 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:
- help - Display user usage.
- info - Prints information about the user.
- list - Prints a list of all users.
- expire - Expires password for a user.
- remove - Removes a user.
- add - Adds a user.
- unsuspend - Unsuspends a user account.
- suspend - Suspends a user account.
- disable - Disables a user account.
- enable - Enables a user account.
- set-password - Sets password for a user
- remove-roles - Removes role(s) from a user
- add-roles - Adds role(s) to a user
- permissions - Modifies a user by adding or removing permissions.
- revoke - Revokes specified access rights for specified repos from a user.
- grant - Grants specified access rights for specified repos to a user.
- import - Read a file defining users and roles
- export - Output a description of the users and roles known to the server
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
WebView can create users without a password. (Aside from the intentional provision of a user named anonymous, creating a user without a password should only be done if access is controlled by some external system like LDAP.)
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 picture is from traditional AGWebView, in New WebView the menus are on the left and the Users page is very similar).
The User page displays a list of current users:
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:
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):
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):
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):
Superuser (super) - a superuser can perform most any action, except perhaps viewing all data by default. See the
SuperUserCanAccessAllDataconfiguration directive in the Top-level directives for account management section of the Server Configuration and Control document. If a superuser does not have permission to view a repository, he/she can add it but that action will be logged by the audit process if auditing is enabled (see Auditing).Start sessions (session) - A user with the Start Sessions permission can use the AllegroGraph features that require spawning a dedicated session, such as Transactions and Social Network Analysis (SNA). If you try to use these features without the appropriate permission, you'll encounter authorization 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.
Evaluate arbitrary code (eval) - 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 withheld from users who are not fully trusted and even among trusted users, it should be granted only to those who need it. The ability to evaluate code in the hands of a knowledgeable user is equivalent to superuser privileges.
Control Replication (replication) - The Control Replication permission allows a user to set up automatic replication of a repository across multiple servers. See Multi-master Replication and also Replication.
Two-phase commit (2pc) - The Two-phase commit permission allows a user to initiate a two-phase commit procedure, where a group of repositories (both in AllegroGraph and in non-AllegroGraph database servers) will all either simultaneously commit or simultaneously roll back. See the Two-phase Commit document for more infomation.
Allow user attributes via HTTP header x-user-attributes (user-attributes-header) - The Allow user attributes via HTTP header x-user-attributes permission allows the user to supply user attributes using the
x-user-attributesheader. See the Static filters section of the Triple Attributes document for more information.Allow user attributes via SPARQL PREFIX franzOption_userAttributes (user-attributes-prefix) - The Allow user attributes via SPARQL PREFIX franzOption_userAttributes permission allows the user to specify user attributes in a SPARQL query using the PREFIX
franzOption_userAttributes. See here in the SPARQL Reference document for more information on that prefix.
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:
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:
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:
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.
We allow read/write access for kennedy and read access for myrepo. Now the user1 profile looks like:
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: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 8.0.1, 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
Here (repeated from above) is the profile for user1 as shown in AGWebView. All the permissions and access granted above are shown.
To add security filters. click on [Add] next to Security Filters. The following dialog appears:
Select allow or disallow and specify the subject, predicate, object, and/or graph of interest - for example disallow triples with predicate
and click Add. Now the user1 profile in AGwebView is
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:
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:
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:
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 password to be specified.
Clicking on [expire password] expires the password. The next time user1 tries to log in, this warning and dialog will appear:
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.
That displays a dialog asking for a name for the new 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.
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:
Then in the Users section, we add the tech1 role to user2:
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.
* import - Read a file defining users and roles
* export - Output a description of the users and roles known to the server
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.
Bulk loading users and roles
There is a format documented here for providing information about the users and roles to be known to the AllegroGraph server.
The command
agtool users import --server SERVER_SPEC filename will add those given users and roles to the authorization database inside the AllegroGraph server. If those users and roles already exist the import command will add the given capabilities to the users and roles and never remove any existing capabilities. In other words the import command does not synchronize the state of the users and roles to what is in the file being imported.
The export command prints all information about the users and roles known the the AllegroGraph server.
agtool users export --server SERVER_SPEC The passwords, if any, are printed in their hashed form. It is very difficult to determine the actual password from the hashed version of the password but one should still take care to protect the information printed by this command if it includes a hashed password. The format of the output is given here. The exported information can be stored in a file and directly imported into another fresh server to effectively copy the user/role authorization from one server to another.
For convenience you can also use the commands
agtool roles import --server SERVER_SPEC filename
agtool roles export --server SERVER_SPEC and they work identically to the agtool users commands. All commands work with both user and role definitions.
HTTP interface
See HTTP Protocol - SPARQL Endpoint for information on AllegroGraph's HTTP interface. The interface for managing users is here in that document.