docs: start description of OAuth2

Give a very high-level, non-technical overview of what OAuth2 is for
and how it works. I'll add more specifics as I get familiar again with
the protocol specification.

Also, convert the bibliography into YAML, as I find that easier to read.

3 files changed, 81 insertions, 17 deletions

diff --git a/bibliography.yaml b/bibliography.yaml
new file mode 100644
index 0000000..e16b69e
--- /dev/null
+++ b/bibliography.yaml
@@ -0,0 +1,29 @@
+---
+references:
+
+- id: rfc6749
+  type: webpage
+  author:
+  - family: Hardt
+    given: D.
+  issued:
+  - year: 2012
+    month: 10
+  title: The OAuth 2.0 Authorization Framework
+  publisher: IETF
+  url: https://tools.ietf.org/html/rfc6749
+
+- id: rfc8252
+  type: webpage
+  author:
+  - family: Denniss
+    given: W.
+  - family: Bradley
+    given: J.
+  issued:
+  - year: 2017
+    month: 10
+  title: OAuth 2.0 for native apps
+  publisher: IETF
+  url: https://tools.ietf.org/html/rfc8252
+...
diff --git a/yuck.bib b/yuck.bib
deleted file mode 100644
index c39c0d7..0000000
--- a/yuck.bib
+++ /dev/null
@@ -1,7 +0,0 @@
-@manual{rfc8252,
-title = "OAuth 2.0 for Native Apps",
-author = "W. Denniss and J. Bradley",
-organization = "IETF",
-year = 2017,
-month = October,
-}
diff --git a/yuck.md b/yuck.md
index edaf804..e845c17 100644
--- a/yuck.md
+++ b/yuck.md
@@ -35,8 +35,6 @@ identity provider can keep a login session open independently of the
 other services and applications, this provides a single sign-on
 experience.
 
-FIXME: add examples of what each protocol is suited for.
-
 We discuss here only these specific versions of these protocols, and
 even then only subsets chosen based mainly from the point of security.
 
@@ -56,18 +54,62 @@ The protocols involves the following entities:
   access to them via a web API
 * the **identity provider** (IDP), which authenticates the user
 
-FIXME: references for these
+The protocol specifications use different terminology, to be more
+generic. The above have been chosen to make this document easier to
+understand.
+
+
+
+
+# The OAuth 2.0 protocol
+
+The OAuth2 protocol is a way for an end user to allow one service
+controlled access to their data on another service. It does not
+authenticate the end user in any way.
+
+As an example, imagine if Alice uses an email service, but would also
+like to make use of another service that typesets and prints emails
+into really nice, impressive, beautiful, heirloom quality, leather
+bound hardcover books. The book service needs to be able to read
+Alice's emails, but not delete them or send email as Alice.
+
+In a kinder world than ours Alice could just give their email password
+to the book service, but in our world, this needs to be done in a more
+complicated way. Otherwise someone at the book service would abuse
+access to Alice's email account by deleting all the email, or worse.
+
+The gist of OAuth2 is that Alice can tell their email service that the
+book service is allowed to read all her correspondence, but do nothing
+else.
 
-# The OAuth 2.0 protocol: client credentials grant
+In a simplistic way, Alice logs into the email service, and asks for
+an _access token_, then passes that onto the book service. The book
+service logs into the email service, and gives the access token to
+gain access to Alice's emails. The email service knows that the access
+token only allows read-only access: no deletion or sending.
 
-FIXME: give a very high level overview of the protocol, and what
-grants are
+However, such a system would be cumbersome to use. Alice would have to
+manually navigate to the email service's access token generation page,
+copy the token, and have a way to communicate the token to the book
+service. This is too much manual work, with too many steps, and too
+much can go wrong.
 
-FIXME: reference some other sources of information
+Instead, Alice logs into the book service, and tells them which email
+service to get emails from. The book service redirects Alice's to the
+email service in a way that tells the email service that a) an access
+is required b) by the book service c) for read-only access d) to
+Alice's emails. The mail service checks that Alice is already logged
+in, or else asks Alice to log in, and that Alice is OK with giving the
+book service the access requested. If all that goes well, the email
+service generates the token, and redirects Alice's web browser back to
+the book service in such a way that the token is carried along. The
+book service can now access the email service API with the access
+token, and get what they need to print the books.
 
-FIXME: explain why only this grant is chosen
+[@rfc6749] describes the OAuth2 protocol in detail. This chapter
+condenses that into a shorter description.
 
-See [@rfc8252] for a description of the client credentials grant.
+FIXME: The rest needs to be written.
 
 
 
@@ -81,7 +123,7 @@ FIXME: write this
 title: "OAuth2 and OpenID Connect: protocols and acceptance criteria"
 author: Lars Wirzenius
 documentclass: report
-bibliography: yuck.bib
+bibliography: bibliography.yaml
 bindings: 
   - yuck.yaml
 classes: