From ad3611717ff4b56074c5cc0f4d9a4672adb1c223 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 19 Sep 2020 14:47:40 +0300 Subject: 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. --- bibliography.yaml | 29 ++++++++++++++++++++++++++ yuck.bib | 7 ------- yuck.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++--------- 3 files changed, 81 insertions(+), 17 deletions(-) create mode 100644 bibliography.yaml delete mode 100644 yuck.bib 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: -- cgit v1.2.1