From 82b99599a9e2fe2a9cecc6c3ddae6a9fc1580339 Mon Sep 17 00:00:00 2001 From: Kobe Mertens <37635647+kobemertens@users.noreply.github.com> Date: Mon, 25 Aug 2025 16:13:36 +0200 Subject: [PATCH 1/3] Update README.md --- README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/README.md b/README.md index 7ad355b..33d7247 100644 --- a/README.md +++ b/README.md @@ -63,6 +63,38 @@ Next, add the following contents to the config file mounted in `./config/authori It basically configures read/write access for everyone for all data on the `http://mu.semte.ch/graphs/public` graph. +## Tutorials +### Defining prefixes +In order to use the CURIE (Compact URI) form (e.g. `foaf:name`) we need to define the prefixes first. This is done as follows: +```lisp +(define-prefixes + :adms "http://www.w3.org/ns/adms#" + :cal "http://www.w3.org/2002/12/cal/ical#" + :cogs "http://vocab.deri.ie/cogs#" + :dcat "http://www.w3.org/ns/dcat#" + :ext "http://mu.semte.ch/vocabularies/ext/" + :eli "http://data.europa.eu/eli/ontology#") +``` +### Specifying which triples are accessible from which graphs +For this we need a `define-graph` block. This looks as follows: +```lisp +(define-graph organization ("http://mu.semte.ch/graphs/organizations/") + ("foaf:Person" -> _) + ("foaf:OnlineAccount" x> "ext:password") +``` +The `define-graph` macro takes a unique identifier, the URI of the graph where the triples are stored and one or more triple shapes. +The triple shapes have this form: `( )`. `` and `` must be a URI string (e.g. `"foaf:Person"`) or a `_` (indicating a wildcard). Triples that match these shapes will go to (or retrieved from) the specified graph (in the above example this is `http://mu.semte.ch/graphs/organizations/`). +These are all the possible operators: +- `T -> p`: Triples where the subject is of type `T` and the predicate is `p`. +- `T <- p`: Triples where the object is of type `T` and the predicate is `p`. +- `T x> p`: For triples where the subject is of type `T`, allow every predicate except for `p`. +- `T Date: Mon, 25 Aug 2025 17:03:04 +0200 Subject: [PATCH 2/3] restructure and add to readme --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 50 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 33d7247..852c157 100644 --- a/README.md +++ b/README.md @@ -64,26 +64,36 @@ Next, add the following contents to the config file mounted in `./config/authori It basically configures read/write access for everyone for all data on the `http://mu.semte.ch/graphs/public` graph. ## Tutorials -### Defining prefixes -In order to use the CURIE (Compact URI) form (e.g. `foaf:name`) we need to define the prefixes first. This is done as follows: +### Specifying groups of users +sparql-parser does authentication based on user groups. We will later define which groups are allowed to perform which operations on which data. So first we need to define some user groups. +User groups are defined based on the result of a query involving the users session id. This can look as follows: ```lisp -(define-prefixes - :adms "http://www.w3.org/ns/adms#" - :cal "http://www.w3.org/2002/12/cal/ical#" - :cogs "http://vocab.deri.ie/cogs#" - :dcat "http://www.w3.org/ns/dcat#" - :ext "http://mu.semte.ch/vocabularies/ext/" - :eli "http://data.europa.eu/eli/ontology#") +(supply-allowed-group "super-mega-admins" + :parameters ("session_group_id" "session_role") + :query "PREFIX ext: + PREFIX mu: + + SELECT ?session_group ?session_role WHERE { + ext:sessionGroup/mu:uuid ?session_group_id; + ext:sessionRole ?session_role. + FILTER( ?session_role = \"SuperMegaAdmin\" ) + }") ``` +If this query returns a result, the user will belong to the `super-mega-admins` group. The value for `` will be filled in automatically at runtime. The value of the variables listed in the `:parameters` argument will be joined using `/` and appended to the graph URI when it is accessed. This allows us to have a separate graph per user group. + ### Specifying which triples are accessible from which graphs -For this we need a `define-graph` block. This looks as follows: +For this we need a `define-graph` block. This will create a *graph spec* and looks as follows: ```lisp (define-graph organization ("http://mu.semte.ch/graphs/organizations/") ("foaf:Person" -> _) - ("foaf:OnlineAccount" x> "ext:password") + ("foaf:OnlineAccount" x> "ext:password")) ``` -The `define-graph` macro takes a unique identifier, the URI of the graph where the triples are stored and one or more triple shapes. -The triple shapes have this form: `( )`. `` and `` must be a URI string (e.g. `"foaf:Person"`) or a `_` (indicating a wildcard). Triples that match these shapes will go to (or retrieved from) the specified graph (in the above example this is `http://mu.semte.ch/graphs/organizations/`). +**NOTE**: Any prefixes such as `foaf` and `ext` need to be defined, see [Defining prefixes](#defining-prefixes) + +The `define-graph` macro takes a unique identifier, the URI of the graph where the triples are stored, and one or more triple shapes. +The triple shapes have this form: `( )`. `` and `` must be a URI string (e.g. `"foaf:Person"`) or a `_` (indicating a wildcard). Triples that match these shapes will go to (or retrieved from) the specified graph (in the above example this is `http://mu.semte.ch/graphs/organizations/`). +**Note**: different *graph specs* can specify the same graph URI. + These are all the possible operators: - `T -> p`: Triples where the subject is of type `T` and the predicate is `p`. - `T <- p`: Triples where the object is of type `T` and the predicate is `p`. @@ -91,11 +101,35 @@ These are all the possible operators: - `T Date: Mon, 25 Aug 2025 17:26:21 +0200 Subject: [PATCH 3/3] improve structure --- README.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 852c157..e4658a3 100644 --- a/README.md +++ b/README.md @@ -66,7 +66,7 @@ It basically configures read/write access for everyone for all data on the `http ## Tutorials ### Specifying groups of users sparql-parser does authentication based on user groups. We will later define which groups are allowed to perform which operations on which data. So first we need to define some user groups. -User groups are defined based on the result of a query involving the users session id. This can look as follows: +User groups are defined based on the result of a query involving the user's session id. This can look as follows: ```lisp (supply-allowed-group "super-mega-admins" :parameters ("session_group_id" "session_role") @@ -90,7 +90,11 @@ For this we need a `define-graph` block. This will create a *graph spec* and loo ``` **NOTE**: Any prefixes such as `foaf` and `ext` need to be defined, see [Defining prefixes](#defining-prefixes) -The `define-graph` macro takes a unique identifier, the URI of the graph where the triples are stored, and one or more triple shapes. +The `define-graph` macro takes: +- A unique identifier (*here `organization`*) +- The URI of the graph where the triples are stored (*here `http://mu.semte.ch/graphs/organizations/`*) +- One or more triple shapes (*here `("foaf:Person" -> _)` and `("foaf:OnlineAccount" x> "ext:password")`*). + The triple shapes have this form: `( )`. `` and `` must be a URI string (e.g. `"foaf:Person"`) or a `_` (indicating a wildcard). Triples that match these shapes will go to (or retrieved from) the specified graph (in the above example this is `http://mu.semte.ch/graphs/organizations/`). **Note**: different *graph specs* can specify the same graph URI. @@ -105,15 +109,18 @@ In the above example this means the following: - Matches all triples where the subject is of type `foaf:OnlineAccount` and where the predicate is not `ext:password`. ### Specifying which user groups have access to which graphs -Finally we need to specify which users are allowed to access which *graph spec*. This is done using the `grant` macro. +Finally we need to specify which *user groups* are allowed to access which *graph spec*. This is done using the `grant` macro. ```lisp (grant (read write) :to-graph (organization) :for-allowed-group "super-mega-admins") ``` This indicates that we allow the users in the `super-mega-admins` group to read and write tripes from and to the `http://mu.semte.ch/graphs/organizations/` graph, according to the triple restrictions in the `organization` *graph spec*. + The only allowed operation values are `read` and `write`. + `:to-graph` allows specifying multiple *graph specs*. + `:for-allowed-group` specifies which user group is allowed to execute the specified operations.