Managing Users in AllegroGraph 9.0.1
Author: Franz Incorporated

Copyright (c) 2005 - 2026 Franz, Incorporated
Last updated 27 May 2026 at 10:34

# AllegroGraph 9.0.1 Managing Users and Roles

- Documentation Index
  - Release Notes
  - Quick Start
  - SSL/TLS Quick Start
  - Introduction
  - Setup and Configuration
    - Download
    - Server Installation
    - Server Configuration and Control
    - WebView
    - Database Upgrading
    - Managing Users
  - Server Management
    - Performance Tuning
    - Deleting Duplicate Triples
    - Purging Deleted Triples
    - Auditing
    - Managing Users
    - Replication
    - Point-in-Time Recovery
    - Transaction Log Archiving
    - Security Overview
    - Security Implementation
  - Tools
    - agtool
    - Data Loading
    - Data Export
    - Backup and Restore
    - Querying
    - RDFS++
    - Materializer
    - Event Scheduler
    - SHACL
  - Details
    - Triple Indices
    - Freetext Indices
    - Encoded IDs
    - Connection Pooling
    - N-dimensional Geospatial Overview
    - 2-D Geospatial
    - Temporal
    - Social Network
    - JavaScript
    - Datatypes
    - Data Conversion (Rapper)
    - Stored Procedures
    - Triple Attributes
    - Lineparse Format
  - Querying
    - SPARQL documentation summary
    - SPARQL Reference
    - SPIN
    - SPARQL Magic Properties
    - Prolog
  - 3rd-party tools
    - Solr text Indices
    - MongoDB integration
    - TopBraid Composer Plugin
    - Cloudera
  - Client APIs
    - Gruff
    - GraphTalker
    - REST/HTTP interface
    - HTTP reference
    - Javadocs (Sesame and Jena)
    - Python API
    - Lisp Reference
    - JavaScript
  - Tutorials
    - N-dimensional Geospatial
    - SPARQL Tutorial
    - Java Sesame
    - Java Jena
    - Python Sesame
    - Lisp
    - Prolog
    - More...
  - Other
    - Conferences and Seminars
    - Source Code on Github
    - Amazon EC2
    - Copyrights
  - Franz, Inc.

- Introduction
- Managing users
  - Allowable user and role names
  - Managing users with agtool: general comments
  - Managing users with WebView: general comments
  - Adding and removing a user
    - Adding a new user with AGWebView
    - Adding a new user with agtool
  - Anonymous access
  - User Permissions and Access Controls
    - General permissions
    - Repository access controls
    - Security filters
    - User attributes
    - Avatar color
  - Other operations on users
    - User suspension and disabling
    - User password modification
  - Limiting the results a user can see
- Roles
  - Role avatar color
  - Managing roles with agtool roles and agtool users
- Bulk loading users and roles
- HTTP interface

Documentation Index

## 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. agtool also has a `users` set of commands which can be used 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.

    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 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 `SuperUserCanAccessAllData` configuration 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).

  A confirmation dialog is displayed when the Superuser check box is checked. This prevents casually giving inappropriate permissions.

- 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-attributes` header. 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:.) Access grants are additive so if the user has read (r) access to the `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 9.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 `<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 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 is 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 account 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 widget 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 to 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.