![](Anca.jpg) Kurt Bauschardt: [Anca the Weasel](https://commons.wikimedia.org/wiki/File:Anca_the_Weasel_(26984433186).jpg) ----------------------------------------------------------------------------- # Introduction * OAuth 2.0: Something I implemented in a previous job. * A common, almost fundamental protocol on the web, especially for APIs and (third-party) applications. - See: OKAPI, Google, Microsoft, ... * Solves a common problem: letting one system act on behalf of an end user on another system. ----------------------------------------------------------------------------- # Basic concepts * Identification "who are you?" - all the relevant things others need to know about you - name, date of birth, contact info, DNS sample, ... - often just "this user account on this service" * Authentication: "how do I know it's really you?" - something you know, something you have, something you are - passwords - hardware security tokens - biometrics - possibly several, depending * Authorization: "what should I allow you to do?" - who said you can? ----------------------------------------------------------------------------- # What OAuth2 is for? * Client authorization (by end-user or otherwise). * NOT end-user identification. * NOT end-user authentication. * NOT end-user authorization. * NOT client identification. * NOT client authentication. ----------------------------------------------------------------------------- I hereby authorize this specific third party to access these bits of my data stored on this particular service. The third party has only specific, limited access, possibly for a limited time. I may withdraw my authorization at any time. ----------------------------------------------------------------------------- # Example * Alice uses an email service, AMail. * Alice wants to have a book printed with all her emails. A beautifully typeset, illustrated, color-printed, leather-bound, hard cover book. An heirloom. * Book printing service, MailBooks, can do this, but needs to access AMail to download all of Alice's emails. * How can this be done securely? ----------------------------------------------------------------------------- ~~~dot digraph "OAuth" { Alice [shape="star"]; AMail [shape="cylinder"]; MailBooks [shape="ellipse"]; Alice -> MailBooks [label="one book, please"]; MailBooks -> AMail [label="Alice's emails, please"]; AMail -> Alice [label="May MB get your emails?"]; } ~~~ ----------------------------------------------------------------------------- # Not this way Alice gives MailBooks her username and password at AMail. MailBooks **solemnly promises** to not delete anything and to not send any mail, and to forget the password after they've got what they need for producing the book. _This works really, really well. Hunky-dory._ ----------------------------------------------------------------------------- # Not this way either MailBooks and AMail have a **special agreement**. AMail will give all the emails MailBooks asks for. MailBooks **promises** to only ask for email of people who say they want a book. MailBooks asks its customers to not lie about who they are. _There is no way in which this might ever go badly in any way._ ----------------------------------------------------------------------------- # No, just no Alice forwards each email to MailBooks. All 1.3 million of them. _It will take no time at all. Easy peasy._ ----------------------------------------------------------------------------- # OAuth2: Overview * Alice asks MailBooks for a book. * MailBooks tells her to **authorize** them to AMail. * Alice logs into AMail and clicks a button to authorize MailBooks. AMail creates an **access token**. * Alice gives the access token to MailBooks. * MailBooks gives the access token to AMail and says it wants a copy of every one of Alice's email. * AMail checks the token and responds with all a copy of all the emails. * MailBooks prints and sends the book to Alice. ----------------------------------------------------------------------------- ~~~plantuml @startuml actor Alice entity "MailBooks" as Booksite database "AMail" as Email hide footbox Alice -> Booksite: Want book! Booksite -> Alice: redirect to authorization Alice -> Email: follow redirection Email -> Alice: OK to give emails to MailBooks? Alice -> Email: Sure! Email -> Alice: redirect back to MailBooks, with access token Alice -> Booksite: follow redirection Booksite -> Email: Emails please, here is access token Email -> Booksite: the emails you requested Booksite -> Alice: Your book, bitte @enduml ~~~ ----------------------------------------------------------------------------- # Details * **HTTPS**: always when credentials or tokens are transmitted - just use HTTPS always for everything - a lot of HTTP redirects: can affect performance, be confusing * access and **refresh tokens**: may be opaque to clients - but JWT is common, because OpenID Connect * tokens are for a specific client and service * tokens specify a **scope**: what operations they allow * tokens expire → refresh tokens * tokens can be revoked → refresh tokens or start over * endpoint discovery: originally unspecified ----------------------------------------------------------------------------- # Transaction 1: get an access token (maybe refresh token) * four specified "flows" for this - custom flows possible * _authorization code grant_: **OKish** * _client credentials grant_: **bots without end users** * _implicit grant_: **don't use**, trusts browser and device too much * new flow **PKCE** replaces this, for mobile and SPA * _resource owner password credentials grant_: **NO, JUST NO!** - motivation: legacy systems ----------------------------------------------------------------------------- # Transaction 2: use access token * send request + token to resource provider (server) * typically as an HTTP header - `Authorization: Bearer TOKEN` ----------------------------------------------------------------------------- # Transaction 3: get new access token * When access token expires or is revoked. * Or when a client wants to give another client an access token, possibly with less scope. - might be a different part of the same client ----------------------------------------------------------------------------- # SEE ALSO * [RFC 6749](https://tools.ietf.org/html/rfc6749) * [OAuth website](https://oauth.net/) * [Yuck](https://yuck.liw.fi/) ----------------------------------------------------------------------------- # Legalese Copyright 2020 Wikimedia Foundation This content is licensed under the Creative Commons Attribution-ShareAlike 4.0 International ([CC BY-SA 4.0][]) licence. [CC BY-SA 4.0]: https://creativecommons.org/licenses/by-sa/4.0/ --- title: "The OAuth 2.0 Protocol" subtitle: "EngProd paper club: RFC 6749" author: "Lars Wirzenius" date: "2020-12-07" ...