index.bs

<!---- GENERAL METADATA ------------------------------------------------------>

<pre class="metadata">

Title: Web Identity (WebID) 1.0
Shortname: WebID

!Authors: Henry Story
!Authors: <a class="p-name fn u-email email" href="mailto:timbl@w3.org">Tim Berners-Lee</a>
!Authors: <a class="p-name fn u-email email" href="mailto:andrei@fcns.eu">Andrei Sambra</a>

Editor: Jacopo Scazzosi, jacopo@scazzosi.com

Former Editor: Henry Story
Former Editor: Andrei Sambra, andrei@fcns.eu
Former Editor: Stéphane Corlosquet, scorlosquet@gmail.com

Group: w3c
Status: w3c/CG-DRAFT
Revision: 1

ED: https://w3c.github.io/WebID/spec/identity/

Previous Version: http://www.w3.org/2005/Incubator/webid/spec/identity/

Repository: https://github.com/w3c/WebID/

Abstract:

  A global distributed Social Web requires that each person be able to control
  their identity, that this identity be linkable across sites — placing each
  person in a Web of relationships — and that it be possible to authenticate
  globally with such identities.

  This specification outlines a simple universal identification mechanism that
  is distributed, openly extensible, improves privacy, security and control
  over how each person can identify themselves in order to allow fine grained
  access control to their information on the Web. It does this by applying the
  best practices of Web Architecture whilst building on well established widely
  deployed protocols and standards including HTML, URLs, HTTP, and RDF
  Semantics.

  <h3 id="how-to-read-this-document">How to Read this Document</h3>

  There are a number of concepts that are covered in this document that the
  reader may want to be aware of before continuing. General knowledge of RDF
  [[!RDF-PRIMER]] is necessary to understand how to implement this
  specification. This specification uses a number of specific technologies like
  Turtle [[!TURTLE]] and RDFa [[!RDFA-CORE]].

  A general [[#introduction|Introduction]] is provided for all that would like
  to understand why this specification is necessary to simplify usage of the Web.

  The terms used throughout this specification are listed in the section titled
  [[#terminology|Terminology]].

Status Text:

  This specification was published by the
  [WebID Community Group](https://www.w3.org/groups/cg/webid). It is not a
  W3C Standard nor is it on the W3C Standards Track. Please note that under the
  [W3C Community Contributor License Agreement (CLA)](https://www.w3.org/community/about/agreements/cla/)
  there is a limited opt-out and other conditions apply. Learn more about 
  [W3C Community and Business Groups](https://www.w3.org/community/).

  This is an internal draft document and may not even end up being officially
  published. It may also be updated, replaced or obsoleted by other documents
  at any time. It is inappropriate to cite this document as other than work in
  progress.

  If you wish to make comments regarding this document, please send them to 
  [public-webid@w3.org](mailto:public-webid@w3.org)
  ([archives](https://lists.w3.org/Archives/Public/public-webid/)).

</pre>

<p boilerplate="copyright">
  [Copyright](https://www.w3.org/policies/#copyright) © 2010-[YEAR]
  the Contributors to the WebID 1.0 Specification, published by the
  [WebID Community Group](https://www.w3.org/groups/cg/webid) under the
  [W3C Community Contributor License Agreement (CLA)](https://www.w3.org/community/about/agreements/cla/).
  A human-readable
  [summary](https://www.w3.org/community/about/agreements/cla-deed/)
  is available.
</p>


<!---- MAIN CONTENT ---------------------------------------------------------->

# Introduction # {#introduction}

[NO-NORM]

A WebID is an IRI with a HTTP(S) scheme that refers to an Agent (Person,
Organization, Group, Device, etc.); a description of the Agent named by the
WebID can be found in the respective [=WebID Document=].

WebIDs can be used to build a Web of trust using vocabularies such as FOAF
[[!FOAF]] by allowing people to link their profiles in a public or protected
manner. Such a web of trust can then be used by a [=Service=] to make
authorization decisions, by allowing access to resources depending on the
properties of an agent, such as that they are known by some relevant people,
employed at a given company, a member of a family or some other group, etc.

This specification is for:

- Anyone who wants to understand the architectural principles and notions underlying WebIDs
- Content publishers who want to allocate identifiers to unambiguously name agents
- Server application developers who want to provide client applications with WebIDs and associated agent descriptions
- Client application developers who want to use a WebID to unambiguously identify their applications as agents
- Specification authors who want to extend any of the WebID specifications via Extension Profiles, e.g., identity authentication protocols
  
## Outline ## {#outline}

This specification is divided in the following sections.

[[#introduction|This section]] gives a high level overview of this
specification, and presents the organization of the specification and the
conventions used throughout this document.

[[#terminology|Section 2]] provides a short description for the most commonly
used terms in this document.

[[#the-webid-http-iri|Section 3]] describes what a [=WebID=] is.

[[#webid-as-url-iri|Section 4]] expands on the use of IRI, URI and URL
throughout this document.

[[#overview|Section 5]] illustrates the relationship between a [=WebID=], the
[=Agent=] that is named by it, and the respective [=WebID Document=].

[[#example|Section 6]] provides an example of an actual [=WebID=] and the related
[=WebID Document=].

[[#publishing-the-webid-document|Section 7]] describes how a [=WebID Document=]
should be published, which format should be used in doing so and what it may 
contain.

[[#processing-the-webid-document|Section 8]] describes how a request for a
[=WebID Document=] should be handled.


# Terminology # {#terminology}

This section provides definitions for several important terms used in this
document.

: <dfn>Requesting Agent</dfn>

:: The Requesting Agent initiates a request to a Service listening on a
    specific port using a given protocol on a given Server.

: <dfn>Server</dfn>

:: A Server is a physical or virtual machine, contactable at a domain name or
    IP address, that hosts Services which are accessible over the network.

: <dfn>Service</dfn>

:: A Service is an agent listening for requests at a particular domain name or
    IP address on a given Server.

: <dfn>WebID</dfn>

:: An identifier in the form of an IRI with a HTTP(S) scheme that
    unambiguously names an Agent and, when dereferenced, always leads to a
    [=WebID Document=] which itself indicates that it describes the
    Agent named by the WebID.

: <dfn>WebID Document</dfn>

:: An RDF document that describes an Agent.

: <dfn>Agent</dfn>

:: An entity that performs or can perform an action, e.g., a person, an organization, a device.

## Namespaces ## {#namespaces}

Examples assume the following namespace prefix bindings unless otherwise
stated:

<table class="prefixes">
  <thead>
    <tr>
      <th>Prefix</th>
      <th>IRI</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>foaf</code></td>
      <td>http://xmlns.com/foaf/0.1/</td>
    </tr>
  </tbody>
</table>


# The WebID HTTP IRI # {#the-webid-http-iri}

When using IRIs with a HTTP(s) scheme, it is possible to identify both a thing
(which may exist outside of the Web) and a Web document describing the thing.
For example, the person Bob is described on his homepage. Alice may not like
the look of Bob's homepage, but may want to link to the person Bob. Therefore,
two IRIs are needed, one for Bob and one for Bob's homepage (or an RDF document
describing Bob).

A WebID HTTP IRI must be one that dereferences to a document the user controls.

For example, if a user Bob controls `https://bob.example.org/profile`, then his
WebID can be `https://bob.example.org/profile#me`.

<div class="note" id="note-cooluris">

  There are two solutions that meet our requirements for identifying real-world
  objects: 303 redirects and hash IRIs. Which one is best to use depends on the
  situation. Both have advantages and disadvantages, as presented in
  [[!COOLURIS]]. All examples in this specification will use such hash IRIs.

</div>

# WebID as a URL and WebID as an IRI # {#webid-as-url-iri}

[NO-NORM]

While a WebID is technically an [[!IRI]] with a HTTP(S) scheme, it can also
generally be considered a WHATWG [[!URL]] with a HTTP(S) scheme. Implementers
[SHOULD] prepare for the entire [[!IRI]] space.

<div class="note" id="note-iris-rdf12-concepts">

  This specification follows the definitions and constraints expressed in 
  [Section 3.2](https://www.w3.org/TR/rdf12-concepts/#section-IRIs) of
  [[!rdf12-concepts]] regarding the use of IRIs within RDF syntax and
  their relationship with URIs and URLs.

</div>

<div class="note" id="note-iri-rfc3987">

  This specification defers to the procedures defined in
  [Section 3](https://www.rfc-editor.org/rfc/rfc3987#section-3) of [[!IRI]]
  regarding mapping and conversion between the IRI and URI spaces.

</div>

# Overview # {#overview}

[NO-NORM]

The following diagram exemplifies the the relationship between a [=WebID=] IRI,
the [=WebID Document=] it resolves to and the agent it denotes.

<img src="img/webid-overview-diagram.png" alt="WebID overview" id="webid-diagram">

In the illustration above, the WebID IRI `https://example.org/ident#me`
(containing the **#me** fragment identifier) is an identifier that denotes
(refers to) an [=Agent=].

The WebID Document IRI `https://example.org/ident` (without the **#me**
fragment identifier) denotes the document describing the agent  who is the
referent of the WebID IRI.

<div class="note" id="note-strip-http-frag">

  As client HTTP libraries conforming to the HTTP standard automatically strip
  the fragment before sending requests to the server, all requests made against
  the WebID `https://example.org/ident#me` will implicitly be made against the
  location of the corresponding [=WebID Document=] `https://example.org/ident`.

</div>

The WebID Document gives the meaning of the WebID: its RDF Graph
contains a [Concise Bounded Description](http://www.w3.org/Submission/CBD/) of
the WebID such that this subgraph forms a definite description of the referent
of the WebID, that is, a description that distinguishes the referent of that
WebID from all other things in the world. The WebID Document
can, for example, contain relations to other documents depicting the WebID
referent, or it can relate the WebID to principals used by different
authentication protocols. (More information on WebID and other authentication
protocols can be found on the [WebID Identity
Interoperability](http://www.w3.org/2005/Incubator/webid/wiki/Identity_Interoperability)
page).

# Example # {#example}

[NO-NORM]

As example of a real-life WebID, consider that of Tim Berners-Lee, a real
physical person who has a history, who invented the World Wide Web, and who
directed the World Web Consortium: 
[https://www.w3.org/People/Berners-Lee/card#i](https://www.w3.org/People/Berners-Lee/card#i) . 

Tim's WebID can easily be dereferenced to its respective [=WebID Document=]
with any suitable HTTP client, such as [curl](https://curl.se/):

```
$ curl -H "Accept: text/turtle" https://www.w3.org/People/Berners-Lee/card#i
```

In doing so, we are presented with a document that includes the following
statements:

```turtle
    @prefix : <http://xmlns.com/foaf/0.1/> .
    @prefix card: <https://www.w3.org/People/Berners-Lee/card#> .
    @prefix cc: <http://creativecommons.org/ns#> .
    @prefix dc: <http://purl.org/dc/elements/1.1/> .

    <>     rdf:type :PersonalProfileDocument;
         cc:license <http://creativecommons.org/licenses/by-nc/3.0/>;
         dc:title "Tim Berners-Lee's FOAF file";
         :maker card:i;
         :primaryTopic card:i .
```

# Publishing the WebID Document # {#publishing-the-webid-document}

## Format of a WebID Document ## {#webid-document-format}

The [=Server=] [MUST] offer at least one RDF representation for a 
[=WebID Document=].

The [=Server=] [SHOULD] offer [[!TURTLE]] as one of the representations for a
[=WebID Document=].

<div class="note" id="note-rdf-formats">

  RDF serialization formats include, but are not limited to, [[!JSON-LD11]], 
  [[!TURTLE]], and [[!RDFA-CORE]].
  
</div>

<div class="note" id="note-turtle-interop">

  This specification does not mandate support for any specific format, 
  following the principle of 
  [Orthogonality of Specifications](https://www.w3.org/blog/2009/orthogonality-of-specification/).
  In the interest of interoperability, however, this specification warmly and
  earnestly suggests supporting the [[!TURTLE]] format, whether in addition to
  other formats or as the only supported one.

</div>

## Vocabulary of a WebID Document ## {#webid-document-vocabulary}

WebID RDF graphs are built using vocabularies identified by URIs, that can be
placed in subject, predicate or object position of the relations constituting
the graph. The definition of each URI should be found at the namespace of the
URI, by dereferencing it.

## Contents of a WebID Document ## {#webid-document-contents}

A [=WebID Document=] [MUST] qualify the described Agent as the
document's `foaf:primaryTopic`. Furthermore, a [=WebID Document=]
[SHOULD] also qualify the described Agent as having type `foaf:Agent`.

Personal details are the most common requirement when registering an account
with a website. Some of these pieces of information include an e-mail address,
a name and perhaps an avatar image, expressed using the FOAF [[!FOAF]]
vocabulary. This section includes properties that [SHOULD] be used when
conveying key pieces of personal information but are <em class="rfc2119"
title="NOT REQUIRED">NOT REQUIRED</em> to be present in a [=WebID Profile
Document=]:

: foaf:name

:: The name of the individual or agent.

: foaf:knows

:: The WebID URI of a known person.

: foaf:img

:: An image representing a person.


## Publishing a WebID Document using Turtle ## {#publishing-a-webid-document-using-turtle}

[NO-NORM]

A widely used format for writing RDF graphs by hand is the
[Turtle](http://www.w3.org/TR/turtle/) [[!TURTLE]] notation. It is easy to
learn, and very handy for communicating over e-mail and on mailing lists. The
syntax is very similar to the \[SPARQL](http://www.w3.org/TR/rdf-sparql-query/)
query language. WebID Documents in Turtle should be served with the
`text/turtle` content type.

Take for example the WebID *https://bob.example.org/profile#me*, for which the
WebID Document contains the following Turtle representation:

<div class="example" id="ex-webid-profile-turtle">
  <pre highlight="turtle">
    @prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt; .

    &lt;&gt; a foaf:PersonalProfileDocument ;
      foaf:maker &lt;#me&gt; ;
      foaf:primaryTopic &lt;#me&gt; .

    &lt;#me&gt; a foaf:Person ;
      foaf:name &quot;Bob&quot; ;
      foaf:knows &lt;https://example.edu/p/Alice#MSc&gt; ;
      foaf:img &lt;https://bob.example.org/picture.jpg&gt; .
  </pre>
</div>


## Publishing a WebID Document using the RDFa HTML notation ## {#publishing-a-webid-document-using-the-rdfa-html-notation}

[NO-NORM]

RDFa in HTML [[!RDFA-CORE]] is a way to markup HTML with relations that have a
well defined semantics and mapping to an RDF graph. There are many ways of
writing out the above graph using RDFa in HTML. Here is just one example of
what a WebID Document could look like.

<div class="example" id="ex-webid-profile-rdfa">
  <pre highlight="html">
    &lt;div vocab=&quot;http://xmlns.com/foaf/0.1/&quot; about=&quot;#me&quot; typeof=&quot;foaf:Person&quot;&gt;
      &lt;p&gt;My name is &lt;span property=&quot;name&quot;&gt;Bob&lt;/span&gt; and this is how I look like: &lt;img property=&quot;img&quot; src=&quot;https://bob.example.org/picture.jpg&quot; title=&quot;Bob&quot; alt=&quot;Bob&quot; /&gt;&lt;/p&gt;
      &lt;h2&gt;My Good Friends&lt;/h2&gt;
      &lt;ul&gt;
        &lt;li property=&quot;knows&quot; href=&quot;https://example.edu/p/Alice#MSc&quot;&gt;Alice&lt;/li&gt;
      &lt;/ul&gt;
    &lt;/div&gt;
  </pre>
</div>

If a WebID provider would prefer not to mark up their WebID Document in
HTML+RDFa, but just provide a human readable format for users in plain HTML and
have the RDF graph appear in a machine readable format such as Turtle, then he
[SHOULD] provide a link of type `alternate` to a machine readable format
[[!RFC5988]]. This can be placed in the HTTP header or in the html as shown
here:

<div class="example" id="webid-profile-link">
  <pre highlight="html">
    &lt;html&gt;
      &lt;head&gt;
        &lt;link rel=&quot;alternate&quot; type=&quot;text/turtle&quot; href=&quot;profile.ttl&quot;/&gt;
      &lt;/head&gt;
      &lt;body&gt; ... &lt;/body&gt;
    &lt;/html&gt;
  </pre>
</div>


## Privacy ## {#privacy}

[NO-NORM]

A WebID Document may contain public as well as private information
about the agent named by the WebID. As some agents may not want to reveal
a lot of information about themselves, RDF and Linked Data principles allows
them to choose how much information they wish to make publicly available. This
can be achieved by separating parts of the profile information into separate
documents, each protected by access control policies. 

On the other hand, some agents may want to publish more information about
themselves, but only to a select group of trusted agents. In the following
example, Bob is limiting access to his list of friends, by placing all
*foaf:knows* relations into a separate document.

<div class="example" id="ex-privacy-profile">
  <pre highlight="turtle">
    @prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt; .
    @prefix rdfs: &lt;http://www.w3.org/2000/01/rdf-schema#&gt; .

    &lt;&gt; a foaf:PersonalProfileDocument ;
      foaf:maker &lt;#me&gt; ;
      foaf:primaryTopic &lt;#me&gt; .

    &lt;#me&gt; a foaf:Person ;
      foaf:name &quot;Bob&quot; ;
      <strong>rdfs:seeAlso &lt;https://bob.example.org/friends&gt; ;</strong>
      foaf:img &lt;https://bob.example.org/picture.jpg&gt; .
  </pre>
</div>

Where https://bob.example.org/friends is a reference to an Access Control List
(ACL) protected document containing:

<div class="example" id="ex-privacy-seeAlso">
  <pre highlight="turtle">
    @prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt; .

    &lt;&gt; a foaf:PersonalProfileDocument ;
      foaf:maker &lt;https://bob.example.org/profile#me&gt; ;
      foaf:primaryTopic &lt;https://bob.example.org/profile#me&gt; .

    &lt;https://bob.example.org/profile#me&gt; a foaf:Person ;
      foaf:knows &lt;https://example.edu/p/Alice#MSc&gt; ;
      foaf:knows &lt;https://example.com/people/Mary/card#me&gt; .
  </pre>
</div>

and having the following corresponding ACL rule, expressed using the
[WebAccessControl](http://www.w3.org/wiki/WebAccessControl) ontology:

<div class="example" id="ex-privacy-acl">
  <pre highlight="turtle">
    @prefix acl: &lt;http://www.w3.org/ns/auth/acl#&gt; .

    &lt;#FriendsOnly&gt; ;
      acl:accessTo &lt;https://bob.example.org/friends&gt; ;
      acl:agent &lt;http://example.edu/p/Alice#Msc&gt;, &lt;http://example.com/people/Mary/card#me&gt; ;
      acl:mode acl:Read .
  </pre>
</div>


## Security Considerations ## {#security-considerations}

[NO-NORM]

A [=WebID=] identifies an agent via a description found in the associated
[=WebID Document=]. An agent that wishes to know what a WebID refers
to, must rely on the description found in the WebID Profile. An attack on the
relation between the [=WebID=] and the [=WebID Document=] can thus be
used to subvert the meaning of the WebID, and to make agents following links
within the [=WebID Document=] come to different conclusions from those
intended by profile owners.

The standard way of overcoming such attacks is to rely on the cryptographic
security protocols within the HTTPS [[!HTTP-TLS]] stack. HTTPS servers are
identified by a certificate either signed by a well known Certification
Authority or whose public key is listed in the DNSSEC as specified by the DANE
protocol [[!RFC6698]], or both. This makes it much more difficult to set up a
fake server by DNS Poisoning attacks. Resources served over HTTPS are
furthermore signed and encrypted removing all the simple man-in-the-middle
attacks. Applying the above security measure does not remove the burden from
server administrators to take the appropriate security measures, in order to
avoid compromising their servers. Similarly, clients that fetch documents on
the web also need to make sure their work environment has not bee
compromised.

As security is constantly being challenged by new attacks, to which new
responses are found, a collection of security considerations will be made
available on the [WebID
Wiki](http://www.w3.org/2005/Incubator/webid/wiki/Identity_Security).


# Processing the WebID Document # {#processing-the-webid-document}

The [=Requesting Agent=] needs to fetch the WebID Document, if it does
not have a valid one in cache. The Agent requesting the WebID Document
[MUST] be able to parse documents in Turtle [[!TURTLE]], but [MAY] also be able
to parse documents in RDF/XML [[!RDF-SYNTAX-GRAMMAR]] and RDFa [[!RDFA-CORE]].
The result of this processing should be a graph of RDF relations that is
queryable, as explained in the next section.

<div class="note" id="note-qvalue">

  It is recommended that the [=Requesting Agent=] sets a *qvalue* for
  `text/turtle` in the HTTP `Accept-Header` with a higher priority than in the
  case of `application/xhtml+xml` or `text/html`, as sites may produce HTML
  without RDFa markup but with a link to graph encoded in a pure RDF format
  such as Turtle. For an agent that can parse Turtle, rdf/xml and RDFa, the
  following would be a reasonable Accept header:
  <br />
  `Accept: text/turtle,application/rdf+xml,application/xhtml+xml;q=0.8,text/html;q=0.7`

</div>

If the [=Requesting Agent=] wishes to have the most up-to-date WebID Profile
Document for an HTTP URL, it can use the HTTP cache control headers to get the
latest versions.


# Acknowledgments # {#acknowledgments}

[NO-NORM]

Thanks to Henry Story for leading the development of WebID, without which none
of this would exist.

The following people have been instrumental in providing thoughts, feedback,
reviews, criticism and input in the creation of this specification: 

Stéphane Corlosquet, Erich Bremer, Kingsley Idehen, Ted Thibodeau, Alexandre
Bertails, Thomas Bergwinkl.


<!---- MACROS ---------------------------------------------------------------->

<pre class="metadata">

Text Macro: W3C <abbr title="World Wide Web Consortium">W3C</abbr>

Text Macro: NO-NORM *This section is non-normative.*

Text Macro: MUST <em class="rfc2119">MUST</em>
Text Macro: SHALL <em class="rfc2119">SHALL</em>
Text Macro: REQUIRED <em class="rfc2119">REQUIRED</em>

Text Macro: MUST-NOT <em class="rfc2119">MUST NOT</em>
Text Macro: SHALL-NOT <em class="rfc2119">SHALL NOT</em>

Text Macro: SHOULD <em class="rfc2119">SHOULD</em>
Text Macro: RECOMMENDED <em class="rfc2119">RECOMMENDED</em>

Text Macro: SHOULD-NOT <em class="rfc2119">SHOULD NOT</em>
Text Macro: NOT-RECOMMENDED <em class="rfc2119">NOT RECOMMENDED</em>

Text Macro: MAY <em class="rfc2119">MAY</em>
Text Macro: OPTIONAL <em class="rfc2119">OPTIONAL</em>

</pre>


<!---- CHECKS TO RUN --------------------------------------------------------->

<pre class="metadata">

Complain About: accidental-2119 yes
Complain About: broken-links yes
Complain About: missing-example-ids yes
Complain About: mixed-indents yes

</pre>


<!---- REFERENCE ANCHORS ----------------------------------------------------->

<pre class="metadata">

External Infotrees: anchors.bsdata no
External Infotrees: link-defaults.infotree no

</pre>


<!---- BIBLIOGRAPHY ---------------------------------------------------------->

<!-- Includes
  https://www.specref.org
  https://drafts.csswg.org/biblio.ref
  ./biblio.json
-->


<!---- CUSTOM STYLING -------------------------------------------------------->

<pre class="metadata">

Dark Mode: no
Boilerplate: conformance no, index no
Max ToC Depth: 4
Markup Shorthands: markdown yes
Inline Github Issues: title
Metadata Order: Title, Shortname, Authors, Editor, Former Editor, Group, Status, Revision, ED, TR, Previous Version, Repository, Abstract, Status Text

</pre>