Skip to content

Change Group section to agentGroup, move agentClass to proposals/ #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Aug 22, 2016
Merged

Change Group section to agentGroup, move agentClass to proposals/ #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b5fbe10
Change Group section to agentGroup, move agentClass to proposals/
dmitrizagidulin Aug 17, 2016
d6505cf
Clarify relationship betwen Group Listings and their containing docum…
dmitrizagidulin Aug 18, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
##### v.0.4.0

- Change Group ACL definition spec to one based on `vcard:hasMember` instead of
`acl:agentClass`. Move previous `agentClass` based section to `proposals/` for
archival purposes.

##### v.0.3.1

- Add a discussion of infinite loops in Group ACL resolution
Expand Down
59 changes: 34 additions & 25 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Next](https://www.w3.org/community/ldpnext/)) type systems, such as the
[Solid](https://github.com/solid/solid) project (see also the parent
[spec](https://github.com/solid/solid-spec)).

**Current Spec version:** `v.0.3.1` (see [CHANGELOG.md](CHANGELOG.md))
**Current Spec version:** `v.0.4.0` (see [CHANGELOG.md](CHANGELOG.md))

## Table of Contents

Expand Down Expand Up @@ -224,10 +224,10 @@ as denoted by her WebID URI, `https://alice.databox.me/profile/card#me`.

### Groups of Agents

To give access to a group of agents, use the `acl:agentClass` predicate.
The object of an `agentClass` statement is a hash fragment identifier that
resolves to an RDF class statement in a **Group Listing** document.
If a WebID is listed in that document, *and* it's of the specified class, it is
To give access to a group of agents, use the `acl:agentGroup` predicate.
The object of an `agentGroup` statement is a link to a **Group Listing**
document. The WebIDs of group members are listed in it, using the
`vcard:hasMember` predicate. If a WebID is listed in that document, it is
given access.

Example ACL resource, `shared-file1.acl`, containing a group permission:
Expand All @@ -249,32 +249,40 @@ Example ACL resource, `shared-file1.acl`, containing a group permission:
a acl:Authorization;
acl:accessTo <https://alice.example.com/docs/shared-file1>;
acl:mode acl:Read, acl:Write;
acl:agentClass <https://alice.example.com/work-groups#Accounting>;
acl:agentClass <https://alice.example.com/work-groups#Management>.
acl:agentGroup <https://alice.example.com/work-groups#Accounting>;
acl:agentGroup <https://alice.example.com/work-groups#Management>.
```

Corresponding `work-groups` Group Listing document:

```ttl
# Contents of https://alice.example.com/work-groups
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix vcard: <http://www.w3.org/2006/vcard/ns#> .

<> a acl:GroupListing.

<#Employee> a rdfs:Class.
<#Accounting> a rdfs:Class.
<#Management> a rdfs:Class.
<#Accounting>
a vcard:Group;
vcard:hasUID <urn:uuid:8831CBAD-1111-2222-8563-F0F4787E5398:ABGroup>;
dc:created "2013-09-11T07:18:19+0000"^^xsd:dateTime;
dc:modified "2015-08-08T14:45:15+0000"^^xsd:dateTime;

<https://bob.example.com/profile/card#me> a <#Employee>, <#Accounting>.
<https://candice.example.com/profile/card#me> a <#Employee>, <#Accounting>.
# Accounting group members:
vcard:hasMember <https://bob.example.com/profile/card#me>;
vcard:hasMember <https://candice.example.com/profile/card#me>.

<https://deb.example.com/profile/card#me> a <#Employee>, <#Management>.
<#Management>
a vcard:Group;
vcard:hasUID <urn:uuid:8831CBAD-3333-4444-8563-F0F4787E5398:ABGroup>;

# Management group members:
vcard:hasMember <https://deb.example.com/profile/card#me>.
```

#### Group Listings - Implementation Notes

When implementing support for `acl:agentClass` and Group Listings, keep in mind
When implementing support for `acl:agentGroup` and Group Listings, keep in mind
the following issues:

1. Group Listings are regular documents (potentially with their own `.acl`s).
Expand All @@ -285,7 +293,7 @@ the following issues:

##### Group Listings - Authentication of External Requests

Group Listings via `acl:agentClass` links introduce the possibility of an ACL
Group Listings via `acl:agentGroup` links introduce the possibility of an ACL
checking engine having to make requests to other servers. Given that access to
those external group listings can be protected, the question immediately arises:
By what mechanism should the ACL checking engine authenticate its request to
Expand Down Expand Up @@ -327,11 +335,12 @@ examples.
##### Infinite Request Loops in Group Listings

Since Group Listings (which are linked to from ACL resources using
the `acl:agentClass` predicate) are regular documents, they can have their very
own `.acl` resources that restrict which users (or groups) are allowed to access
or change them. This fact, that `.acl`s point to Group Listings, which can have
`.acl`s of their own, which can potentially also point to Group Listings, and so
on, introduces the potential for infinite loops during ACL resolution.
the `acl:agentGroup` predicate) reside in regular documents, those documents
will have their very own `.acl` resources that restrict which users (or groups)
are allowed to access or change them. This fact, that `.acl`s point to Group
Listings, which can have `.acl`s of their own, which can potentially also point
to Group Listings, and so on, introduces the potential for infinite loops
during ACL resolution.

Take the following situation with two different servers:

Expand All @@ -340,15 +349,15 @@ https://a.com https://b.com
------------- GET ---------------
group-listA <------ group-listB.acl
| ^ contains:
| | agentClass <a.com/group-ListA>
| | agentGroup <a.com/group-ListA>
v GET |
group-listA.acl ------> group-listB
contains:
agentClass <b.com/group-listB>
agentGroup <b.com/group-listB>
```

The access to `group-listA` is controlled by `group-listA.acl`. So far so good.
But if `group-listA.acl` contains any `acl:agentClass` references to *another*
But if `group-listA.acl` contains any `acl:agentGroup` references to *another*
group listing (say, points to `group-listB`), one runs into potential danger.
In order to retrieve that other group listing, the ACL-checking engine on
`https://b.com` will need to check the rules in `group-listB.acl`. And if
Expand All @@ -361,7 +370,7 @@ To guard against these loops, implementers have several options:
**A) Do not allow cross-domain Group Listing resolutions**.
The simplest to implement (but also the most limited) option is to disallow
cross-domain Group Listings resolution requests. That is, the ACL-checking code
could detect `agentClass` links pointing to external servers during ACL
could detect `agentGroup` links pointing to external servers during ACL
resolution time, and treat those uniformly (as errors, or as automatic "access
denied").

Expand Down
52 changes: 52 additions & 0 deletions proposals/agent-class.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
### Groups of Agents and `agentClass`

**Note:** Current spec uses `acl:agentGroup` and `vcard:hasMember` to implement
group membership. This section is saved here for reference / archival purposes.

To give access to a group of agents, use the `acl:agentClass` predicate.
The object of an `agentClass` statement is a hash fragment identifier that
resolves to an RDF class statement in a **Group Listing** document.
If a WebID is listed in that document, *and* it's of the specified class, it is
given access.

Example ACL resource, `shared-file1.acl`, containing a group permission:

```ttl
# Contents of https://alice.databox.me/docs/shared-file1.acl
@prefix acl: <http://www.w3.org/ns/auth/acl#>.

# Individual authorization - Alice has Read/Write/Control access
<#authorization1>
a acl:Authorization;
acl:accessTo <https://alice.example.com/docs/shared-file1>;
acl:mode acl:Read, acl:Write, acl:Control;
acl:agent <https://alice.example.com/profile/card#me>.

# Group authorization, giving Read/Write access to two groups, which are
# specified in the 'work-groups' document.
<#authorization2>
a acl:Authorization;
acl:accessTo <https://alice.example.com/docs/shared-file1>;
acl:mode acl:Read, acl:Write;
acl:agentClass <https://alice.example.com/work-groups#Accounting>;
acl:agentClass <https://alice.example.com/work-groups#Management>.
```

Corresponding `work-groups` Group Listing document:

```ttl
# Contents of https://alice.example.com/work-groups
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.

<> a acl:GroupListing.

<#Employee> a rdfs:Class.
<#Accounting> a rdfs:Class.
<#Management> a rdfs:Class.

<https://bob.example.com/profile/card#me> a <#Employee>, <#Accounting>.
<https://candice.example.com/profile/card#me> a <#Employee>, <#Accounting>.

<https://deb.example.com/profile/card#me> a <#Employee>, <#Management>.
```