diff options
author | Lars Wirzenius <liw@liw.fi> | 2020-09-19 14:47:40 +0300 |
---|---|---|
committer | Lars Wirzenius <liw@liw.fi> | 2020-09-21 11:53:17 +0300 |
commit | ad3611717ff4b56074c5cc0f4d9a4672adb1c223 (patch) | |
tree | 80bc371b0e7ae3b9d60ca65d298cb64c0dc99fdd /yuck.md | |
parent | 42cd2442e1f5703ec5231e320076bce376e175c1 (diff) | |
download | yuck-ad3611717ff4b56074c5cc0f4d9a4672adb1c223.tar.gz |
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.
Diffstat (limited to 'yuck.md')
-rw-r--r-- | yuck.md | 62 |
1 files changed, 52 insertions, 10 deletions
@@ -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: |