Skip to content

Commit ff6e9ba

Browse files
dmitrizagidulindmitrizagidulin
committed
First draft of WAC spec (Solid-specific subset)
Addresses issue solid/solid#95
1 parent df598b8 commit ff6e9ba

File tree

2 files changed

+195
-2
lines changed

2 files changed

+195
-2
lines changed

‎CHANGELOG.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
##### v0.1.0
2+
3+
First draft of spec, as of Apr 2016.

‎README.md

+192-2
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,192 @@
1-
# web-access-control-spec
2-
Web Access Control (WAC) specification (as used by the Solid project)
1+
# Web Access Control (WAC)
2+
[![](https://img.shields.io/badge/project-Solid-7C4DFF.svg?style=flat-square)](https://github.com/solid/solid)
3+
4+
Web Access Control (WAC) specification (as used by the Solid project). It
5+
is based on Tim Berners-Lee's May 2009 proposal, as originally captured, and
6+
subsequently evolved by the community, at
7+
[Web Access Control Wiki](https://www.w3.org/wiki/WebAccessControl). This spec
8+
is a particular subset of the options and extensions described in the wiki.
9+
10+
**Current Spec version:** `v.0.1.0` (see [CHANGELOG.md](CHANGELOG.md))
11+
12+
## Table of Contents
13+
14+
1. [Overview](#overview)
15+
2. [Vocabulary](#vocabulary)
16+
3. [Example WAC Document](#example-wac-document)
17+
4. [Describing Agents](#describing-agents)
18+
5. [Referring to Resources](#referring-to-resources)
19+
6. [Modes of Access](#modes-of-access)
20+
21+
## Overview
22+
23+
Web Access Control (WAC) is a decentralized cross-domain access control system.
24+
The main concepts should be familiar to developers, as they are similar to
25+
access control schemes used in many file systems. It's concerned with giving
26+
access to agents (users, groups and more) to perform various kinds of operations
27+
(read, write, append, etc) on resources. WAC has several key features:
28+
29+
1. The resources are identified by URLs, and can refer to any web documents or
30+
resources.
31+
2. It is *declarative* -- access control policies live in regular web documents,
32+
as opposed to in separate privileged subsystems (as they do in many operating
33+
systems).
34+
3. Users and groups are also identified by URLs (specifically, by
35+
[Web IDs](https://github.com/solid/solid-spec#identity))
36+
4. It is *cross-domain* -- all of its components, such as resources, agent Web
37+
IDs, and even the documents containing the access control policies, can
38+
potentially reside on separate domains. In other words, you can give access
39+
to a resource on one site to users and groups hosted on another site.
40+
41+
WAC documents contain a number of *Authorizations*, in Linked Data format
42+
([Turtle](http://www.w3.org/TR/turtle/) by default, but also available in other
43+
serializations). Each Authorization has statements describing: who the
44+
authorized *agents* are, which *resources* they have access to, and what types
45+
(*modes*) of access they are being granted.
46+
47+
Note: A familiarity with Linked Data and
48+
[RDF Concepts](http://www.w3.org/TR/rdf11-concepts/) helps with understanding
49+
the terminology used in this spec.
50+
51+
## Vocabulary
52+
53+
WAC uses the http://www.w3.org/ns/auth/acl ontology for its terms. Through the
54+
rest of the spec, the prefix `acl:` is assumed to mean
55+
`@prefix acl: <http://www.w3.org/ns/auth/acl#> .`
56+
57+
## Example WAC Document
58+
59+
Below is an example WAC document (often referred to as an 'ACL resource') that
60+
specifies that Alice (as identified by her Web ID
61+
`https://alice.databox.me/profile/card#me`) has full access (Read, Write and
62+
Control) to one of her web resources, located at
63+
`https://alice.databox.me/file1`.
64+
65+
The exact location of `file1`'s corresponding ACL resource is
66+
technically opaque (the naming convention may differ between various servers
67+
and implementations). In this example, for simplicity, we use the current
68+
[LDNode](https://github.com/linkeddata/ldnode) convention and locate it
69+
at `file1.acl`:
70+
71+
```ttl
72+
# Contents of https://alice.databox.me/file1.acl
73+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
74+
75+
<#authorization1>
76+
a acl:Authorization;
77+
acl:agent <https://alice.databox.me/profile/card#me>; # Alice's Web ID
78+
acl:accessTo <https://alice.databox.me/file1>;
79+
acl:mode
80+
acl:Read, acl:Write, acl:Control.
81+
```
82+
83+
## Describing Agents
84+
85+
In WAC, we use the term *Agent* to identify *who* is allowed access to various
86+
resources. In general, it is assumed to mean "someone or something that can
87+
be referenced with a Web ID", which covers users, groups (as well as companies
88+
and organizations), and software agents such as applications or services.
89+
90+
### Singular Agent
91+
92+
An authorization may list any number of individual agents (that are being given
93+
access) by using the `acl:agent` predicate, and using their Web ID URIs as
94+
subjects.
95+
96+
### Groups of Agents
97+
98+
If you need to give access to a particular group of agents, you can instead use
99+
the `acl:agentClass` predicate, and point it to a resource which lists the
100+
Web IDs of the individual members of that group.
101+
102+
#### All Agents (Public)
103+
104+
To specify that you're giving a particular mode of access to *everyone*
105+
(for example, that your Web ID Profile is public-readable), you can use
106+
`acl:agentClass foaf:Agent` to denote that you're giving access to the class
107+
of *all* agents (the general public). For example:
108+
109+
```ttl
110+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
111+
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
112+
113+
<#authorization2>
114+
a acl:Authorization;
115+
acl:agentClass foaf:Agent; # everyone
116+
acl:mode acl:Read; # has Read-only access
117+
acl:accessTo <https://alice.databox.me/profile/card>. # to the public profile
118+
```
119+
120+
## Referring to Resources
121+
122+
The `acl:accessTo` predicate specifies *which resources* you're giving access
123+
to, using their URLs as the subjects.
124+
125+
### Referring to the ACL Resource Itself
126+
127+
Since an ACL resource is a plain Web document in itself, what controls who
128+
has access to *it*? While an ACL resource *could* in theory have its own
129+
corresponding ACL document (for example, `file1.acl` controls access to `file1`,
130+
and `file1.acl.acl` could potentially control access to `file1.acl`), one
131+
quickly realize thats this recursion has to end somewhere.
132+
133+
As mentioned in the Introduction, one of the design goals of Web Access Control
134+
is that the ACL resources themselves do not get any special treatment by
135+
the server -- they are plain Web resources with Linked Data statements in them,
136+
and so their own access has to be controlled by other Linked Data statements
137+
that have to live somewhere. To avoid multiple levels of recursion, it is
138+
recommended that the authorizations that control who has access to an ACL
139+
document are placed *in the ACL document itself*.
140+
141+
In other words, an ACL document typically controls its own access, explicitly.
142+
To extend a [previous example](#example-wac-document):
143+
144+
```ttl
145+
# Contents of https://alice.databox.me/file1.acl
146+
@prefix acl: <http://www.w3.org/ns/auth/acl#>.
147+
148+
<#authorization1>
149+
# ... statements controlling access to file1
150+
151+
# This authorization concerns the ACL resource itself
152+
<#authorization2>
153+
a acl:Authorization;
154+
acl:accessTo <>; # gives access to this document
155+
acl:agent <https://alice.databox.me/profile/card#me>; # to Alice's Web ID
156+
acl:mode
157+
acl:Read, acl:Write, acl:Control.
158+
```
159+
160+
## Modes of Access
161+
162+
The `acl:mode` predicate denotes a class of operations that the agents can
163+
perform on a resource.
164+
165+
##### `acl:Read`
166+
gives access to a class of operations that can be described as "Read
167+
Access". In a typical REST API (such as the one used by Solid), this includes
168+
access to HTTP verbs `GET`, and `HEAD`. This also includes any kind of
169+
QUERY or SEARCH verbs, if supported.
170+
171+
##### `acl:Write`
172+
gives access to a class of operations that can modify the resource. In a REST
173+
API context, this would include `PUT`, `POST`, `DELETE` and `PATCH`. This also
174+
includes the ability to perform SPARQL queries that perform updates, if those
175+
are supported.
176+
177+
##### `acl:Append`
178+
gives a more limited ability to write to a resource -- Append-Only. This
179+
generally includes the HTTP verb `POST`, although some implementations may
180+
also extend this mode to cover non-overwriting `PUT`s, as well as the
181+
`INSERT`-only portion of SPARQL-based `PATCH`es. A typical example of Append
182+
mode usage would be a user's Inbox -- other agents can write (append)
183+
notifications to the inbox, but cannot alter or read existing ones.
184+
185+
##### `acl:Control`
186+
is a special-case access mode that gives an agent the ability to *modify the
187+
ACL of a resource*. Note that it doesn't automatically imply that the agent
188+
has `acl:Write` access to the resource itself, just to its corresponding ACL
189+
document. For example, a resource owner may disable their own Write access
190+
(to prevent accidental over-writing of a resource by an app), but be able to
191+
change their access levels at a later point (since they retain `acl:Control`
192+
access).

0 commit comments

Comments
 (0)