oauth2: add grant types, flow diagrams

1 files changed, 96 insertions, 4 deletions

diff --git a/yuck.md b/yuck.md
index e845c17..f50796c 100644
--- a/yuck.md
+++ b/yuck.md
@@ -107,10 +107,102 @@ book service can now access the email service API with the access
 token, and get what they need to print the books.
 
 [@rfc6749] describes the OAuth2 protocol in detail. This chapter
-condenses that into a shorter description.
-
-FIXME: The rest needs to be written.
-
+condenses that into a shorter, and opinionated description.
+
+## OAuth2 protocol variants (grant types)
+
+OAuth2 allows for several different kinds of use cases, by providing
+different ways to get an "authorization grant". An authorization grant
+is a thing that provides access to a protected resource (see section
+1.3 in [@rfc6749]).
+
+There are four authorization grant types:
+
+* authorization code
+  - this is a slightly simplified description: the spec seems to allow
+    less secure variants, but we'll get to that later
+  - application redirects end user's web browser to the identity
+    provider, which returns an authorization code to the application
+  - application gives authorization code to resource provider, which
+    gives back an access token
+  - browser never gets end the token
+  - the authorization code is random, temporary, short-lived, can only
+    be used once, and can be tied to a specific resource provider
+  - this allows the application to be authenticated as well as the
+    end user
+  - this is the most secure grant type and should be used if possible
+* implicit
+  - application is typically a JavaScript application running in the
+    browser
+  - access token is given directly to the browser
+  - this is vulnerable to browser insecurities, which are legion
+  - application can't be authenticated in any useful sense
+  - don't use this, due to low security
+* resource owner password credentials
+  - client has the end user's username and password
+  - never use this, as it leaks credentials and is inherently insecure
+* client credentials
+  - client has its own credentials
+  - can be suitable when the client itself is the resource owner (such
+    as for server-to-server communication) or the end user
+    authorization has been arranged beforehand using some other way
+
+In this document we only discuss the authorization code grant, as it's
+the only one of these we can recommend from a security point of view.
+
+## Overview of a basic OAuth2 transaction
+
+~~~dot
+digraph "oauth2" {
+    alice [label="Alice"];
+	booksite [label="Book service"];
+	email [label="Email service"];
+
+	alice -> booksite [label="1."];
+	booksite -> email [label="2."];
+	email -> alice [label="3."];
+	alice -> email [label="4."];
+	email -> booksite [label="5."];
+	booksite -> email [label="6."];
+	booksite -> alice [label="7."];
+}
+~~~
+
+The above diagram represents the steps of Alice getting her book of
+emails, at a very high level. There are many steps.
+
+1. Alice asks the book service for a book of her emails.
+2. Book service asks email service for an access token.
+3. Email service asks Alice if book service may access her emails.
+4. Alice tells email service "sure".
+5. Email service gives book service an access token.
+6. Book service uses access token to download all of Alice's emails.
+7. Book service sends book to Alice.
+
+The diagram below represents the same transaction, but in a different
+way. (One of the diagrams will be clearer to the reader, but it
+depends on the reader which.)
+
+~~~plantuml
+@startuml
+actor Alice
+entity "Book service" as Booksite
+database "Email service" as Email
+
+Alice -> Booksite: Want book!
+Booksite -> Email: May I get emails?
+Email -> Alice: OK to give emails to Booksite?
+Alice -> Email: Sure!
+Email -> Booksite: Have an access token
+Booksite -> Email: Emails please
+Booksite -> Alice: Your book, bitte
+@enduml
+~~~
+
+## Token types
+
+FIXME: explain different token types: access, refresh. what are their
+use cases? Token does not need to be JMT of OAuth.
 
 
 # The OIDC 1.0 protocol: authorization code