Fine-grained Access Control

Note

This feature requires a GraphDB Enterprise license.

By default, permissions in GraphDB are set at the repository level — access to a repository grants access to all its statements indiscriminately. However, a more robust access control system may be necessary in some cases, such as restricting access to a specific named graph (a collection of statements with sensitive data), to a specific predicate (a single statement with sensitive information, such as salary), or restricting users from being able to clear an entire named graph.

Fine-grained access control (FGAC) allows you to manage access to specific resources at a more granular level, so that only authorized users can read or modify certain data, or execute certain operations. The FGAC mechanism provides a means to allow or deny access based on elements such as parts of the RDF statement or specific plugins, as well as to control access to system operations that change the repository in a fundamental way.

Note

To learn how to manage FGAC rules, check the Managing FGAC rules through Workbench and Managing FGAC rules through the REST API documentation pages.

How FGAC works

Fine-grained access control is managed through individual access control rule definitions, with each definition setting the rules for access to a specific resource or operation for a specific group of people. There are four types of rule definitions, based on the scope of the the access control check the rule performs — statement, clear graph, plugin, system. Check Rule scopes for Fine-grained access control below for more information on the scopes.

A rule definition consists of four elements:

Policy

There are two permission policies:

  • Allow: the rule will allow access to the resource

  • Deny: the rule will deny access to the resource

Note

In real-world applications, it doesn’t make sense for a user to be allowed to modify a resource that they cannot read. Thus, some rules are automatically inferred:

  • A rule that allows write operations also allows read operations concerning the same resource.

  • A rule that denies read operations also forbids write operations concerning the same resource.

This approach is based on common sense and practicality.

Custom user roles

The role attribute specifies role membership. It can be one of the following:

  • A role name: the user must have that role

  • ! followed by a role name: the user must not have that role, or in other words, ! negates the role membership

To learn more about user roles, check our documentation on Custom user roles.

Operation types

There are two operation types: read and write. They are defined only for the statement, plugin and system scope.

  • Read: any operation that reads something without changing its state, such as read operations of repository statements, queries to plugins, reading the SHACL shapes, or reading the fingerprint.

  • Write: any operation that writes something and potentially changes its state, such as regular data inserts or deletes, updates handled by plugins, changing the SHACL shapes, or changing of the repository via a system statement.

Tip

The operation type can also be set to "*" to explicitly use the rule for both Read and Write access control checks.

Access control list

All rule definitions are stored in an access control list (ACL).

When GraphDB needs to determine whether to grant access to a resource, the rules in the ACL are processed sequentially until either of the following occurs:

  • A rule matches the operation type, the role attribute and the scope specific attributes — in that case, GraphDB will follow the rule’s policy (either allow or deny access to the resource).

  • The end of the ACL is reached — in this case, the default policy is to allow access to the resource.

Thus, the order of your ACL rules is of crucial importance.

All rules share the same management API, regardless of their scope.

Tip

Rules are only processed within the scope of the operations they cover. In other words, if a user is initiating an operation handled through a plugin, only the rules within the Plugin scope will be processed.

Note

Duplicate rules (where all elements of the rule definition are identical) are not permitted.

Repository managers and administrators

Any user who has the repository manager or administrator role will bypass all FGAC checks and thus be allowed to perform any operation on the repository.

Rule scopes for Fine-grained access control

The scope of a FGAC rule definition determines the type of resource the rule applies to (as opposed to the specific resource). A given rule will be used only if its scope matches the access control check that needs to be performed. Scopes may have scope-specific attributes and can be one of the following four types:

  • statement scope

  • clear graph scope

  • plugin scope

  • system scope

Each of these is covered in more detail below.

Statement scope

Statement scope FGAC allows you to manage access to specific RDF statements, so that only authorized users can read certain data. This way you can allow or deny access based on any part of an RDF statement, where the full representation of a statement consists of a quad — the subject, the predicate, the object, and the named graph, also known as context. Thus, statement scope access control is also known as quad-based access control.

Common use cases for statement scope fine-grained access control are restricting access to a specific named graph (a collection of statements with sensitive data) or a specific predicate (a single statement with sensitive information, such as a salary).

Note

Access control list support for statement scope was first introduced only for read operations in GraphDB 10.4 under the name “Quad-based access control”. Repository statement scope ACL rules are backwards-compatible with GraphDB 10.4 quad-based access control rules. Since quad-based access control rules lacked the scope and operation properties, rules created in GraphDB 10.4 will receive Statement scope and * operation type upon migrating to GraphDB 10.5 or newer.

In addition, all regular users (i.e., not repository managers or administrators) will be subject to FGAC checks, while in GraphDB 10.4 only users with read access (and not read/write access) to a repository were checked.

Statement scope attributes and special values

The statement scope takes the elements of a quad as additional attributes:

  • subject — the subject of the RDF statement: an IRI or on RDF-star embedded triple

  • predicate — the predicate of the RDF statement: an IRI

  • object — the object of the RDF statement: an IRI, an RDF-star embedded triple or a literal

  • context — the context of the RDF statement: an IRI

Each of those four elements can take a wildcard value of * to match any RDF value when the rule is checked. In addition to that, context can also take the special values of default for the default graph and named for any named graph.

RDF values

All RDF values are specified in N-Triples/Turtle-star format using the full notation, where shortened IRIs and bare numeric or boolean literals are not permitted:

  • Valid IRIs — <http://example.com/data/Person1>, <http://www.w3.org/2000/01/rdf-schema#label>

  • Invalid IRIs — rdf:type (shortened IRIs not allowed)

  • Valid literals — "My data", "Meine Daten"@de, "15"^^<http://www.w3.org/2001/XMLSchema#int>, "true"^^<http://www.w3.org/2001/XMLSchema#boolean>

  • Invalid literals — 125, 78.05, true, false (bare literals not allowed)

  • Valid RDF-star triples — <<<http://example.com/data/Person1> <http://www.w3.org/2000/01/rdf-schema#label> "Person 1">>

Note that it is not possible to specify and match against blank nodes.

Clear graph scope

Clear graph scope FGAC control is used to manage who can process operations that delete a set of statements identified only by the named graph or the special case of clearing all graphs.

The clear graph scope FGAC is especially useful for restricting access to the CLEAR ALL operation by denying access to it.

Clear graph scope attributes and special values

The clear graph scope takes only context as an additional attribute, either as an IRI, a wildcard value of * to match any value when the rule is checked, or one of the following special values:

  • default for the default graph.

  • named for any named graph.

  • all for the CLEAR ALL operation.

The IRIs are specified in N-Triples/Turtle-star format using the full notation, just like for statement scope.

Note

Unlike the other scopes, clear graph does not have operation type.

Implicit CLEAR ALL protection

GraphDB processes CLEAR ALL as a bulk operation in GraphDB that is executed without iterating over individual statements. As such, it is not possible to check if the user executing the operation has write access to each statement that would be deleted. In order to prevent inadvertent removal of otherwise protected statements, GraphDB will append a clear graph scope rule denying CLEAR ALL if there is at least one rule denying writes to statements or clear graph to any named graph.

Plugin scope

Plugin scope FGAC is used to manage operations handled through plugins. These operations typically look like regular queries or updates but are answered or executed by a plugin instead of being handled as proper RDF data. You can use plugin scope access control to manage who has access to any specific plugin.

A common use case for the plugin scope FGAC is restricting write operations on GraphDB Connectors to prevent accidental removal of a connector instance.

Plugin scope attributes and special values

The plugin scope takes only plugin as an additional attribute, either as a plugin name or a wildcard value of * to match any plugin when the rule is checked.

System scope

System scope FGAC is used to manage the rights to perform any operation involving a system statement. This includes operations such as querying the fingerprint, changing the ruleset, or triggering reinferencing.

A common use case for the system scope FGAC is restricting write operations that change the ruleset of the repository.

Note

It is not possible to specify only a single category of operations (for example, only changing the ruleset).

Note

The system scope plugin does not take any additional attributes and does not have special values.