Skip to content

Commit a4eaae2

Browse files
joachimvhjoachimvh
committed
docs: Explain asset collection implementation
1 parent a1153f5 commit a4eaae2

File tree

2 files changed

+157
-0
lines changed

2 files changed

+157
-0
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ You can then execute the following flows:
2929
- `yarn script:uma-ucp`: `PUT` some text to the private `/alice/other/resource.txt`, protected by a UCP enforcer checking WebIDs according to policies in `packages/uma/config/rules/policy/`.
3030
- `yarn script:collection`: `POST`, `GET` and `DELETE` some text to/from `/alice/public/resource.txt` to test the correct creation and deletion of resource registrations on the UMA server.
3131
An AssetCollection policy is used to create `/alice/public/`.
32+
More information on the collection implementation can be found in [docs/collections.md](docs/collections.md).
3233

3334
`yarn script:flow` runs all flows in sequence.
3435

‎docs/collections.md

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# ODRL policies targeting collections
2+
3+
This document describes how this UMA server supports ODRL collections,
4+
and the issues encountered when implementing this,
5+
some of which still need to be resolved cleanly.
6+
7+
## WAC / ACP
8+
9+
The main reason for adding support is that we wanted to be able to use ODRL policies
10+
started from wanting to describe permissions on the contents of LDP containers.
11+
We do not want the UMA server to be tied to the LDP interface though,
12+
so the goal was to have a generic solution that can handle any kind of relationship between resources.
13+
14+
## Example ODRL policy
15+
16+
Below is an example of what a policy targeting the contents of a container looks like:
17+
18+
```ttl
19+
@prefix ex: <http://example.org/> .
20+
@prefix ldp: <http://www.w3.org/ns/ldp#>.
21+
@prefix odrl: <http://www.w3.org/ns/odrl/2/>.
22+
@prefix odrl_p: <https://w3id.org/force/odrl3proposal#>.
23+
24+
<urn:uuid:e30bcd34-0d5c-43d1-b229-bf68afcae5ae> a odrl:Set ;
25+
odrl:uid <urn:uuid:e30bcd34-0d5c-43d1-b229-bf68afcae5ae> ;
26+
odrl:permission <urn:uuid:f4cb5007-e834-4a9c-a62a-091891350c04> .
27+
28+
<urn:uuid:f4cb5007-e834-4a9c-a62a-091891350c04> a odrl:Permission ;
29+
odrl:assignee ex:alice ;
30+
odrl:action odrl:read ;
31+
odrl:target ex:assetCollection .
32+
33+
ex:assetCollection a odrl:AssetCollection ;
34+
odrl:source <http://localhost:3000/container/> ;
35+
odrl_p:relation ldp:contains .
36+
```
37+
38+
The above policy gives Alice read permission on all resources in `http://localhost:3000/container/`.
39+
40+
## New resource description fields
41+
42+
To support collections, the RS now includes two additional fields when registering a resource,
43+
in addition to those defined in the UMA specification.
44+
45+
* `resource_defaults`: A key/value map describing the scopes of collections having the registered resource as a source.
46+
The keys are the relations and the values are arrays of scopes.
47+
* `resource_relations`: A key/value map linking this resource to others through relations.
48+
The keys are the relations and the values are the UMA IDs of the relation targets.
49+
If the relation starts with `^` a reverse relation is implied.
50+
51+
An example of such an extended resource description:
52+
```json
53+
{
54+
"resource_scopes": [ "read", "write" ],
55+
"resource_defaults": {
56+
"http://www.w3.org/ns/ldp#contains": [ "read" ]
57+
},
58+
"resource_relations": {
59+
"^http://www.w3.org/ns/ldp#contains": [ "assets:1234c" ]
60+
}
61+
}
62+
```
63+
64+
The above example tells the UMA server that the available scopes for this new resource are `read` and `write`,
65+
as defined in the UMA specification.
66+
The new field `resource_defaults` tells the server that all containers for
67+
the `http://www.w3.org/ns/ldp#contains` relation
68+
that have this resource as the source,
69+
have `read` as an available scope.
70+
Finally, the `resource_relations` field indicates that the resource `assets:1234c`
71+
has the `http://www.w3.org/ns/ldp#contains` relation with as target the newly registered resource.
72+
This is the reverse as indicated by the `^` in the string.
73+
74+
## UMA identifiers
75+
76+
Currently, the UMA server does not yet have the support to allow users to easily write policies using UMA IDs.
77+
This is why all the example policies target the URLs of the resources in the RS.
78+
To make sure this is still UMA compatible,
79+
the UMA server copies the RS URL of the resource as UMA ID.
80+
To provide this information to the UMA server,
81+
the `name` field is used in the resource description when registering a resource.
82+
83+
## Transitive relations
84+
85+
The current implementation sees all relations as transitive.
86+
This means that if resource A has relation R to resource B,
87+
and resource B has relation R to resource C,
88+
resource A is assumed to also have relation R to resource C.
89+
As a consequence, policies targeting the collection that has as source C,
90+
will be applicable to both A and B.
91+
92+
## Generating collection triples
93+
94+
When registering a resource,
95+
the UMA server immediately generates all necessary triples to keep track of all collections a resource is part of.
96+
When registering the resource in the example above,
97+
the UMA server would first look for all collections matching the pattern
98+
```ttl
99+
@prefix odrl: <http://www.w3.org/ns/odrl/2/>.
100+
@prefix odrl_p: <https://w3id.org/force/odrl3proposal#>.
101+
102+
?a a odrl:AssetCollection ;
103+
odrl:source <assets:1234c> ;
104+
odrl_p:relation <http://www.w3.org/ns/ldp#contains> .
105+
```
106+
107+
If no such collection exists, triples would be generated to create one.
108+
The triple `<NEW-ID> odrl:partOf <COLLECTION-ID>` would then be added,
109+
with `NEW-ID` being the newly generated UMA ID, and `COLLECTION-ID` being the ID of the matching collections.
110+
Because of the transitive property described above,
111+
the server would also look for all collections `assets:1234c` is a part of,
112+
and continue doing this recursively for the collections it finds,
113+
and also generate triples with those identifiers.
114+
The internal ODRL evaluator will then use these triples to find the matching policies during evaluation.
115+
116+
## Known issues/workarounds
117+
118+
Below are some of the issues encountered while implementing this,
119+
that might need more robust solutions.
120+
121+
### Parent containers not yet registered
122+
123+
Resource registration happens asynchronously.
124+
As a consequence,
125+
it is possible, when registering a resource,
126+
that the registration of its parent container was not yet completed.
127+
The UMA ID of this parent is necessary to link to the correct relation though.
128+
The current solution is to register the resource without the relations and retry twice:
129+
once immediately after the registration is successful, and once after 30 seconds.
130+
131+
A more robust solution would be preferable, where it is guaranteed that the parent relation will always be registered.
132+
133+
### Policies for resources that do not yet exist
134+
135+
When creating a new resource on the RS, using PUT for example,
136+
it is necessary to know if that action is allowed.
137+
It is not possible to generate an UMA ticket with this potentially new resource as a target though,
138+
as it does not have an UMA ID yet since it does not yet exist.
139+
The current implementation instead generates a ticket targeting the first existing (grand)parent container,
140+
and requests the `create` scope.
141+
142+
Solid does have some edge case situations that are no longer covered this way.
143+
For example, trying to read a non-existent resource would give a different response
144+
depending on if the client was allowed to read it or not (404 vs 401/403).
145+
146+
### How to determine which side of the relation is the collection
147+
148+
When resource registrations include the `resource_relations` field,
149+
it indicates relations of the form `A R B`.
150+
With A or B being the newly registered resource,
151+
depending on if the relation is reversed or not.
152+
153+
One of the sides of the relation would be the source of a collection,
154+
and the other side would then be part of that collection.
155+
Currently, we have no clear way to indicate which is which,
156+
so for now the server will always assume the subject of the triple is the collection source.

0 commit comments

Comments
 (0)