Introduction

A file can describe a set of users and roles and the capabilities for each. The file is in lineparse format.

There are two section directives: user and role. A file begins with a user or role directive followed by items for that type of section. The section ends at the end of file or when another user or role directive is seen.

The allowed items in each section are given in the following tables.

All items except name can be repeated.

Min and Max refer to the number of arguments to the named item.

Role

item min max required
name 1 1 yes
permissions 1 no-max no
grant 2 4 no
security 2 5 no
attributes 2 2 no

The form of a grant item is 

grant kind catalog [ repo [ limit ]]

where kind is read, write or read/write.

limit, if given, is the word limit and means that while those users with this role can do queries there is a limit on how many results can be returned in order to prevent someone from getting a copy of the whole repository. The QueryResultsLimit configuration directive in agraph.cfg sets the limit and the default is 1000 results. (see the Server Configuration and Control document)

Examples: 

grant read /        # read anything in the root catalog  
grant read / "" limit # read anything in the root catalog with results limited  
grant read/write project myrepo # read/write myrepo in the project catalog  
grant read/write ""      # read/write any catalog, any repo  
grant read/write "" ""   # also read/write any catalog, any repo  
grant read/write "*"     # also read/write any catalog, any repo  
grant read/write "*" "*" # also read/write any catalog, any repo

The form of a security item is 

security kind s p o g

where kind is allow or disallow and, if given, then s,p,o and g are parts in ntriple syntax. You must specify kind and s but anything after that is optional.

The security item defines a pattern to match against quads (subject predicate object graph) in the repository. If there are any rules where the kind is allow then only quads matching one of the allow rules is visible to users with this role, however you then consider the disallow rules. If there are no allow rules then all quads are visible except those disallowed with a disallow rule.

If a quad is visible by virtue of the allow rules (if any) it is then matched against the disallow rules and a match means the quad is not visible to users of this role. See Security Implementation.

Examples: 

# ignore all quads with the predicate <http://secret.com>  
security disallow ""  <http://secret.com>  
 
# ignore this precise quad  
security disallow <http://sss.com> <http://ppp.com> "secret word" <http://ggg.com>

For the permissions item the possible arguments are: 

super eval session replication 2pc user-attributes-header  
user-attributes-prefix define-fedshard use-fedshard

For example 

permission super

This gives the user with this role the power to do anything. The other permissions need not be explicitly given, they are all granted by the super permission. In fact there are even more capabilities granted by super such as the ability to add and delete users and to read and write any repository in any catalog. Of course the super permission should only be granted the administrator of the server.

Another example 

permission session use-fedshard

This allows the users with this role to create sessions which are used to do modifications of the repo within a transaction. Using gruff to view a repository requires that the user have session permission. The users with this role can also open a fedshard repostory but cannot define a new fedshard repository (since the permission define-fedshard is missing).

The form of an attributes item is 

attributes cat:repo attributes-json

Where cat:repo is a specification of the catalog and repo to which the attributes apply. Catalog and/or repo can be * meaning all. A missing catalog specification (i.e. just repo) implies the root catalog.

Examples of cat:repo: 

myrootrepo  
hr:personnel  
secret:*  
*:*

The attributes-json is a json expression specifying the attributes to be given for anyone with this role (as long as no other attribute specification has more precedence)

An example is: 

"{\"security\": "\low\", \"department\": \"hr\"}"

User

A user can have specific permission, grant and security capabilities and the syntax is just like shown in the role definition above.

All items except name and password can be repeated.

Min and Max refer to the number of arguments to the named item.

item min max required
name 1 1 yes
password 1 1 no
roles 1 no-max no
permissions 1 no-max no
grant 2 4 no
security 2 5 no
attributes 2 2 no

If the password is not given then the user will not have a password in the internal AllegroGraph database (and thus can't log in using the internal database) however the user might still authenticate using external authentication (see Top-level directives for external authentication).

The user with name "anonymous" is a special case. anonymous does not have a password yet it can log in with no password and with only the capabilities specified for it. The administrator can choose to make an account with the name "anonymous". Initially the server does not have an anonymous account.

If a password is given then it can be in plain text or it can be the hashed value of the password. Typically a password specified as a hashed value will only be seen in the output of the agtool users export command.

Example

 user  
   name smith  
   password mitms  
   roles arole brole  
   roles crole  
   permissions 2pc super  
   permissions  define-fedshard  
   security  allow   <http://subj.com>  
   security  disallow "" <http://pred.com> "secret object"  
   security  disallow <http://sss.com> <http://ppp.com> <http://ooo.com> <http://ggg.com>  
   grant     read bigcat  
   grant     read/write bigcat okrepo  
   grant     read mysys bigdata limit  
   grant     read/write small smaller  
   grant     read/write small medium limit  
   attributes bigcat:secret "{\"Security\": \"high\"}"  
 
 user  
   name jones  
   password soenj  
   roles crole  
   grant read/write ""  
 
 role  
   name arole  
   grant read acat  
 
 role  
   name brole  
   security disallow "" <http://secretpred.com/>  
   attributes *:* "{\"Security\": \"low\"}"  
 
 role  
   name crole  
   permissions super