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