From 64b2aa2cf244650dfe469d7fdd451488b3c025b5 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Fri, 25 Sep 2020 10:22:28 +0300 Subject: oauth2: add grant types, flow diagrams --- yuck.md | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file 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 -- cgit v1.2.1