Added a Web Credential-based login mechanism to the spec.

specs/source/web-identity/index.html

@@ -592,7 +592,131 @@ <h2>Credentials and Claims</h2>
     </section>
 
     <section>
-      <h1>Compatibility with other Identity Mechanisms</h1>
+      <h1>Web Credential-based Login</h1>
+      <p>
+It is possible to use the mechanism described in this specification to login to
+a website in much the same way that Persona enables a verified email login. The
+process is described below:
+      </p>
+      <ol>
+        <li>
+Go to a website that requires a valid email address for login.
+        </li>
+        <li>
+The website requests the email address for login.
+        </li>
+        <li>
+A document is fetched from the domain of the email address checking for a 
+Web Identity endpoint and identity URL template.
+        </li>
+        <li>
+The user agent is instructed to retrieve the credential information from the
+Web Identity endpoint and send it to the website requiring login.
+        </li>
+        <li>
+The website that requires the valid email address for login checks the
+credentials posted by the user agent, verifies the signatures, and creates a
+session for the user.
+        </li>
+      </ol>
+
+      <section>
+        <h2>Detailed Flow for Credential-based Login</h1>
+        <p>
+In the following example, a login prompt is provided on
+<code>store.example.org</code> where the person that is logging in provides 
+the <code>asmith@example.com</code> email address. The first step constitutes
+<code>store.example.org</code> fetching the identity endpoint information 
+from <code>example.com</code>:
+        </p>
+        <pre class="example" title="Step 1a: Web Identity endpoint requested">
+GET /.well-known/identity HTTP/1.1
+Host: example.com
+Date: Wed, 08 Jun 2013 22:54:42 GMT
+Content-Type: application/ld+json
+        </pre>
+        <p>
+A successful retrieval of the identity service endpoint will result in the
+following document:
+        </p>
+        <pre class="example" title="Step 1b: Web Identity endpoint document retrieved">
+HTTP/1.1 200 OK
+Content-Type: application/ld+json
+Content-Length: 34
+Date: Wed, 08 Jun 2013 22:54:43 GMT
+
+{
+  "@context": "https://w3id.org/identity/v1",
+  "identityService": {
+    "@id": "https://example.com/identities/:id",
+    "parameter": {
+      "name": ":id",
+      "property": "https://w3id.org/identity#slug"
+    }
+  }
+}
+        </pre>
+        <p>
+The <code>store.example.org</code> software may then construct the proper query 
+by modifying the identity service information with the given information:
+        </p>        
+        <pre class="example" title="Step 2a: Request verified e-mail information">
+POST /identities/asmith?action=query&credentials=true&callback=https://store.example.org/verify?session=8d73j320s HTTP/1.1
+Host: example.com
+Date: Wed, 08 Jun 2013 22:54:44 GMT
+Content-Type: application/ld+json
+
+{
+  "@context": "https://w3id.org/identity/v1",
+  "id": "https://example.com/identities/asmith",
+  "email": ""
+}
+        </pre>
+        <p>
+After a UI interaction with Alice on <code>example.com</code> verifies that 
+the email information should be sent to <code>store.example.org</code>, 
+the following message is transmitted from Alice's user agent to
+<code>store.example.org</code>:
+        </p>
+        <pre class="example" title="Step 2b: Request for e-mail information is fulfilled">
+POST https://store.example.org/verify?session=8d73j320s HTTP/1.1
+Host: example.org
+Date: Wed, 08 Jun 2013 22:55:15 GMT
+Content-Type: application/ld+json
+
+{
+  "@context": "https://w3id.org/identity/v1",
+  "id": "https://example.com/identities/asmith",
+  "type": "Identity",
+  "email": "asmith@example.com",
+  "credential": [{
+    "id": "http://example.com/credentials/23894",
+    "type": "EmailCredential",
+    "claim": {
+      "id": "https://example.com/identities/asmith",
+      "email": "asmith@example.com",
+    },
+    "expires": "2015-02-04",
+    "signature": {
+       "type": "GraphSignature2012",
+       "signer": "https://example.com/keys/24",
+       "signature": "jf48901fu41...23908aszfhdk23h9f"
+    }
+  }]
+}
+        </pre>
+        <p>
+Note that for the purposes of simplicity in the example above, there is 
+no tracking protection to prevent <code>example.com</code> from knowing which 
+website Alice is logging in to. Tracking protection is easily implemented by
+adding a trusted 3rd party, such as the browser UI or a 3rd party mixer service,
+that decouples the identity provider from the relying party.
+        </p>
+      </section>
+    </section>
+
+    <section>
+      <h1>Compatibility with other Login Mechanisms</h1>
       <p>
 This identity mechanism is designed to be compatible with other identity
 mechanisms in use today such as OpenID, Facebook Connect, and Firefox ID.