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.
You can define a set of users and roles with one command. Also you can export all the current user and role 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 configured LDAP or OAuth and the referenced server has a record for the user. Tokens (essentially alternate passwords) can also be defined. See agtool tokens for more information.
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 WebView (traditional AGWebView also can be used for managing users). agtool also has a users command which can be user for user management. The REST/HTTP interface can also be used for that purpose. 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, stop the server, edit the configuration file and then restart the server.
Allowable user and role names
User and role names may consist of any characters 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 a powerful and flexible way to manage users. The REST/HTTP interface is as powerful but not as convenient. WebView provides the graphical interface as does traditional WebView.
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 as part of the SERVER_SPEC (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 WebView: 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 or OAuth/OIDC).
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 WebView, in Traditional WebView the menus are along the top).
The User page displays a list of current users:
WebView 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, along with other settings, is displayed when the username is clicked on the Users page (which has been done for user3 in the illustration):
There are nine 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 nine 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.
Use fedshard repo and Define fedshard repo**: these allow the user to define a fedshard repo and/or to use such repos. See the FedShard documentation for more information.
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 user3 permission to Control replication and 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 user3 (where SERVER_SPEC is either SCHEME://user3:user3-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 user3 and superusers can see user3'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. A limit to the number of responses to a query can also be specified.
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 user3 (this image taken before we modified user3's permissions just above):
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 clicking on New Access and specifying the catalog(s)/repository(ies) of interest and choosing the type of access.
The various catalog/repository fields can be filled in with drop-down menus. We show the menu for the Catalog field. It lists existing catalogs and also *, meaning all catalogs. The Repository field can also be * (meaning all repos in the catalog) or a choice of available repos.
The permissions are:
- Read: data in the repo can be seen.
- Write: new data can be written or existing data can be deleted.
- Query limit: Only up to 1000 query results can be displayed regardless of how many triples satisfy a query. See below for more information on query results limits.
Using agtool users, grant access with
agtool users grant --server SERVER_SPEC USERNAME root:kennedy:rw (repos and access are specified by catalog:repo:root:kennedy repository,
agtool users grant --server SERVER_SPEC USERNAME root:kennedy: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 Thus, if r access is present and you want just w access, you must first revoke r and then add w.
Security filters
The next user setting is specifying security filters. Note in release 8.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 <http://www.franz.com/info#salary>) or allowed only to see triples with specific content. See the discussion linked to above for further details.
Here is the current profile for user3 as shown in AGWebView. All the permissions and access granted above are shown.
To add security filters. click New Security Filter. We have already done that, though we have not specified any values yet.
Select allow or disallow (the menu on the right) and specify the subject, predicate, object, and/or graph of interest (unspecified means any value) - for example disallow triples with predicate <http://www.franz.com/info#salary> as shown (we have specified that the the predicate, left the subject, object, and graph blank, and chosen Disallow):
User attributes
See the Triple security document for information on user attributes. These can be used along with triple attributes (see Triple Attributes) to control user access to triples. Unlike the coarse restrictions provided by security filters described just above, using attributes provides fine control down to the level of individual triples. This section allows specifying attributes associated with a user. The format is similar to that for associating attributes with triples. See the Triple security document for more information.
Avatar color
The avatar is a circle with the initial character of the username and with a specified background color. You see this in the upper right of the screen when a user is logged in. The initial color is gray but the last choice when setting up the characteristics of a user has a color widget which can change the avatar background color.
If a color is chosen, it will be used. Users without a chosen color who have a role will use the role's chosen color if there is one. If a user without a chosen color has multiple roles with chosen colors, the one that is used in undetermined.
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 user3) 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. 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, just above (in the suspend/disable discussion) you see the profile of user3 on the Users page displayed (for superusers) by the Admin | Users menu item. The Password is just below the page title (Edit user3 user) and has links for changing and expiring.
Clicking on [change password] displays a dialog allowing a new password to be specified.
Clicking on [expire password] expires the password. The next time user3 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 WebView). 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 WebView, roles are defined and listed on the Users page displayed by the Admin|Users menu item, just like users. To add a role, click [New role] to the right of the Roles section of the Users page. We have done that already in the illustration and have named the role manager:
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.
Role avatar color
The avatar is a circle with the initial character of the username and with a specified background color. Users can choose their avatar color. If they do not and they have a role, the role's chosen avatar color, if there is one, is used for the user. (If the user has multiple roles but no individual chosen color, and more than one of the roles has a chosen color, the one that is used for the user is undetermined.)
Use this widegt at the bottom of the role specification to choose a color for a 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.
* 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.