diff --git a/README-v0.5.0.md b/README-v0.5.0.md new file mode 100644 index 00000000..29ae614d --- /dev/null +++ b/README-v0.5.0.md @@ -0,0 +1,713 @@ +# Web Access Control (WAC) +[![](https://img.shields.io/badge/project-Solid-7C4DFF.svg?style=flat-square)](https://github.com/solid/solid) + +Web Access Control (WAC) specification (as used by the Solid project). It +is based on Tim Berners-Lee's May 2009 proposal, as originally captured, and +subsequently evolved by the community, at +[Web Access Control Wiki](https://www.w3.org/wiki/WebAccessControl). This spec +is a particular subset of the options and extensions described in the wiki. + +For use with [LDP](https://www.w3.org/TR/ldp/) (and [LDP +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.5.0` (see [CHANGELOG.md](CHANGELOG.md)) + +## Table of Contents + +1. [Overview](#overview) +2. [Access Control List Resources](#access-control-list-resources) + * [Containers and Inherited ACLs](#containers-and-inherited-acls) + * [Individual Resource ACLs](#individual-resource-acls) + * [ACL Resource Location Discovery](#acl-resource-location-discovery) +3. [ACL Inheritance Algorithm](#acl-inheritance-algorithm) +4. [Representation Format](#representation-format) +5. [Example WAC Document](#example-wac-document) +6. [Describing Agents](#describing-agents) + * [Singular Agent](#singular-agent) + * [Groups](#groups-of-agents) + * [Public Access (all Agents)](#public-access-all-agents) + * [Anyone logged on (Authenticated Agents)](#authenticated-agents-anyone-logged-on) + * [Referring to Origins, i.e. Web Apps](#referring-to-origins-ie-web-apps) +7. [Referring to Resources](#referring-to-resources) +8. [Modes of Access](#modes-of-access) +9. [Default (Inherited) Authorizations](#default-inherited-authorizations) +10. [Not Supported by Design](#not-supported-by-design) + +## Overview + +Web Access Control (WAC) is a decentralized cross-domain access control system. +The main concepts should be familiar to developers, as they are similar to +access control schemes used in many file systems. It's concerned with giving +access to agents (users, groups and more) to perform various kinds of operations +(read, write, append, etc) on resources. WAC has several key features: + +1. The resources are identified by URLs, and can refer to any web documents or + resources. +2. It is *declarative* -- access control policies live in regular web documents, + which can be exported/backed easily, using the same mechanism as you would + for backing up the rest of your data. +3. Users and groups are also identified by URLs (specifically, by + [WebIDs](https://github.com/solid/solid-spec#identity)) +4. It is *cross-domain* -- all of its components, such as resources, agent + WebIDs, and even the documents containing the access control policies, can + potentially reside on separate domains. In other words, you can give access + to a resource on one site to users and groups hosted on another site. + +## Access Control List Resources + +In a system that uses Web Access Control, each web resource has a set of +*Authorization* statements describing: + +1. Who has access to that resource (that is, who the authorized *agents* are) +2. What types (or *modes*) of access they have + +These Authorizations are either explicitly set for an individual resource, or +(more often) inherited from that resource's parent folder or container. In +either case, the Authorization statements are placed into separate WAC +documents called *Access Control List Resources* (or simply *ACLs*). + +### Containers and Inherited ACLs + +The WAC system assumes that web documents are placed in hierarchical containers +or folders. For convenience, users do not have to specify permissions on each +individual resource -- they can simply set default permissions on a container using a +[`acl:default`](#default-inherited-authorizations) predicate and the exact container URI +as the object, and have all +of the resources in that container [inherit](#acl-inheritance-algorithm) those +permissions. + +### Individual Resource ACLs + +For fine-grained control, users can specify a set of permissions for each +individual resource (which overrides any permissions of its parent container). +See the [Example WAC Document](#example-wac-document) section to get an idea +for what that would look like. + +### ACL Resource Location Discovery + +Given a URL for an individual resource or container, a client can discover the +location of its corresponding ACL by performing a `HEAD` (or a `GET`) request +and parsing the `rel="acl"` link relation. + +Example request to discover the location of the ACL resource for a web document +at `http://example.org/docs/file1` is given below: + +```http +HEAD /docs/file1 HTTP/1.1 +Host: example.org + +HTTP/1.1 200 OK +Link: ; rel="acl" +``` + +The request to discover the location of a container's ACL resource looks +similar: + +```http +HEAD /docs/ HTTP/1.1 +Host: example.org + +HTTP/1.1 200 OK +Link: <.acl>; rel="acl" +``` + +Note that the `acl` link relation uses relative path URLs (the absolute URL of +the ACL resource in the above example would be `/docs/.acl`). + +Clients MUST NOT assume that the location of an ACL resource can be +deterministically derived from a document's URL. For example, given a document +with a URL of `/docs/file1`, clients cannot rely on the assumption that an ACL +resource exists at `/docs/file1.acl`, simply using `.acl` as a suffix. The +actual naming convention for ACL resources can differ for each individual +implementation (or even for each individual server). If one server locates the +ACL resource by appending the suffix `.acl`, another server could place the ACL +resources into a sub-container (locating it at `/docs/.acl/file1.acl` for the +example above). + +## ACL Schemas + +*This section is non-normative.* ( Issue: https://github.com/solid/specification/issues/169 ) + +The following schema excerpts use these namespace prefixes: +``` turtle +PREFIX acl: +PREFIX dc: +PREFIX vcard: +PREFIX xsd: +``` +### Authorization Schema +``` turtle +<#authShape> { + a [acl:Authorization] ; + acl:accessTo IRI ; + acl:mode [acl:Read acl:Write acl:Control]+ ; + ( acl:agent IRI ; + | acl:agentGroup @<#groupShape> + + ) ; +} +``` + +### Group Schema + +``` turtle +<#groupShape> { + a [vcard:Group] ; + vcard:hasUID IRI /^urn:uuid:/ ; + dc:created xsd:dateTime ? ; + dc:modified xsd:dateTime ? ; + vcard:hasMember IRI + ; +} +``` + +## ACL Inheritance Algorithm + +The following algorithm is used by servers to determine which ACL resources +(and hence which set of Authorization statements) apply to any given resource: + +1. Use the document's own ACL resource if it exists (in which case, stop here). +2. Otherwise, look for authorizations to inherit from the ACL of the document's + container. If those are found, stop here. +3. Failing that, check the container's *parent* container to see if *that* has + its own ACL file, and see if there are any permissions to inherit. +4. Failing that, move up the container hierarchy until you find a container + with an existing ACL file, which has some permissions to inherit. +5. The *root container* of a user's account MUST have an ACL resource specified. + (If all else fails, the search stops there.) + +It is considered an anti-pattern for a *client* to perform those steps, however. +A client may [discover](#acl-resource-location-discovery) and load a document's +individual resource (for example, for the purposes of editing its permissions). +If such a resource does not exist, a client SHOULD NOT search for, or interact +with, the inherited ACLs from an upstream container. + +### ACL Inheritance Algorithm Example + +*Note:* The server in the examples below is using the ACL naming convention of +appending `.acl` to resource URLs, for simplicity. As mentioned in the section +on [ACL discovery](#acl-resource-location-discovery), clients should not use +or assume any naming convention. + +A request (to read or write) has arrived for a document located at +`/documents/papers/paper1`. The server does as follows: + +1. First, it checks for the existence of an individual corresponding ACL + resource. (That is, it checks if `paper1.acl` exists.) If this individual ACL + resource exists, the server uses the Authorization statements in that ACL. No + other statements apply. +2. If no individual ACL exists, the server next checks to see if the + `/documents/papers/` container (in which the document resides) has its own + ACL resource (here, `/documents/papers/.acl`). If it finds that, the server + reads each authorization in the container's ACL, and if any of them contain an + `acl:default` predicate, the server will use them (as if they were + specified in `paper1.acl`). Again, if any such authorizations are found, the + process stops there and no other statements apply. +3. If the document's container has no ACL resource of its own, the search + continues upstream, in the *parent* container. The server would check if + `/documents/.acl` exists, and then `/.acl`, until it finds some authorizations + that contain `acl:default`. +4. Since the root container (here, `/`) MUST have its own ACL resource, the + server would use the authorizations there as a last resort. + +See the [Default (Inherited) Authorizations](#default-inherited-authorizations) +section below for an example of what a container's ACL resource might look like. + +## Representation Format + +The permissions in an ACL resource are stored in Linked Data format +([Turtle](http://www.w3.org/TR/turtle/) by default, but also available in other +serializations). + +*Note: A familiarity with Linked Data and +[RDF Concepts](http://www.w3.org/TR/rdf11-concepts/) helps with understanding +the terminology used in this spec.* + +WAC uses the [`http://www.w3.org/ns/auth/acl`](http://www.w3.org/ns/auth/acl) +ontology for its terms. Through the rest of the spec, the prefix `acl:` is +assumed to mean `@prefix acl: .` + +## Example WAC Document + +Below is an example ACL resource that specifies that Alice (as identified by her +WebID `https://alice.databox.me/profile/card#me`) has full access (Read, Write +and Control) to one of her web resources, located at +`https://alice.databox.me/docs/file1`. + +```ttl +# Contents of https://alice.databox.me/docs/file1.acl +@prefix acl: . + +<#authorization1> + a acl:Authorization; + acl:agent ; # Alice's WebID + acl:accessTo ; + acl:mode acl:Read, + acl:Write, + acl:Control. +``` + +## Describing Agents + +In WAC, we use the term *Agent* to identify *who* is allowed access to various +resources. In general, it is assumed to mean "someone or something that can +be referenced with a WebID", which covers users, groups (as well as companies +and organizations), and software agents such as applications or services. + +### Singular Agent + +An authorization may list any number of individual agents (that are being given +access) by using the `acl:agent` predicate, and using their WebID URIs as +objects. The example WAC document in a previous section grants access to Alice, +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:agentGroup` predicate. +The object of an `agentGroup` statement is an instance of `vcard:Group`. +The WebIDs of group members are listed in it, using the +`vcard:hasMember` predicate. If a WebID is listed as member of that group, +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: . + +# Individual authorization - Alice has Read/Write/Control access +<#authorization1> + a acl:Authorization; + acl:accessTo ; + acl:mode acl:Read, + acl:Write, + acl:Control; + acl:agent . + +# Group authorization, giving Read/Write access to two groups, which are +# specified in the 'work-groups' document. +<#authorization2> + a acl:Authorization; + acl:accessTo ; + acl:mode acl:Read, + acl:Write; + acl:agentGroup ; + acl:agentGroup . +``` + +Corresponding `work-groups` Group Listing document: + +```ttl +# Contents of https://alice.example.com/work-groups +@prefix acl: . +@prefix dc: . +@prefix vcard: . +@prefix xsd: . + +<#Accounting> + a vcard:Group; + vcard:hasUID ; + dc:created "2013-09-11T07:18:19Z"^^xsd:dateTime; + dc:modified "2015-08-08T14:45:15Z"^^xsd:dateTime; + + # Accounting group members: + vcard:hasMember ; + vcard:hasMember . + +<#Management> + a vcard:Group; + vcard:hasUID ; + + # Management group members: + vcard:hasMember . +``` +[[test against schema](https://tinyurl.com/whcrhlo)] + +#### Group Listings - Implementation Notes + +When implementing support for `acl:agentGroup` and Group Listings, keep in mind +the following issues: + +1. Group Listings are regular documents (potentially each with its own `.acl`). +2. What authentication mechanism should the ACL checking engine use, when making + requests for Group Listing documents on other servers? +3. Infinite request loops during ACL resolution become possible, if an `.acl` + points to a group listing on a different server. +4. Therefore, for the moment, we suggest that all Group files which are used + for group ACLs are public. + +Possible future methods for a server to find out whether a given agent is a +member of a group are a matter for future research and possible addition here. + +### Public Access (All Agents) + +To specify that you're giving a particular mode of access to *everyone* +(for example, that your WebID Profile is public-readable), you can use +`acl:agentClass foaf:Agent` to denote that you're giving access to the class +of *all* agents (the general public). For example: + +```ttl +@prefix acl: . +@prefix foaf: . + +<#authorization2> + a acl:Authorization; + acl:agentClass foaf:Agent; # everyone + acl:mode acl:Read; # has Read-only access + acl:accessTo . # to the public profile +``` + +### Authenticated Agents (Anyone logged on) + +Authenticated access is a bit like public access +but it is not anonymous. Access is only given to people +who have logged on and provided a specific ID. +This allows the server to track the people who have used the resource. + +To specify that you're giving a particular mode of access to anyone *logged on* +(for example, that your collaborative page is open to anyone but you want to know who they are), +you can use +`acl:agentClass acl:AuthenticatedAgent` to denote that you're giving access to the class +of *all* authenticated agents. For example: + +```ttl +@prefix acl: . +@prefix foaf: . + +<#authorization2> + a acl:Authorization; + acl:agentClass acl:AuthenticatedAgent; # everyone + acl:mode acl:Read; # has Read-only access + acl:accessTo . # to the public profile +``` + +Note that this is a special case of `acl:agentClass` usage, since it doesn't +point to a Class Listing document that's meant to be de-referenced. + +An application of this feature is to throw a resource open to all logged on users +for a specific amount of time, accumulate the list of those who access it within +that time as a group, and then later restrict access to that group, to prevent spam. + +### Referring to Origins, i.e. Web Apps + + +When a compliant server receives a request from a web application running +in a browser, the browser will send an extra warning HTTP header, the Origin header. + +``` +Origin: https://scripts.example.com:8080 +``` +(For background, see also [Backgrounder on Same Origin Policy and CORS](https://solid.github.io/web-access-control-spec/Background)) +Note that the origin comprises the protocol and the DNS and port but none of the path, +and no trailing slash. +All scripts running on the same origin are assumed to be run by the same +social entity, and so trusted to the same extent. + +*When an Origin header is present then BOTH the authenticated agent AND +the origin MUST be allowed access.* + +As both the user and the web app get to read or write (etc) the data, then they must BOTH +be trusted. This is the algorithm the server must go through. + + - If the requested mode is available to the public, then succeed `200 OK` with added CORS headers ACAO and ACAH. ** + - If the user is *not* logged on, then fail `401 Unauthenticated`. + - If the authenticated user is *not* allowed access, AND the class AuthenticatedAgent is not allowed access, then fail `403 User Unauthorized`. + - If the Origin header is not present, then succeed `200 OK`. + - If the Origin is allowed by the ACL, then succeed `200 OK` with added CORS headers ACAO and ACAH. + - (In future proposed) Look up the owner's webid(s) to check for trusted apps declared there, and if match, succeed `200 OK` with added CORS headers ACAO and ACAH. + - Fail `403 Origin Unauthorized`. + +Note it is a really good idea to make it clear both in the text of the status message and in the body of +the message the difference between the user not being allowed and the web app they are using +not being trusted. + +** Possible future alternative: Set ACAO header to `"*"` indicating that the document is public. This will though block in the browser any access made using credentials. + +#### Adding trusted web apps. + +** NB: this feature was only added recently and is still considered experimental. It's likely to change in the near future. ** + +The authorization of trusted web app is a running battle between readers and writers on the web, and malevolent parties trying to break in to get unauthorized access. The history or Cross-Site Scripting attacks and the introduction of the Same Origin Policy is not detailed here, The CORS specification in general prevents any web app from accessing any data from or associated with a different origin. The web server can get around CORS. It is a pain to to do so, as it involves the server code echoing back the Origin header in the ACAO header, and also it must be done only when the web app in question actually is trustworthy. + +In solid a maxim is, you have complete control of he data. Therefore it is up to the owner of the data, the publisher, the controller of the ACL, or more broadly the person running the solid server, to specify who gets access, be it people or apps. However another maxim is that you can chose which app you use. So of Alice publishes data, and Bob want to use his favorite app, then how does that happen? + + - A Web server MAY be configured such that a given list of origins is unconditionally trusted for incoming HTTP requests. The origin check is then bypassed for these domains, but all other access control mechanisms remain active. + - A specific ACL can be made to allow a given app to access a given file or folder of files, using `acl:origin`. + - Someone with `acl:Control` access to the resource could give in their profile a statement that they will allow users to use a given app. + +``` + <#me> acl:trustedApp [ acl:origin ; + acl:mode acl:Read, + acl:Append]. + <#me> acl:trustedApp [ acl:origin ; + acl:mode acl:Read, + acl:Write, + acl:Control]. +``` + +We define the owners of the resource as people given explicit Control access to it. +(Possible future change: also anyone with Control access, even through a group, as the group can be used as a role) + +For each owner x, the server looks up the (extended?) profile, and looks in it for a +triple of the form + +``` +?x acl:trustedApp ?y. +``` +The set of trust objects is the accumulated set of ?y found in this way. + +For the app ?z to have access, for every mode of access ?m required +there must be some trust object ?y such that +``` +?y acl:origin ?z; + acl:mode ?m. +``` +Note access to different modes may be given in the same or different trust objects. + +## Referring to Resources + +The `acl:accessTo` predicate specifies *which resources* you're giving access +to, using their exact URLs as the objects. + +### Referring to the ACL Resource Itself + +Since an ACL resource is a plain Web document in itself, what controls who +has access to *it*? While an ACL resource *could* in theory have its own +corresponding ACL document (for example, `file1.acl` controls access to `file1`, +and `file1.acl.acl` could potentially control access to `file1.acl`), one +quickly realizes that this recursion has to end somewhere. + +Instead, the [`acl:Control` access mode](#aclcontrol) is used (see below), to +specify who has access to alter (or even view) the ACL resource. + +## Modes of Access + +The `acl:mode` predicate denotes a class of operations that the agents can +perform on a resource. + +##### `acl:Read` +gives access to a class of operations that can be described as "Read +Access". In a typical REST API (such as the one used by +[Solid](https://github.com/solid/solid-spec#https-rest-api)), this includes +access to HTTP verbs `GET`, and `HEAD`. This also includes any kind of +QUERY or SEARCH verbs, if supported. + +##### `acl:Write` +gives access to a class of operations that can modify the resource. In a REST +API context, this would include `PUT`, `POST`, `DELETE` and `PATCH`. This also +includes the ability to perform SPARQL queries that perform updates, if those +are supported. + +##### `acl:Append` +gives a more limited ability to write to a resource -- Append-Only. This +generally includes the HTTP verb `POST`, although some implementations may +also extend this mode to cover non-overwriting `PUT`s, as well as the +`INSERT`-only portion of SPARQL-based `PATCH`es. A typical example of Append +mode usage would be a user's Inbox -- other agents can write (append) +notifications to the inbox, but cannot alter or read existing ones. + +##### `acl:Control` +is a special-case access mode that gives an agent the ability to *view and +modify the ACL of a resource*. Note that it doesn't automatically imply that the +agent has `acl:Read` or `acl:Write` access to the resource itself, just to its +corresponding ACL document. For example, a resource owner may disable their own +Write access (to prevent accidental over-writing of a resource by an app), but +be able to change their access levels at a later point (since they retain +`acl:Control` access). + +## Default (Inherited) Authorizations + +As previously mentioned, not every document needs its own individual ACL +resource and its own authorizations. Instead, one can can create an +Authorization for a container (in the container's own ACL resource), and then +use the `acl:default` predicate to denote that any resource within that +container will *inherit* that authorization. To put it another way, if an +Authorization contains `acl:default`, it will be applied *by default* to +any resource in that container. + +You can override the default inherited authorization for any resource by +creating an individual ACL just for that resource. + +An example ACL for a container would look something like: + +```ttl +# Contents of https://alice.databox.me/docs/.acl +@prefix acl: . + +<#authorization1> + a acl:Authorization; + + # These statements specify access rules for the /docs/ container itself: + acl:agent ; + acl:accessTo ; + acl:mode acl:Read, + acl:Write, + acl:Control; + + # default says: this authorization (the statements above) + # will also be inherited by any resource within that container + # that doesn't have its own ACL. + acl:default . +``` + +## See also + +[Background on CORS](https://solid.github.io/web-access-control-spec/Background) + +## Old discussion of access to group files + +##### Group Listings - Authentication of External Requests + +*This section is not normative* + +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 +external servers? + +For example: Alice sends a GET request to a resource on the server +`https://a.com`. The ACL for that resource links to a group listing on an +external server, `https://b.com`. In the process of resolving the ACL, `a.com` +must send a request to `b.com`, to get that group listing. Note that it's not +Alice herself (or her application) that is sending that request, it's actually +`a.com` sending it (as part of trying to resolve its own ACL). How should +`a.com` authenticate itself? Does it have its own credentials, or does it have +a way to say that it's acting on behalf of Alice? Or both? + +There are several implementation possibilities: + +**No authentication**. The ACL checking engine sends *un-authenticated* requests +to external servers (to fetch group listings). This is the simplest method to +implement, but suffers from the limitation that those external group listings +need to be public-readable. THIS IS THE ONLY METHOD CURRENTLY IN USE + +**WebID-TLS Delegation**. If your implementation uses the WebID-TLS +authentication method, it also needs to implement the ability to delegate its +requests on behalf of the original user. +(No, the original requester may not be allowed access -- you don't have to able to +access a group to be in it) +For a discussion of such a capability, +see the [Extending the WebID Protocol with Access +Delegation](http://bblfish.net/tmp/2012/08/05/WebID_Delegation.pdf) paper. +One thing to keep in mind is - if there are several hops (an ACL request chain +across more than one other domain), how does this change the delegation +confirmation algorithm? If the original server is explicitly authorized for +delegation by the user, what about the subsequent ones? + +**ID Tokens/Bearer Tokens**. If you're using a token-based authentication system +such as OpenID Connect or OAuth2 Bearer Tokens, it will also need to implement +the ability to delegate its ACL requests on behalf of the original user. See +[PoP/RFC7800](https://tools.ietf.org/html/rfc7800) and [Authorization Cross +Domain Code](http://openid.bitbucket.org/draft-acdc-01.html) specs for relevant +examples. + +##### Infinite Request Loops in Group Listings + +Since Group Listings (which are linked to from ACL resources using +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: + +``` +https://a.com https://b.com +------------- GET --------------- +group-listA <------ group-listB.acl + | ^ contains: + | | agentGroup + v GET | +group-listA.acl ------> group-listB + contains: + agentGroup +``` + +The access to `group-listA` is controlled by `group-listA.acl`. So far so good. +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 +`group-listB.acl` (by accident or malice) points back to `group-listA` a request +will be made to access `group-listA` on the original server `https://a.com`, +which would start an infinite cycle. + +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 `agentGroup` links pointing to external servers during ACL +resolution time, and treat those uniformly (as errors, or as automatic "access +denied"). + +**B) Treat Group Listings as special cases**. +This assumes that the server has the ability to parse or query the contents of a +Group Listing document *before* resolving ACL checks -- a design decision that +some implementations may find unworkable. If the ACL checking engine can inspect +the contents of a document and know that it's a Group Listing, it can put in +various safeguards against loops. For example, it could validate ACLs when they +are created, and disallow external Group Listing links, similar to option A +above. Note that even if you wanted to ensure that no `.acl`s are allowed for +Group Listings, and that all such documents would be public-readable, you would +still have to be able to tell Group Listings apart from other documents, which +would imply special-case treatment. + +**C) Create and pass along a tracking/state parameter**. +For each ACL check request beyond the original server, it would be possible to +create a nonce-type tracking parameter and pass it along with each subsequent +request. Servers would then be able to use this parameter to detect loops on +each particular request chain. However, this is a spec-level solution (instead +of an individual implementation level), since all implementations have to play +along for this to work. See issue +[solid/solid#8](https://github.com/solid/solid/issues/8) for further +discussion). + +**D) Ignore this issue and rely on timeouts.** +It's worth noting that if an infinite group ACL loop was created by mistake, +this will soon become apparent since requests for that resource will time out. +If the loop was created by malicious actors, this is comparable to a very +small, low volume DDOS attack, which experienced server operators know how to +guard against. In either case, the consequences are not disastrous. + + +### Other ideas about specifying trusted apps + + - A reader can ask to use a given app, by publishing the fact that she trusts a given app. + + ``` + <#me> acl:trustsForUse [ acl:origin ; + acl:mode acl:Read, + acl:Append]. + <#me> acl:trustsForUse [ acl:origin ; + acl:mode acl:Read, + acl:Write, + acl:Control]. + ``` + +A writer could have also more sophisticated requirements, such as that any app Alice +wants to use must be signed by developer from a given list, and so on. + +Therefore, by pulling the profiles of the reader and/or the writer, and/or the Origin app itself, +the system can be adjusted to allow new apps to be added without bad things happening + + +## Not Supported by Design + +This section describes some features or acl-related terms that are not included +in this spec by design. + +##### Resource Owners +WAC has no formal notion of a resource owner, and no explicit Owner access mode. +For convenience/UI purposes, it may be assumed that Owners are agents that have +Read, Write and Control permissions. + +##### acl:accessToClass +The predicate `acl:accessToClass` is not supported. + +##### Regular Expressions +The use of regular expressions in statements such as `acl:agentClass` is not +supported. diff --git a/README.md b/README.md index 29ae614d..1890fdd9 100644 --- a/README.md +++ b/README.md @@ -1,713 +1,36 @@ # Web Access Control (WAC) [![](https://img.shields.io/badge/project-Solid-7C4DFF.svg?style=flat-square)](https://github.com/solid/solid) -Web Access Control (WAC) specification (as used by the Solid project). It -is based on Tim Berners-Lee's May 2009 proposal, as originally captured, and -subsequently evolved by the community, at -[Web Access Control Wiki](https://www.w3.org/wiki/WebAccessControl). This spec -is a particular subset of the options and extensions described in the wiki. +Web Access Control (WAC) is a decentralized cross-domain access control system +providing a way for Linked Data systems to set authorization conditions on +HTTP resources using the Access Control List (ACL) model. -For use with [LDP](https://www.w3.org/TR/ldp/) (and [LDP -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)). +WAC (as used by the [Solid Project](https://solidproject.org/)) is based on +Tim Berners-Lee's May 2009 proposal, as originally captured, and subsequently +evolved by the community, +at [Web Access Control Wiki](https://www.w3.org/wiki/WebAccessControl). +This spec is a particular subset of the options and extensions described in +the wiki, as well as implementation experience. -**Current Spec version:** `v.0.5.0` (see [CHANGELOG.md](CHANGELOG.md)) +Implementations are strongly encouraged to use existing approaches that +provide an extension of the rules of Linked Data, eg. +[Solid Protocol](https://solidproject.org/TR/protocol), +[LDP](https://www.w3.org/TR/ldp/). -## Table of Contents +## Current version +[Editor’s Draft](https://solid.github.io/web-access-control-spec/) -1. [Overview](#overview) -2. [Access Control List Resources](#access-control-list-resources) - * [Containers and Inherited ACLs](#containers-and-inherited-acls) - * [Individual Resource ACLs](#individual-resource-acls) - * [ACL Resource Location Discovery](#acl-resource-location-discovery) -3. [ACL Inheritance Algorithm](#acl-inheritance-algorithm) -4. [Representation Format](#representation-format) -5. [Example WAC Document](#example-wac-document) -6. [Describing Agents](#describing-agents) - * [Singular Agent](#singular-agent) - * [Groups](#groups-of-agents) - * [Public Access (all Agents)](#public-access-all-agents) - * [Anyone logged on (Authenticated Agents)](#authenticated-agents-anyone-logged-on) - * [Referring to Origins, i.e. Web Apps](#referring-to-origins-ie-web-apps) -7. [Referring to Resources](#referring-to-resources) -8. [Modes of Access](#modes-of-access) -9. [Default (Inherited) Authorizations](#default-inherited-authorizations) -10. [Not Supported by Design](#not-supported-by-design) +## Participation -## Overview +All substantive contributors to any Work Items must be members of the Solid +CG. It’s easy to [join the CG](https://www.w3.org/community/solid/join) if +you’d like to contribute. -Web Access Control (WAC) is a decentralized cross-domain access control system. -The main concepts should be familiar to developers, as they are similar to -access control schemes used in many file systems. It's concerned with giving -access to agents (users, groups and more) to perform various kinds of operations -(read, write, append, etc) on resources. WAC has several key features: +Anyone can join the [chat](https://gitter.im/solid/specification). -1. The resources are identified by URLs, and can refer to any web documents or - resources. -2. It is *declarative* -- access control policies live in regular web documents, - which can be exported/backed easily, using the same mechanism as you would - for backing up the rest of your data. -3. Users and groups are also identified by URLs (specifically, by - [WebIDs](https://github.com/solid/solid-spec#identity)) -4. It is *cross-domain* -- all of its components, such as resources, agent - WebIDs, and even the documents containing the access control policies, can - potentially reside on separate domains. In other words, you can give access - to a resource on one site to users and groups hosted on another site. +## Code of Conduct -## Access Control List Resources - -In a system that uses Web Access Control, each web resource has a set of -*Authorization* statements describing: - -1. Who has access to that resource (that is, who the authorized *agents* are) -2. What types (or *modes*) of access they have - -These Authorizations are either explicitly set for an individual resource, or -(more often) inherited from that resource's parent folder or container. In -either case, the Authorization statements are placed into separate WAC -documents called *Access Control List Resources* (or simply *ACLs*). - -### Containers and Inherited ACLs - -The WAC system assumes that web documents are placed in hierarchical containers -or folders. For convenience, users do not have to specify permissions on each -individual resource -- they can simply set default permissions on a container using a -[`acl:default`](#default-inherited-authorizations) predicate and the exact container URI -as the object, and have all -of the resources in that container [inherit](#acl-inheritance-algorithm) those -permissions. - -### Individual Resource ACLs - -For fine-grained control, users can specify a set of permissions for each -individual resource (which overrides any permissions of its parent container). -See the [Example WAC Document](#example-wac-document) section to get an idea -for what that would look like. - -### ACL Resource Location Discovery - -Given a URL for an individual resource or container, a client can discover the -location of its corresponding ACL by performing a `HEAD` (or a `GET`) request -and parsing the `rel="acl"` link relation. - -Example request to discover the location of the ACL resource for a web document -at `http://example.org/docs/file1` is given below: - -```http -HEAD /docs/file1 HTTP/1.1 -Host: example.org - -HTTP/1.1 200 OK -Link: ; rel="acl" -``` - -The request to discover the location of a container's ACL resource looks -similar: - -```http -HEAD /docs/ HTTP/1.1 -Host: example.org - -HTTP/1.1 200 OK -Link: <.acl>; rel="acl" -``` - -Note that the `acl` link relation uses relative path URLs (the absolute URL of -the ACL resource in the above example would be `/docs/.acl`). - -Clients MUST NOT assume that the location of an ACL resource can be -deterministically derived from a document's URL. For example, given a document -with a URL of `/docs/file1`, clients cannot rely on the assumption that an ACL -resource exists at `/docs/file1.acl`, simply using `.acl` as a suffix. The -actual naming convention for ACL resources can differ for each individual -implementation (or even for each individual server). If one server locates the -ACL resource by appending the suffix `.acl`, another server could place the ACL -resources into a sub-container (locating it at `/docs/.acl/file1.acl` for the -example above). - -## ACL Schemas - -*This section is non-normative.* ( Issue: https://github.com/solid/specification/issues/169 ) - -The following schema excerpts use these namespace prefixes: -``` turtle -PREFIX acl: -PREFIX dc: -PREFIX vcard: -PREFIX xsd: -``` -### Authorization Schema -``` turtle -<#authShape> { - a [acl:Authorization] ; - acl:accessTo IRI ; - acl:mode [acl:Read acl:Write acl:Control]+ ; - ( acl:agent IRI ; - | acl:agentGroup @<#groupShape> + - ) ; -} -``` - -### Group Schema - -``` turtle -<#groupShape> { - a [vcard:Group] ; - vcard:hasUID IRI /^urn:uuid:/ ; - dc:created xsd:dateTime ? ; - dc:modified xsd:dateTime ? ; - vcard:hasMember IRI + ; -} -``` - -## ACL Inheritance Algorithm - -The following algorithm is used by servers to determine which ACL resources -(and hence which set of Authorization statements) apply to any given resource: - -1. Use the document's own ACL resource if it exists (in which case, stop here). -2. Otherwise, look for authorizations to inherit from the ACL of the document's - container. If those are found, stop here. -3. Failing that, check the container's *parent* container to see if *that* has - its own ACL file, and see if there are any permissions to inherit. -4. Failing that, move up the container hierarchy until you find a container - with an existing ACL file, which has some permissions to inherit. -5. The *root container* of a user's account MUST have an ACL resource specified. - (If all else fails, the search stops there.) - -It is considered an anti-pattern for a *client* to perform those steps, however. -A client may [discover](#acl-resource-location-discovery) and load a document's -individual resource (for example, for the purposes of editing its permissions). -If such a resource does not exist, a client SHOULD NOT search for, or interact -with, the inherited ACLs from an upstream container. - -### ACL Inheritance Algorithm Example - -*Note:* The server in the examples below is using the ACL naming convention of -appending `.acl` to resource URLs, for simplicity. As mentioned in the section -on [ACL discovery](#acl-resource-location-discovery), clients should not use -or assume any naming convention. - -A request (to read or write) has arrived for a document located at -`/documents/papers/paper1`. The server does as follows: - -1. First, it checks for the existence of an individual corresponding ACL - resource. (That is, it checks if `paper1.acl` exists.) If this individual ACL - resource exists, the server uses the Authorization statements in that ACL. No - other statements apply. -2. If no individual ACL exists, the server next checks to see if the - `/documents/papers/` container (in which the document resides) has its own - ACL resource (here, `/documents/papers/.acl`). If it finds that, the server - reads each authorization in the container's ACL, and if any of them contain an - `acl:default` predicate, the server will use them (as if they were - specified in `paper1.acl`). Again, if any such authorizations are found, the - process stops there and no other statements apply. -3. If the document's container has no ACL resource of its own, the search - continues upstream, in the *parent* container. The server would check if - `/documents/.acl` exists, and then `/.acl`, until it finds some authorizations - that contain `acl:default`. -4. Since the root container (here, `/`) MUST have its own ACL resource, the - server would use the authorizations there as a last resort. - -See the [Default (Inherited) Authorizations](#default-inherited-authorizations) -section below for an example of what a container's ACL resource might look like. - -## Representation Format - -The permissions in an ACL resource are stored in Linked Data format -([Turtle](http://www.w3.org/TR/turtle/) by default, but also available in other -serializations). - -*Note: A familiarity with Linked Data and -[RDF Concepts](http://www.w3.org/TR/rdf11-concepts/) helps with understanding -the terminology used in this spec.* - -WAC uses the [`http://www.w3.org/ns/auth/acl`](http://www.w3.org/ns/auth/acl) -ontology for its terms. Through the rest of the spec, the prefix `acl:` is -assumed to mean `@prefix acl: .` - -## Example WAC Document - -Below is an example ACL resource that specifies that Alice (as identified by her -WebID `https://alice.databox.me/profile/card#me`) has full access (Read, Write -and Control) to one of her web resources, located at -`https://alice.databox.me/docs/file1`. - -```ttl -# Contents of https://alice.databox.me/docs/file1.acl -@prefix acl: . - -<#authorization1> - a acl:Authorization; - acl:agent ; # Alice's WebID - acl:accessTo ; - acl:mode acl:Read, - acl:Write, - acl:Control. -``` - -## Describing Agents - -In WAC, we use the term *Agent* to identify *who* is allowed access to various -resources. In general, it is assumed to mean "someone or something that can -be referenced with a WebID", which covers users, groups (as well as companies -and organizations), and software agents such as applications or services. - -### Singular Agent - -An authorization may list any number of individual agents (that are being given -access) by using the `acl:agent` predicate, and using their WebID URIs as -objects. The example WAC document in a previous section grants access to Alice, -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:agentGroup` predicate. -The object of an `agentGroup` statement is an instance of `vcard:Group`. -The WebIDs of group members are listed in it, using the -`vcard:hasMember` predicate. If a WebID is listed as member of that group, -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: . - -# Individual authorization - Alice has Read/Write/Control access -<#authorization1> - a acl:Authorization; - acl:accessTo ; - acl:mode acl:Read, - acl:Write, - acl:Control; - acl:agent . - -# Group authorization, giving Read/Write access to two groups, which are -# specified in the 'work-groups' document. -<#authorization2> - a acl:Authorization; - acl:accessTo ; - acl:mode acl:Read, - acl:Write; - acl:agentGroup ; - acl:agentGroup . -``` - -Corresponding `work-groups` Group Listing document: - -```ttl -# Contents of https://alice.example.com/work-groups -@prefix acl: . -@prefix dc: . -@prefix vcard: . -@prefix xsd: . - -<#Accounting> - a vcard:Group; - vcard:hasUID ; - dc:created "2013-09-11T07:18:19Z"^^xsd:dateTime; - dc:modified "2015-08-08T14:45:15Z"^^xsd:dateTime; - - # Accounting group members: - vcard:hasMember ; - vcard:hasMember . - -<#Management> - a vcard:Group; - vcard:hasUID ; - - # Management group members: - vcard:hasMember . -``` -[[test against schema](https://tinyurl.com/whcrhlo)] - -#### Group Listings - Implementation Notes - -When implementing support for `acl:agentGroup` and Group Listings, keep in mind -the following issues: - -1. Group Listings are regular documents (potentially each with its own `.acl`). -2. What authentication mechanism should the ACL checking engine use, when making - requests for Group Listing documents on other servers? -3. Infinite request loops during ACL resolution become possible, if an `.acl` - points to a group listing on a different server. -4. Therefore, for the moment, we suggest that all Group files which are used - for group ACLs are public. - -Possible future methods for a server to find out whether a given agent is a -member of a group are a matter for future research and possible addition here. - -### Public Access (All Agents) - -To specify that you're giving a particular mode of access to *everyone* -(for example, that your WebID Profile is public-readable), you can use -`acl:agentClass foaf:Agent` to denote that you're giving access to the class -of *all* agents (the general public). For example: - -```ttl -@prefix acl: . -@prefix foaf: . - -<#authorization2> - a acl:Authorization; - acl:agentClass foaf:Agent; # everyone - acl:mode acl:Read; # has Read-only access - acl:accessTo . # to the public profile -``` - -### Authenticated Agents (Anyone logged on) - -Authenticated access is a bit like public access -but it is not anonymous. Access is only given to people -who have logged on and provided a specific ID. -This allows the server to track the people who have used the resource. - -To specify that you're giving a particular mode of access to anyone *logged on* -(for example, that your collaborative page is open to anyone but you want to know who they are), -you can use -`acl:agentClass acl:AuthenticatedAgent` to denote that you're giving access to the class -of *all* authenticated agents. For example: - -```ttl -@prefix acl: . -@prefix foaf: . - -<#authorization2> - a acl:Authorization; - acl:agentClass acl:AuthenticatedAgent; # everyone - acl:mode acl:Read; # has Read-only access - acl:accessTo . # to the public profile -``` - -Note that this is a special case of `acl:agentClass` usage, since it doesn't -point to a Class Listing document that's meant to be de-referenced. - -An application of this feature is to throw a resource open to all logged on users -for a specific amount of time, accumulate the list of those who access it within -that time as a group, and then later restrict access to that group, to prevent spam. - -### Referring to Origins, i.e. Web Apps - - -When a compliant server receives a request from a web application running -in a browser, the browser will send an extra warning HTTP header, the Origin header. - -``` -Origin: https://scripts.example.com:8080 -``` -(For background, see also [Backgrounder on Same Origin Policy and CORS](https://solid.github.io/web-access-control-spec/Background)) -Note that the origin comprises the protocol and the DNS and port but none of the path, -and no trailing slash. -All scripts running on the same origin are assumed to be run by the same -social entity, and so trusted to the same extent. - -*When an Origin header is present then BOTH the authenticated agent AND -the origin MUST be allowed access.* - -As both the user and the web app get to read or write (etc) the data, then they must BOTH -be trusted. This is the algorithm the server must go through. - - - If the requested mode is available to the public, then succeed `200 OK` with added CORS headers ACAO and ACAH. ** - - If the user is *not* logged on, then fail `401 Unauthenticated`. - - If the authenticated user is *not* allowed access, AND the class AuthenticatedAgent is not allowed access, then fail `403 User Unauthorized`. - - If the Origin header is not present, then succeed `200 OK`. - - If the Origin is allowed by the ACL, then succeed `200 OK` with added CORS headers ACAO and ACAH. - - (In future proposed) Look up the owner's webid(s) to check for trusted apps declared there, and if match, succeed `200 OK` with added CORS headers ACAO and ACAH. - - Fail `403 Origin Unauthorized`. - -Note it is a really good idea to make it clear both in the text of the status message and in the body of -the message the difference between the user not being allowed and the web app they are using -not being trusted. - -** Possible future alternative: Set ACAO header to `"*"` indicating that the document is public. This will though block in the browser any access made using credentials. - -#### Adding trusted web apps. - -** NB: this feature was only added recently and is still considered experimental. It's likely to change in the near future. ** - -The authorization of trusted web app is a running battle between readers and writers on the web, and malevolent parties trying to break in to get unauthorized access. The history or Cross-Site Scripting attacks and the introduction of the Same Origin Policy is not detailed here, The CORS specification in general prevents any web app from accessing any data from or associated with a different origin. The web server can get around CORS. It is a pain to to do so, as it involves the server code echoing back the Origin header in the ACAO header, and also it must be done only when the web app in question actually is trustworthy. - -In solid a maxim is, you have complete control of he data. Therefore it is up to the owner of the data, the publisher, the controller of the ACL, or more broadly the person running the solid server, to specify who gets access, be it people or apps. However another maxim is that you can chose which app you use. So of Alice publishes data, and Bob want to use his favorite app, then how does that happen? - - - A Web server MAY be configured such that a given list of origins is unconditionally trusted for incoming HTTP requests. The origin check is then bypassed for these domains, but all other access control mechanisms remain active. - - A specific ACL can be made to allow a given app to access a given file or folder of files, using `acl:origin`. - - Someone with `acl:Control` access to the resource could give in their profile a statement that they will allow users to use a given app. - -``` - <#me> acl:trustedApp [ acl:origin ; - acl:mode acl:Read, - acl:Append]. - <#me> acl:trustedApp [ acl:origin ; - acl:mode acl:Read, - acl:Write, - acl:Control]. -``` - -We define the owners of the resource as people given explicit Control access to it. -(Possible future change: also anyone with Control access, even through a group, as the group can be used as a role) - -For each owner x, the server looks up the (extended?) profile, and looks in it for a -triple of the form - -``` -?x acl:trustedApp ?y. -``` -The set of trust objects is the accumulated set of ?y found in this way. - -For the app ?z to have access, for every mode of access ?m required -there must be some trust object ?y such that -``` -?y acl:origin ?z; - acl:mode ?m. -``` -Note access to different modes may be given in the same or different trust objects. - -## Referring to Resources - -The `acl:accessTo` predicate specifies *which resources* you're giving access -to, using their exact URLs as the objects. - -### Referring to the ACL Resource Itself - -Since an ACL resource is a plain Web document in itself, what controls who -has access to *it*? While an ACL resource *could* in theory have its own -corresponding ACL document (for example, `file1.acl` controls access to `file1`, -and `file1.acl.acl` could potentially control access to `file1.acl`), one -quickly realizes that this recursion has to end somewhere. - -Instead, the [`acl:Control` access mode](#aclcontrol) is used (see below), to -specify who has access to alter (or even view) the ACL resource. - -## Modes of Access - -The `acl:mode` predicate denotes a class of operations that the agents can -perform on a resource. - -##### `acl:Read` -gives access to a class of operations that can be described as "Read -Access". In a typical REST API (such as the one used by -[Solid](https://github.com/solid/solid-spec#https-rest-api)), this includes -access to HTTP verbs `GET`, and `HEAD`. This also includes any kind of -QUERY or SEARCH verbs, if supported. - -##### `acl:Write` -gives access to a class of operations that can modify the resource. In a REST -API context, this would include `PUT`, `POST`, `DELETE` and `PATCH`. This also -includes the ability to perform SPARQL queries that perform updates, if those -are supported. - -##### `acl:Append` -gives a more limited ability to write to a resource -- Append-Only. This -generally includes the HTTP verb `POST`, although some implementations may -also extend this mode to cover non-overwriting `PUT`s, as well as the -`INSERT`-only portion of SPARQL-based `PATCH`es. A typical example of Append -mode usage would be a user's Inbox -- other agents can write (append) -notifications to the inbox, but cannot alter or read existing ones. - -##### `acl:Control` -is a special-case access mode that gives an agent the ability to *view and -modify the ACL of a resource*. Note that it doesn't automatically imply that the -agent has `acl:Read` or `acl:Write` access to the resource itself, just to its -corresponding ACL document. For example, a resource owner may disable their own -Write access (to prevent accidental over-writing of a resource by an app), but -be able to change their access levels at a later point (since they retain -`acl:Control` access). - -## Default (Inherited) Authorizations - -As previously mentioned, not every document needs its own individual ACL -resource and its own authorizations. Instead, one can can create an -Authorization for a container (in the container's own ACL resource), and then -use the `acl:default` predicate to denote that any resource within that -container will *inherit* that authorization. To put it another way, if an -Authorization contains `acl:default`, it will be applied *by default* to -any resource in that container. - -You can override the default inherited authorization for any resource by -creating an individual ACL just for that resource. - -An example ACL for a container would look something like: - -```ttl -# Contents of https://alice.databox.me/docs/.acl -@prefix acl: . - -<#authorization1> - a acl:Authorization; - - # These statements specify access rules for the /docs/ container itself: - acl:agent ; - acl:accessTo ; - acl:mode acl:Read, - acl:Write, - acl:Control; - - # default says: this authorization (the statements above) - # will also be inherited by any resource within that container - # that doesn't have its own ACL. - acl:default . -``` - -## See also - -[Background on CORS](https://solid.github.io/web-access-control-spec/Background) - -## Old discussion of access to group files - -##### Group Listings - Authentication of External Requests - -*This section is not normative* - -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 -external servers? - -For example: Alice sends a GET request to a resource on the server -`https://a.com`. The ACL for that resource links to a group listing on an -external server, `https://b.com`. In the process of resolving the ACL, `a.com` -must send a request to `b.com`, to get that group listing. Note that it's not -Alice herself (or her application) that is sending that request, it's actually -`a.com` sending it (as part of trying to resolve its own ACL). How should -`a.com` authenticate itself? Does it have its own credentials, or does it have -a way to say that it's acting on behalf of Alice? Or both? - -There are several implementation possibilities: - -**No authentication**. The ACL checking engine sends *un-authenticated* requests -to external servers (to fetch group listings). This is the simplest method to -implement, but suffers from the limitation that those external group listings -need to be public-readable. THIS IS THE ONLY METHOD CURRENTLY IN USE - -**WebID-TLS Delegation**. If your implementation uses the WebID-TLS -authentication method, it also needs to implement the ability to delegate its -requests on behalf of the original user. -(No, the original requester may not be allowed access -- you don't have to able to -access a group to be in it) -For a discussion of such a capability, -see the [Extending the WebID Protocol with Access -Delegation](http://bblfish.net/tmp/2012/08/05/WebID_Delegation.pdf) paper. -One thing to keep in mind is - if there are several hops (an ACL request chain -across more than one other domain), how does this change the delegation -confirmation algorithm? If the original server is explicitly authorized for -delegation by the user, what about the subsequent ones? - -**ID Tokens/Bearer Tokens**. If you're using a token-based authentication system -such as OpenID Connect or OAuth2 Bearer Tokens, it will also need to implement -the ability to delegate its ACL requests on behalf of the original user. See -[PoP/RFC7800](https://tools.ietf.org/html/rfc7800) and [Authorization Cross -Domain Code](http://openid.bitbucket.org/draft-acdc-01.html) specs for relevant -examples. - -##### Infinite Request Loops in Group Listings - -Since Group Listings (which are linked to from ACL resources using -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: - -``` -https://a.com https://b.com -------------- GET --------------- -group-listA <------ group-listB.acl - | ^ contains: - | | agentGroup - v GET | -group-listA.acl ------> group-listB - contains: - agentGroup -``` - -The access to `group-listA` is controlled by `group-listA.acl`. So far so good. -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 -`group-listB.acl` (by accident or malice) points back to `group-listA` a request -will be made to access `group-listA` on the original server `https://a.com`, -which would start an infinite cycle. - -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 `agentGroup` links pointing to external servers during ACL -resolution time, and treat those uniformly (as errors, or as automatic "access -denied"). - -**B) Treat Group Listings as special cases**. -This assumes that the server has the ability to parse or query the contents of a -Group Listing document *before* resolving ACL checks -- a design decision that -some implementations may find unworkable. If the ACL checking engine can inspect -the contents of a document and know that it's a Group Listing, it can put in -various safeguards against loops. For example, it could validate ACLs when they -are created, and disallow external Group Listing links, similar to option A -above. Note that even if you wanted to ensure that no `.acl`s are allowed for -Group Listings, and that all such documents would be public-readable, you would -still have to be able to tell Group Listings apart from other documents, which -would imply special-case treatment. - -**C) Create and pass along a tracking/state parameter**. -For each ACL check request beyond the original server, it would be possible to -create a nonce-type tracking parameter and pass it along with each subsequent -request. Servers would then be able to use this parameter to detect loops on -each particular request chain. However, this is a spec-level solution (instead -of an individual implementation level), since all implementations have to play -along for this to work. See issue -[solid/solid#8](https://github.com/solid/solid/issues/8) for further -discussion). - -**D) Ignore this issue and rely on timeouts.** -It's worth noting that if an infinite group ACL loop was created by mistake, -this will soon become apparent since requests for that resource will time out. -If the loop was created by malicious actors, this is comparable to a very -small, low volume DDOS attack, which experienced server operators know how to -guard against. In either case, the consequences are not disastrous. - - -### Other ideas about specifying trusted apps - - - A reader can ask to use a given app, by publishing the fact that she trusts a given app. - - ``` - <#me> acl:trustsForUse [ acl:origin ; - acl:mode acl:Read, - acl:Append]. - <#me> acl:trustsForUse [ acl:origin ; - acl:mode acl:Read, - acl:Write, - acl:Control]. - ``` - -A writer could have also more sophisticated requirements, such as that any app Alice -wants to use must be signed by developer from a given list, and so on. - -Therefore, by pulling the profiles of the reader and/or the writer, and/or the Origin app itself, -the system can be adjusted to allow new apps to be added without bad things happening - - -## Not Supported by Design - -This section describes some features or acl-related terms that are not included -in this spec by design. - -##### Resource Owners -WAC has no formal notion of a resource owner, and no explicit Owner access mode. -For convenience/UI purposes, it may be assumed that Owners are agents that have -Read, Write and Control permissions. - -##### acl:accessToClass -The predicate `acl:accessToClass` is not supported. - -##### Regular Expressions -The use of regular expressions in statements such as `acl:agentClass` is not -supported. +All work and communication within the Solid CG is covered by the +[Solid Code of Conduct](https://github.com/solid/process/blob/master/code-of-conduct.md) +as well as the +[Positive Work Environment at W3C: Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc/). diff --git a/index.html b/index.html new file mode 100644 index 00000000..91edce68 --- /dev/null +++ b/index.html @@ -0,0 +1,1227 @@ + + + + + Web Access Control + + + + + + + + +
+
+ +
+
+ +
+
+

Web Access Control

+

Editor’s Draft, 2021-06-30

+ +
+
This version
+
https://solid.github.io/web-access-control-spec/
+
+ +
+
Latest version
+
https://solid.github.io/web-access-control-spec/
+
+ +
+
+
Editors
+
Sarven Capadisli
+
+
+ +
+
Published
+
+
+ +
+
Modified
+
+
+ +
+
Repository
+
GitHub
+
Issues
+
+ +
+
Derived From
+
+ +
+
+ +
+
Language
+
English
+
+ +
+
License
+
MIT License
+
+ +
+
Notifications Inbox
+
https://specs.solidcommunity.net/inbox/wac/
+
+ +
+
Document Status
+
Editor’s Draft
+
+ +
+
In Reply To
+
Solid Origin
+
+ +
+
Policy
+
+
+
Rule
+
Offer
+
Unique Identifier
+
https://solid.github.io/web-access-control-spec/#document-policy-offer
+
Target
+
https://solid.github.io/web-access-control-spec/
+
Permission
+
+
+
Assigner
+
W3C Solid Community Group
+
Action
+
+ +
+
+
+
+
+
+ +

Copyright © 2021 W3C Solid Community Group.

+ +
+
+

Abstract

+
+

Web Access Control (WAC) is a decentralized cross-domain access control system providing a way for Linked Data systems to set authorization conditions on HTTP resources using the Access Control List (ACL) model.

+
+
+ +
+

Status of This Document

+
+

This section describes the status of this document at the time of its publication.

+ +

This document was published by the Solid Community Group as an Editor’s Draft. The sections that have been incorporated have been reviewed following the Solid process. However, the information in this document is still subject to change. You are invited to contribute any feedback, comments, or questions you might have.

+ +

Publication as an Editor’s Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

+ +

This document was produced by a group operating under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

+
+
+ + + +
+

Introduction

+
+

This section is non-normative.

+ +

Unauthorized access or modification of Web resources could lead to unintended loss, damage or disclosure of data. To support read-write operations within the framework of HTTP, mechanisms for expressing and application of authorization conditions are needed to meet the social requirements of decentralised applications.

+ +

Web Access Control (WAC) is a decentralized cross-domain access control system providing a way for Linked Data systems to set authorization conditions on HTTP resources using the Access Control List (ACL) model.

+ +

The WAC specification describes how to enable applications to discover Authorizations associated with a given resource, and to control such policies, as directed by an agent. Server manages the association between a resource and an ACL resource, and applies the authorization conditions on requested operations. Authorizations are described using the ACL ontology to express and determine access privileges of a requested resource. Any kind of access can be given to a resource as per the ACL ontology. This specification uses the access modes currently defined by the ACL ontology, such as the class of operations to read, write, append and control resources. An Authorization may allow public access to resources or place the requirement for authenticated agents. Resources and agents can be on different origins.

+ +
+

Note: Specification Orthogonality

+
+

This specification does not specify mechanisms for authentication or methods to verify assertions. It is assumed that systems using WAC have the ability to apply authentication and verification techniques when desired.

+
+
+ +

The access control system can be enhanced by adding more inference or expressivity to express social constraints. See the Extensions section.

+ +

This specification is for:

+ + + +
+

Terminology

+
+

This section is non-normative.

+ +

The WAC specification defines the following terms. These terms are referenced throughout this specification.

+ + + +
+
URI
+
A Uniform Resource Identifier (URI) provides the means for identifying resources [RFC3986].
+ +
resource
+
A resource is the target of an HTTP request identified by a URI [RFC7231].
+ +
container resource
+
A container resource is a hierarchical collection of resources that contains other resources, including containers.
+ +
root container
+
A root container is a container resource that is at the highest level of the collection hierarchy.
+ +
ACL resource
+
An ACL resource is represented by an RDF document [RDF11-CONCEPTS] that includes Authorizations determining access to resources.
+ +
Authorization
+
An Authorization is an abstract thing which is identified by a URI and whose properties are defined in an ACL resource, e.g., access modes granted to agents the ability to perform operations on resources.
+ +
access mode
+
An access mode is a class of operations that can be performed on one or more resources.
+ +
agent
+
An agent is a person, social entity or software identified by a URI, e.g., a WebID denotes an agent [WEBID].
+ +
agent group
+
An agent group is a group of persons or entities identified by a URI.
+ +
agent class
+
An agent class is a class of persons or entities identified by a URI.
+ +
origin
+
An origin indicates where an HTTP request originates from [RFC6454].
+
+ +

In addition to the terminology above, this specification also uses terminology from the [INFRA] specification. When INFRA terminology is used, such as string and boolean, it is linked directly to that specification.

+
+
+ +
+

Namespaces

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Prefixes and Namespaces
PrefixNamespaceDescription
rdfhttp://www.w3.org/1999/02/22-rdf-syntax-ns#[RDF-SCHEMA]
aclhttp://www.w3.org/ns/auth/acl#ACL ontology
foafhttp://xmlns.com/foaf/0.1/[FOAF]
vcardhttp://www.w3.org/2006/vcard/ns#[VCARD-RDF]
+
+
+ +
+

Conformance

+
+

All assertions, diagrams, examples, and notes are non-normative, as are all sections explicitly marked non-normative. Everything else is normative.

+ +

The key words “MUST” and “MUST NOT” are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

+
+
+
+
+ +
+

HTTP Interactions

+
+

This section is non-normative.

+ +

Clients who want to perform read-write operations on ACL resources with respect to Authorizations which are stored on a server can do so within the framework of HTTP. This specification does not describe the HTTP interaction to read-write resources. It is assumed that servers have a mapping to handle HTTP requests and the required Authorizations to grant operations on resources. Implementations are strongly encouraged to use existing approaches that provide an extension of the rules of Linked Data, e.g., [SOLID-PROTOCOL], [LDP].

+
+
+ +
+

ACL Resources

+
+

This section describes ACL resource discovery and representation.

+ +
+

ACL Resource Discovery

+
+ + +

ACL Resource Discovery is used towards determining the Effective ACL Resource of a resource.

+ + + +

Servers MUST NOT directly associate more than one ACL resource to a resource.

+ + + +
+

Note: ACL Resource URI Security

+
+

The URI of an ACL resource does not in itself pose a security threat ([RFC3986] security considerations). This specification does not constrain the discoverability of ACL resources.

+
+
+ +
+

Note: URI Origin

+
+

The resource and the associated ACL resource can be on different origins [RFC6454].

+
+
+ +

Clients MUST NOT derive the URI of the ACL resource through string operations on the URI of the resource.

+ +

Source: issues/8, issues/62, issues/131, issues/176

+
+
+ +
+

ACL Resource Representation

+
+

An ACL resource is an RDF document [RDF11-CONCEPTS] that can hold any information, typically comprises an unordered set of Authorizations, any of which could permit an attempted access.

+ +

Servers MUST accept an HTTP GET and HEAD request targeting an ACL resource when the value of the Accept header requests a representation in text/turtle [TURTLE].

+ +

Servers who want a resource to inherit Authorizations (Effective ACL Resource) from a container resource MUST NOT initialise the ACL resource that is associated with the resource with a representation.

+ +

When an authorized HTTP GET or HEAD request targets an ACL resource without an existing representation, the server MUST respond with the 404 status code as per [RFC7231].

+ +

The root container MUST have an ACL resource with a representation.

+ +

The ACL resource of the root container MUST include an Authorization allowing the acl:Control access privilege (acl:Control access mode).

+ +

Source: issues/45

+
+
+
+
+ +
+

Authorization Rule

+
+

Authorization (instance of acl:Authorization) is the most fundamental unit of access control describing access permissions granting to agents the ability to perform operations on resources. Authorizations are described with RDF statements and may express any information. This section describes the following characteristics of an Authorization: access objects to specify what can be accessed, access modes to specify permissions, and access subjects to specify who can access the objects. See the Authorization Conformance section for applicable Authorizations towards Authorization Evaluation.

+ +
+

Access Objects

+
+

The acl:accessTo predicate denotes the resource to which access is being granted.

+ +

The acl:default predicate denotes the container resource whose Authorization can be applied to a resource lower in the collection hierarchy.

+ +

Inheriting Authorizations from the most significant container’s ACL resource is useful to avoid individually managing an ACL resource for each resource, as well as to define access control for resources that do not exist yet.

+ +

Source: issues/59

+
+
+ +
+

Access Modes

+
+

The access modes described in this section are defined in the ACL ontology, such as the class of operations to read, write, append and control resources. The requirements for new access modes is explained in the Access Mode Extensions section.

+ +

The acl:mode predicate denotes a class of operations that the agents can perform on a resource.

+ +
+
acl:Read
+
Allows access to a class of read operations on a resource, e.g., to view the contents of a resource on HTTP GET requests.
+ +
acl:Write
+
Allows access to a class of write operations on a resource, e.g., to create, delete or modify resources on HTTP PUT, POST, PATCH, DELETE requests.
+ +
acl:Append
+
Allows access to a class of append operations on a resource, e.g., to add information, but not remove, information on HTTP POST, PATCH requests.
+ +
acl:Control
+
Allows access to a class of read and write operations on an ACL resource associated with a resource.
+
+ +
+

Note: Access Mode Classes

+
+

acl:Access is a superclass where specific access modes (entailing a class of operations) can be subclassed. It is not intended to be used for setting or matching access privileges.

+ +

acl:Append is a subclass of acl:Write.

+
+
+ +
+

Note: URI Ownership

+
+

URI ownership, as per Architecture of the World Wide Web [WEBARCH], is outside the scope of this specification, and thus cannot be changed by modifying Authorizations.

+
+
+ +
+

Note: Loss of Control Mitigation

+
+

It is assumed that systems using WAC have mechanisms to mitigate loss of control of the resources, such as by ensuring valid ACL resources and Authorizations, by providing administrative functions on the storage, or by implicitly granting control over all resources in a storage to owners.

+ +

Source: issues/67, issues/153, pull/264

+
+
+ +

Source: issues/33

+
+
+ +
+

Access Subjects

+
+

The ability of a subject to access a resource can be granted to identifiable agents, a class of agents, a group of agents, or an origin.

+ +

The acl:agent predicate denotes an agent being given the access permission.

+ +

The acl:agentClass predicate denotes a class of agents being given the access permission.

+ +

Two agent classes are defined here:

+ +
+
foaf:Agent
+
Allows access to any agent, i.e., the public.
+
acl:AuthenticatedAgent
+
Allows access to any authenticated agent.
+
+ +

The acl:agentGroup predicate denotes a group of agents being given the access permission. The object of an acl:agentGroup statement is an instance of vcard:Group, where the members of the group are specified with the vcard:hasMember predicate.

+ +

The acl:origin predicate denotes the origin of an HTTP request that is being given the access permission.

+ +
+

Note: Subject Verification

+
+

Servers may accept different authentication protocols as well as credential verification methods.

+
+
+ +
+

Note: Origin Considerations

+
+

Typical Web browsers use origin based security. While it has many limitations, it is however ubiquitous.

+
+
+ +
+

Issue: Client Identification

+
+

Distinguishing social entities and clients: issues/81.

+
+
+ +

Source: issues/34, issues/32, issues/59

+
+
+
+
+ +
+

Authorization Process

+
+

This section describes how implementations can determine the effective ACL resource of a resource and hence which set of conforming authorizations to use.

+ +

Servers process access requests by evaluating the Authorizations associated with referenced resources in order to determine whether the necessary access permissions are granted for a particular request.

+ +
+

Effective ACL Resource

+
+

Servers enforce the effective ACL resource of a resource, whereas clients determine the effective ACL resource of a resource to perform control operations.

+ +

When an ACL resource associated with a resource has a representation (ACL Resource Representation), it is the effective ACL resource of the requested resource.

+ +

When an ACL resource associated with a resource does not have a representation (ACL Resource Representation), no Authorizations can be immediately checked against the requested resource. In this case, a container resource’s ACL resource may apply on every access to a member resource, in specifying Authorizations for the requested resource.

+ +

WAC has the property of being recursive with respect to container hierarchy, meaning that a member resource inherits Authorizations from the closest container resource (heading towards the root container).

+ +

To determine the effective ACL resource of a resource, perform the following steps. Returns string (the URI of an ACL Resource).

+ +
    +
  1. Let resource be the resource.
    2. +
  2. Let aclResource be the ACL resource of resource.
    3. +
  3. If resource has an associated aclResource with a representation, return aclResource.
    4. +
  4. Otherwise, repeat the steps using the container resource of resource.
    5. +
+ +
+

Note: Effective ACL Resource Alternatives

+
+

This specification does not constrain alternative methods to determine the effective ACL resource of a resource.

+
+
+ +

Source: issues/55, issues/106, issues/130, issues/257, issues/251

+
+
+ +
+

Authorization Conformance

+
+

An applicable Authorization has the following properties:

+ +
    +
  • At least one rdf:type property whose object is acl:Authorization.
    • +
  • At least one acl:accessTo or acl:default property value (Access Objects).
    • +
  • At least one acl:mode property value (Access Modes).
    • +
  • At least one acl:agent, acl:agentGroup, acl:agentClass or acl:origin property value (Access Subjects).
    • +
+ +

Source: issues/56, issues/57, issues/169, issues/186, issues/193, issues/17, issues/18, issues/38, issues/68, issues/78, issues/145

+
+
+ +
+

Authorization Evaluation

+
+

The evaluation of an authorization is concerned with finding Authorizations that match the required parameters of an operation (Authorization Conformance). Evaluation stops when all access permission requests have been granted by one or more Authorizations. Authorizations that do not match a required access permission have no effect on the outcome of the evaluation. Access is granted when conforming Authorizations are matched, otherwise access is denied.

+ +

As per determining the Effective ACL Resource of a resource, an Authorization can be evaluated explicitly (via acl:accessTo) or inherited (via acl:default) against a particular request.

+ +

When a request requires an access mode (acl:mode) which is a limitation of another access mode, then access is granted if either mode is allowed by an Authorization. For example, when a request requires acl:Append, then access will be granted to agents having acl:Write.

+ +

The presence of the acl:origin property and its value is taken into account in the evaluation only when the HTTP request includes the Origin header (Web Origin Authorization).

+ +
+

Reading and Writing Resources

+
+

Working alongside HTTP Interactions, WAC enables a standard set of operations which can be applied to different resource types for a given request based on the set of access modes which control those operations:

+ +

Generally: read operations attempt to confirm the existence of a resource or to view the contents of a resource; write operations attempt to create, delete, or modify resources; append operations attempt to create resources or add information to existing resources; and control operations attempt to view, create, delete, or modify ACL resources.

+ +

As container resources and member resources are hierarchically organised, requests to perform operations on resources are in the context of the applicable container (Effective ACL Resource).

+ +

When an operation requests to read a resource, the server MUST match an Authorization allowing the acl:Read access privilege on the resource.

+ +

When an operation requests to create a resource as a member of a container resource, the server MUST match an Authorization allowing the acl:Append or acl:Write access privilege on the container for new members.

+ +

When an operation requests to update a resource, the server MUST match an Authorization allowing the acl:Append or acl:Write access privilege on the resource.

+ +

When an operation requests to delete a resource, the server MUST match Authorizations allowing the acl:Write access privilege on the resource and the containing container.

+ +
+
Note: Container Permissions
+
+

When a server supports the creation of intermediate containers in the process of creating a resource, the server must match Authorization policies allowing acl:Write on each container.

+ +

When a server supports the recursive deletion of a container, the server must match Authorization policies allowing acl:Write on each member resource.

+
+
+ +
+
Note: Reinstated Resource Permissions
+
+

Implementations may perform cleanup tasks such as deleting the ACL resource that is associated with a resource when the resource is deleted. As deleted resources may be replaced by new resources with the same URI, access permissions on the new resource may differ when the Effective ACL Resource is determined.

+
+
+ +

When an operation requests to read and write an ACL resource, the server MUST match an Authorization allowing the acl:Control access privilege on the resource.

+ +
+
Note: HTTP Method and Access Mode Mapping
+
+

When the target of the HTTP request is the ACL resource, the operation can only be allowed with the acl:Control access mode.

+ +

Having acl:Control does not imply that the agent has acl:Read or acl:Write access to the resource itself, just to its corresponding ACL resource. For example, an agent with control access may disable their own write access (to prevent accidental over-writing of a resource by an application), but be able to change their access levels at a later point (since they retain acl:Control access).

+ +

The HTTP GET method request targeting a resource can only be allowed with the acl:Read access mode.

+ +

The HTTP POST can be used to create a new resource in a container or add information to existing resources (but not remove resources or its contents) with either acl:Append or acl:Write.

+ +

As the HTTP PUT method requests to create or replace the resource state, the acl:Write access mode would be required.

+ +

As the processing of HTTP PATCH method requests depends on the request semantics and content, acl:Append can allow requests using SPARQL 1.1 Update’s [SPARQL11-UPDATE] INSERT DATA operation but not DELETE DATA, whereas acl:Write would allow both operations.

+ +

As the HTTP DELETE method requests to remove a resource, the acl:Write access mode would be required.

+
+
+ +

Source: issues/47, issues/132, issues/197, issues/246

+
+
+ +
+

Web Origin Authorization

+
+

User agents include the HTTP Origin header field to isolate different origins and permit controlled communication between origins. The Origin header warns the server that a possibly untrusted Web application is being used.

+ +

When an HTTP request includes the Origin header, the requested operation is granted on the target resource when there is a match for:

+ +
    +
  • an Authorization allowing access to the requesting agent (acl:agent, acl:agentGroup, acl:agentClass);
    • +
  • an Authorization with an acl:origin property value that of Origin’s field-value, when the required access mode is not available to all agents (acl:agentClass foaf:Agent); and
    • +
  • the required access mode is allowed for the requesting agent and the origin.
    • +
+ +

When a server participates in the CORS protocol [FETCH] and authorization is granted to an HTTP request including the Origin header, the server MUST include the HTTP Access-Control-Allow-Origin and Access-Control-Allow-Headers headers in the response of the HTTP request.

+ +
+
Note: Access Subject and Origin Rejection Reason
+
+

Implementations are encouraged to describe reasons to reject the request in the HTTP response the difference between the access subject not being allowed and the origin associated with the HTTP request not being granted access.

+
+
+ +
+
Note: Trusted Origins
+
+

Implementations might implicitly allow a list of origins, such as the same-origin [RFC6454].

+
+
+
+
+ +
+

Authorization Matching

+
+

This section is non-normative.

+ +

This specification does not impose a storage system that can be used to store Authorizations. Similarly, mechanisms that can be used to find required RDF statements of Authorizations is deliberately unspecified to allow for a wide variety of use. This section exemplifies access check via SPARQL 1.1 Query Language’s [SPARQL11-QUERY] ASK form to test whether or not an Authorization pattern matches; returns boolean.

+ +

The ASK queries below exemplify atomic graph patterns that can be executed against the default graph of an RDF dataset using named graphs for resources. The examples use query variables marked with "?" to indicate any value, and "$" to indicate inputs passed to the query, e.g., <http://example.org/.acl> as the IRI reference of the effective ACL resource of a request replaces $aclResource in the query, and likewise, acl:Write as input is intended to replace $mode in the examples.

+ +
+

Example: Match an Authorization with a specific resource, agent and access mode.

+ 
PREFIX acl: <http://www.w3.org/ns/auth/acl#>
+PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+PREFIX vcard: <http://www.w3.org/2006/vcard/ns#>
+
+ASK {
+  GRAPH $aclResource {
+    ?authorization
+      a acl:Authorization ;
+      acl:accessTo $resource ;
+      acl:agent $agent ;
+      acl:mode $mode .
+  }
+}
+
ASK query matching an Authorization given inputs resource, agent and mode.
+
+ +

From here on, PREFIXs in the query are assumed to be present.

+ +

The following query is typically used in context of inheriting Authorizations (acl:default) from a container’s ACL resource. The query also demonstrates matching Authorizations that use a superclass of the required access mode (Access Mode Classes):

+ +
+

Example: Match an Authorization with a specific container resource, agent class membership and access mode.

+ 
ASK {
+  GRAPH $aclResource {
+    {
+      ?authorization
+        a acl:Authorization ;
+        acl:default $containerResource ;
+        acl:agentClass $agentClass ;
+        acl:mode $requiredMode .
+    }
+    UNION
+    {
+      ?authorization
+        a acl:Authorization ;
+        acl:default $containerResource ;
+        acl:agentClass $agentClass ;
+        acl:mode ?mode .
+      GRAPH $aclOntologyResource {
+        $requiredMode rdfs:subClassOf+ ?mode .
+      }
+    }
+  }
+}
+
ASK query matching an Authorization given inputs containerResource, agentClass and requiredMode (which may be a subclass of another access mode).
+
+ +

The following query can be used to check if an agent is a member of any group that can access a resource:

+ +
+

Example: Match an Authorization with a specific resource, agent with any group membership, and specific access mode.

+ 
ASK {
+  GRAPH $aclResource {
+    ?authorization
+      a acl:Authorization ;
+      acl:accessTo $resource ;
+      acl:agentGroup ?agentGroup ;
+      acl:mode $mode .
+  }
+  GRAPH ?groupResource {
+    ?agentGroup vcard:hasMember $agent .
+  }
+}
+
ASK query matching an Authorization given inputs resource, agent and mode (which may be a subclass of another access mode).
+
+
+
+ +
+

Access Privileges

+
+

Servers MUST advertise client’s access privileges on a resource by including the WAC-Allow HTTP header (WAC-Allow) in the response of HTTP GET and HEAD requests.

+ +

Clients can discover access privileges on a resource by making an HTTP GET or HEAD request on the target resource, and checking the WAC-Allow header value for access parameters listing the allowed access modes per permission group (WAC-Allow).

+ +

When a server participates in the CORS protocol [FETCH], the server MUST include WAC-Allow in the Access-Control-Expose-Headers field-value in the HTTP response.

+
+
+
+
+
+
+ +
+

HTTP Definitions

+
+
+

wac-allow HTTP Header

+
+

The syntax for the WAC-Allow header, using the ABNF syntax defined in Section 1.2 of [RFC7231], is:

+ + 
wac-allow        = "WAC-Allow" ":" OWS #access-param OWS
+access-param     = permission-group OWS "=" OWS access-modes
+permission-group = 1*ALPHA
+access-modes     = DQUOTE OWS *1(access-mode *(RWS access-mode)) OWS DQUOTE
+access-mode      = "read" / "write" / "append" / "control"
+ +

The WAC-Allow HTTP header’s field-value is a comma-separated list of access-params. access-param is a whitespace-separated list of access-modes granted to a permission-group.

+ +
+

Issue: WAC-Allow Access Modes

+
+

Allow any access mode issues/82.

+
+
+ +

This specification defines the following permission-groups:

+ +
+
user
+
Permissions granted to the agent requesting the resource.
+
public
+
Permissions granted to the public.
+
+ +

access-mode corresponds to the Access Modes as defined in the ACL ontology (acl:Read, acl:Write, acl:Append, acl:Control).

+ +

Client parsing algorithms for WAC-Allow header field-values should incorporate error handling. When the received message fails to match an allowed pattern, clients MUST ignore the received WAC-Allow header-field. When unrecognised access parameters (such as permission groups or access modes) are found, clients MUST continue processing the access parameters as if those properties were not present.

+ +

Source: issues/171, issues/170, issues/181, 60101295d8bdab47395e6775, pull/210

+
+
+ + +
+
+ +
+

Extensions

+
+

Extensions incorporate additional features beyond what is defined in this specification. The use of extensions must not contradict nor cause the non-conformance of functionality defined in the WAC specification.

+ +
+

Authorization Extensions

+
+

This section is non-normative.

+ +

As ACL resources are RDF sources; Authorization descriptions may be extended or limited by constraints, e.g., temporal or spatial constraints; and duties, e.g., payments, may be imposed on permissions; but no behaviour is defined by this specification. For example, the ODRL Information Model can be used to set obligations required to be met by agents prior to accessing a resource.

+ +

To allow access to a class of resources, implementations may want to use the acl:accessToClass predicate as defined in the ACL ontology.

+ +

Source: issues/10, issues/22, pull/37, issues/20

+
+
+ +
+

Access Mode Extensions

+
+

An extension to access modes is any mode that is defined in the ACL ontology, i.e., as a subclass of acl:Access, but not described in this specification (Access Modes). Consumers of Authorizations that encounter unrecognised access modes MUST NOT stop processing or signal an error and MUST continue processing the access modes as if those properties were not present.

+ +

Foreign-namespaced access modes are allowed in ACL resources, but they MUST NOT cause increased access.

+
+
+ +
+

Permission Inheritance Extensions

+
+

This section is non-normative.

+ +

This specification describes permission inheritance based on determining the Effective ACL Resource of a resource. Alternative strategies such as cumulative permissions (union of all the permissions from each ACL resource inherited from the ancestors of a resource) are allowed, but no behaviour is defined by this specification.

+
+
+ +
+

Distinct Effective ACL Resource Extensions

+
+

This section is non-normative.

+ +

This specification describes the use of acl Link Relation for ACL Resource Discovery and the algorithm to determine the Effective ACL Resource of a resource. To enable clients to perform discovery faster, separate link relation type targeting the effective ACL resource is allowed, but no behaviour is defined by this specification.

+
+
+
+
+ +
+

Considerations

+
+

This section details security, privacy, accessibility and internationalization considerations.

+ +

Some of the normative references with this specification point to documents with a Living Standard or Draft status, meaning their contents can still change over time. It is advised to monitor these documents, as such changes might have implications.

+ +
+

Security Considerations

+
+

This section is non-normative.

+ +

While this section attempts to highlight a set of security considerations, it is not a complete list. Implementers are urged to seek the advice of security professionals when implementing mission critical systems using the technology outlined in this specification.

+ +

Implementations are encouraged to follow the security considerations that are found in URI Generic Syntax, HTTP/1.1 Message Syntax and Routing and Semantics and Content.

+ +

Servers are strongly discouraged from trusting the information returned by looking up an agent’s WebID for access control purposes. The server operator can also provide the server with other trusted information to include in the search for a reason to give the requester the access.

+ +

Transfer of Authorizations between a client and server over an open network creates the potential for those policies to be modified or disclosed without proper authorization. The requirements for the WAC protocol discussed in this specification do not include cryptographic protection of Authorization information, because it is assumed that this protection can be provided through HTTP over TLS. The path between client and application may be composed of multiple independent TLS connections, thus for end-to-end integrity and authenticity of content within an HTTP message, implementers can use mechanisms such as Signing HTTP Messages. For cryptographic proof of Authorizations asserted by agents and protection from undetected modifications, implementers can use mechanisms such as Linked Data Security.

+ +

Implementations are encouraged to use mechanisms to record activities about ACL resources for the purpose of accountability and integrity, e.g., by having audit trails, notification of changes, reasons for change, preserving provenance information.

+ +

Implementations that want to allow a class of write or control operations on resources are encouraged to require agents to be authenticated, e.g., for purposes of provenance or accountability.

+
+
+ +
+

Privacy Considerations

+
+

This section is non-normative.

+ +

The class of read and write operations require discrete access permissions:

+ +

Access permission to append a new resource to a container resource is independent of access permission to read a container resource. Thus, servers are encouraged to prevent information leakage when a successful HTTP request appends a new resource to a container resource. For instance, while the knowledge of the URI-Reference in Location and Content-Location HTTP headers in the response of a POST does not in itself pose a security threat ([RFC3986]), servers should consider the risks when read access to the container is not granted to agents.

+ +

Access permission to update a resource is independent of access permission to read a resource. Thus, servers are encouraged to prevent information leakage when an attempt to delete information in a resource may reveal the existence of the information. For instance, when an HTTP PATCH request uses SPARQL Update’s DELETE DATA operation, servers should consider the risks of disclosing information by the chosen status code when read access to the resource is not granted to agents.

+
+
+ +
+

Accessibility Considerations

+
+

This section is non-normative.

+
+
+ +
+

Internationalization Considerations

+
+

This section is non-normative.

+
+
+ +
+

Security and Privacy Review

+
+

This section is non-normative.

+ +

These questions provide an overview of security and privacy considerations for this specification as guided by [SECURITY-PRIVACY-QUESTIONNAIRE].

+ +
+
What information might this feature expose to Web sites or other parties, and for what purposes is that exposure necessary?
+
There are no known security impacts of the features in this specification.
+ +
Do features in your specification expose the minimum amount of information necessary to enable their intended uses?
+
Yes.
+ +
How do the features in your specification deal with personal information, personally-identifiable information (PII), or information derived from them?
+
ACL resources may contain any data including that which identifies or refers to agents and agent groups. Access to ACL resources is only granted to Access Subjects with the acl:Control access mode, and thus by definition, meaningful consent to any personal data that agents include about themselves is extended to other agents with control access on the ACL resource. Group resources are subject to the same Authorization conditions as any resource (that is not an ACL resource), and thus information may be exposed.
+ +
How do the features in your specification deal with sensitive information?
+
Same implications as personal information and personally-identifiable information in ACL resources and group resources. When including sensitive information, the sender should be aware that changes to a group resource’s ACL resource may allow non-members or new members to view membership details.
+ +
Do the features in your specification introduce new state for an origin that persists across browsing sessions?
+
No.
+ +
Do the features in your specification expose information about the underlying platform to origins?
+
No.
+ +
Does this specification allow an origin to send data to the underlying platform?
+
No. ACL resources are described within the framework of HTTP as RDF documents represented with the Turtle syntax. Servers may be able to redirect ACL resources, (e.g., the https: URLs to file:, data:, or blob: URLs), but no behaviour is defined by this specification.
+ +
Do features in this specification allow an origin access to sensors on a user’s device
+
No.
+ +
What data do the features in this specification expose to an origin? Please also document what data is identical to data exposed by other features, in the same or different contexts.
+
No detail about another origin’s state is exposed. As the association between a resource and its ACL resource is at the discretion of the resource server, they can be on different origins (URI Origin). Similarly, when a server participates in the CORS protocol [FETCH], HTTP requests from different origins my be allowed. This feature does not add any new attack surface above and beyond normal CORS requests, so no extra mitigation is deemed necessary.
+ +
Do features in this specification enable new script execution/loading mechanisms?
+
No.
+ +
Do features in this specification allow an origin to access other devices?
+
No.
+ +
Do features in this specification allow an origin some measure of control over a user agent’s native UI?
+
No.
+ +
What temporary identifiers do the features in this specification create or expose to the web?
+
None.
+ +
How does this specification distinguish between behaviour in first-party and third-party contexts?
+
When an HTTP request includes the Origin header (typical Web browsers use origin based security to warn servers), Authorizations are matched in context of the origin of the HTTP request in addition to requiring agent identification and allowed access modes. While the use of Origin is not intended as client identification, the implication is that unless servers have separate mechanisms to verify the original request made by an application, the Origin header’s field-value can differ. In order to distinguish social entities and clients supported by authentication protocols, an issue on client identification is filed.
+ +
How do the features in this specification work in the context of a browser’s Private Browsing or Incognito mode?
+
No different than browser’s 'normal' state.
+ +
Does this specification have both "Security Considerations" and "Privacy Considerations" sections?
+
Yes, in Security Considerations and Privacy Considerations.
+ +
Do features in your specification enable origins to downgrade default security protections?
+
No.
+
+
+
+
+
+ +
+

References

+
+
+

Normative References

+
+
+
[FETCH]
+
Fetch Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://fetch.spec.whatwg.org/
+
[FOAF]
+
FOAF Vocabulary Specification 0.99 (Paddington Edition). Dan Brickley; Libby Miller. FOAF project. 14 January 2014. URL: http://xmlns.com/foaf/spec
+
[INFRA]
+
Infra Standard. Anne van Kesteren; Domenic Denicola. WHATWG. Living Standard. URL: https://infra.spec.whatwg.org/
+
[RDF-SCHEMA]
+
RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf-schema/
+
[RDF11-CONCEPTS]
+
RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/
+
[RFC2119]
+
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
+
[RFC3864]
+
Registration Procedures for Message Header Fields. G. Klyne; M. Nottingham; J. Mogul. IETF. September 2004. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc3864
+
[RFC3986]
+
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://datatracker.ietf.org/doc/html/rfc3986
+
[RFC5789]
+
PATCH Method for HTTP. L. Dusseault; J. Snell. IETF. March 2010. Proposed Standard. URL: https://httpwg.org/specs/rfc5789.html
+
[RFC6454]
+
The Web Origin Concept. A. Barth. IETF. December 2011. Proposed Standard. URL: https://datatracker.ietf.org/doc/html/rfc6454
+
[RFC7231]
+
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
+
[RFC8274]
+
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc8174
+
[RFC8288]
+
Web Linking. M. Nottingham. IETF. October 2017. Proposed Standard. URL: https://httpwg.org/specs/rfc8288.html
+
[TURTLE]
+
RDF 1.1 Turtle. Eric Prud'hommeaux; Gavin Carothers. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/turtle/
+
[VCARD-RDF]
+
vCard Ontology - for describing People and Organizations. Renato Iannella; James McKinney. W3C. 22 May 2014. W3C Note. URL: https://www.w3.org/TR/vcard-rdf/
+
[WEBARCH]
+
Architecture of the World Wide Web, Volume One. Ian Jacobs; Norman Walsh. W3C. 15 December 2004. W3C Recommendation. URL: https://www.w3.org/TR/webarch/
+
[WEBID]
+
WebID 1.0. Henry Story; Andrei Sambra; Stéphane Corlosquet. W3C Editor’s Draft. URL: https://www.w3.org/2005/Incubator/webid/spec/identity/
+
+
+
+ +
+

Informative References

+
+
+
[LDP]
+
Linked Data Platform 1.0. Steve Speicher; John Arwe; Ashok Malhotra. W3C. 26 February 2015. W3C Recommendation. URL: https://www.w3.org/TR/ldp/
+
[ODRL-MODEL]
+
ODRL Information Model 2.2. Renato Iannella; Serena Villata. W3C. 15 February 2018. W3C Recommendation. URL: https://www.w3.org/TR/odrl-model/
+
[SECURITY-PRIVACY-QUESTIONNAIRE]
+
Self-Review Questionnaire: Security and Privacy. Theresa O'Connor; Peter Snyder. W3C. 23 March 2021. W3C Note. URL: https://www.w3.org/TR/security-privacy-questionnaire/
+
[SOLID-PROTOCOL]
+
Solid Protocol. Sarven Capadisli; Tim Berners-Lee; Ruben Verborgh; Kjetil Kjernsmo; Justin Bingham; Dmitri Zagidulin. W3C Solid Community Group. W3C Editor’s Draft. URL: https://solidproject.org/TR/protocol
+
[SPARQL11-QUERY]
+
SPARQL 1.1 Query Language. Steven Harris; Andy Seaborne. W3C. 21 March 2013. W3C Recommendation. URL: https://www.w3.org/TR/sparql11-query/
+
[SPARQL11-UPDATE]
+
SPARQL 1.1 Update. Paula Gearon; Alexandre Passant; Axel Polleres. W3C. 21 March 2013. W3C Recommendation. URL: https://www.w3.org/TR/sparql11-update/
+
+
+
+
+
+
+
+
+ + + + + +