feature: support ODRL to configure authorisation policies

[mirdono]

Note

This functionality is being tested in the DECIDe project. I marked the PR as
draft until it has seem more mileage.

Add initial functionality to support specifying authorisation policies using
ODRL (with some SHACL), as an option next to the existing lisp ACL.

Approach

Specifying authorisation policies using ODRL and SHACL

The following table contains an overview of how the different elements in
sparql-parser's ACL are expressed using ODRL and SHACL. A more detailed
description can be found in the README's how-guide on ODRL and on the
gitbook of the DECIDe project.

ACL	ODRL/SHACL
access	ODRL Party collection
graph	ODRL Asset collection
type-specification	ODRL Asset and SHACL node shape with property shapes
grant	ODRL Permission

An ODRL Party collection can be linked to a query (and parameters) in which
case it would correspond to an access-by-query, otherwise it corresponds to
always-accessible. It is currently not supported to influence this mapping
using constraints.

For example, take the following access-by-group for authenticated users:

(supply-allowed-group "authenticated"
  :parameters ("account")
  :query "PREFIX session: <http://mu.semte.ch/vocabularies/session/>
      SELECT DISTINCT ?account WHERE {
      <SESSION_ID> session:account ?account.
      }")

would correspond to the following ODRL Party collection:

@prefix dct: <http://purl.org/dc/terms/> .
@prefix ext: <http://mu.semte.ch/vocabularies/ext/> .
@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .

ext:authenticatedParty a odrl:PartyCollection ;
  vcard:fn "autenticated" ;
  ext:queryParameters "account" ;
  ext:definedBy """PREFIX session: <http://mu.semte.ch/vocabularies/session/>
  SELECT DISTINCT ?account
  WHERE {
    <SESSION_ID> session:account ?account .
  }""" ;
  dct:description "This represents all logged in users of the system." .

An ODRL Asset collection describes a set of triples in a graph. Therefore,
we opted to use SHACL shapes instead of ODRL constraints to capture
type-specifications, as the former is specifically intended to express that
kind of information. ODRL constraints on the other hand are not suitable here.
A SHACL node shape (ODRL Asset) specifies a resource type as sh:targetClass
and can contain property shapes to further refine for specific predicates. For
example, a graph-specification such as

(define-graph some-graph ("http://mu.semte.ch/graphs/someGraph")
    (typeOne -> predOne
             <- predTwo))

would correspond to the following ODRL Asset collection and SHACL node shape:

@prefix ext: <http://mu.semte.ch/vocabularies/ext/> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix odrl: <http://www.w3.org/ns/odrl/2/> .
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .

ext:someCollection a odrl:AssetCollection ;
    vcard:fn "some-graph" ;
    ext:graphPrefix <http://mu.semte.ch/graphs/someGraph> .

ext:someShape a odrl:Asset , sh:NodeShape ;
  odrl:partOf ext:someCollection ;
  sh:targetClass typeOne ;
  sh:property [
    sh:path predOne
  ] , [
    sh:path [ sh:inversePath predTwo ]
  ] .

An ODRL Permission grants members of party collection a given action on an asset collection. Similar to what a grant does.

For example, the following grant:

(grant (read)
       :to-graph some-graph
       :for-allowed-group "authenticated")

corresponds to the following ODRL Permission

@prefix ext: <http://mu.semte.ch/vocabularies/ext/> .
@prefix odrl: <http://www.w3.org/ns/odrl/2/> .

ext:someGraphReadPermission a odrl:Permission ;
  odrl:action odrl:read ;
  odrl:target ext:someGraph ;
  odrl:assignee ext:authenticatedParty .

Note, scopes can be defined using the ext:scope property for Permissions. This will essentially act the same as the :scopes keyword argument for grants.

ODRL model implementation

The ODRL/SHACL model explained above is implemented as a set of classes in
odrl.lisp and shacl.lisp. This allows
to internally instantiate ODRL policies read from a configuration file as well
as convert ODRL model instances to the ACL sparql-parser uses. Having this
intermediate representation should allow that the functionality to convert it to
the internal ACL can evolve independently from the functionality parsing the
input configuration file. For example, supporting another file format only
requires to implement functionality to instantiate an ODRL model from that format.

The model implementations only cover the parts of the ODRL and SHACL
specifications that are necessary to express authorisation policies. For
example, no support for ODRL offers or constraints is implemented. Furthermore,
the implemented ODRL model deviates from the specification in two ways. First,
in our implementation rules can specify multiple actions, whereas ODRL only
allows a single action¹. This allows to "merge" rules that map to a single
grant thereby simplifying the actual conversion. Second, asset collections
reference their contained assets, whereas in the ODRL specification it is assets
that link to the collections they are part of via the odrl:partOf
predicate. This inversion allows to pass over all elements in a policy in a
top-down fashion, instead of having to keep track of all available assets
separately.

Conversion to ACL

Converting an ODRL model instance to the internal ACL is implemented using
generic functions, odrl-to-acl and shacl-to-acl, and their method
implementations. In summary this conversion starts from an ODRL rule-set and
passes over each contained element to convert them to their corresponding ACL
element.

Note, as the conversion starts from the rules in a policy, only party (asset)
collections that are used in at least 1 rule are converted. This is different
from configurations in lisp, where each specified access and graph is
evaluated irrelevant of whether there is a grant using it.

Input file parsing

As input a ttl file is expected, this file is read and parsed by the
functionality in parse-ttl. The load-policy-file
function reads input file and parses the content using
cl-ttl-parser. The result is a list of
lists, with each inner list representing a triple. The make-rule-set function
converts these triples to their corresponding ODRL or SHACL objects.

Open issues

ODRL policies do not yet support all features available through the lisp ACL:

• It is not possible to explicitly specify a constraint for a party collection,
  as can be done for allowed-groups in the acl:supply-allowed-group
  macro. Consequently, the type of acl:access that will be created for each
  party collection is determined by the presence or absence of a query. It is
  thus not possible to specify a NEVER constraint, or force the creation of an
  acl:always-accessible instance despite the presence of a query.

• Asset Collections do not support setting options on a per instance basis. Each
  Asset Collection will be translated to an acl::graph-specification with
  generate-delta-p and generate-sparql-p set to t.

• ODRL's policy rule composition is not supported at the ttl configuration level. Adding support for this would allow to specify configurations in a slightly more condensed manner. For example, one would not have to define 2 separate rules to grant read and write rights.

Notes

• The implementation is adapted from the
  odrl-parser-service which
  served as PoC to show the feasibility of expressing semantic.works
  authorisation in ODRL.

Related tickets

• LBRON-719
• LBRON-1060

Footnotes

1. Policy rule composition is currently not supported for specifying ODRL authorisation policies. ↩