# Introduction

* OAuth 2.0: Something I implemented in a previous job.

* A common, almost fundamental protocol on the web, especially
  for APIs.

  - See: OKAPI

* Solves a common problem: letting one site act on behalf of an end
  user on another site.

-----------------------------------------------------------------------------

# 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.

* 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?

-----------------------------------------------------------------------------

# 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.

Yeah right.

-----------------------------------------------------------------------------

# 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 go badly.

-----------------------------------------------------------------------------

# No, just no

Alice forwards each email to MailBooks. All 1.3 million of them.

-----------------------------------------------------------------------------

# OAuth2: Overview

* Alice asks MailBooks for a book.

* MailBooks tells her to authorize them on 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 "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
~~~


-----------------------------------------------------------------------------

# Details

* HTTPS: always when credentials or tokens are transmitted
* access and **refresh tokens**: may be opaque to clients
  - but JWT is common
* tokens are for a specific client and service
* tokens specify a **scope**: what operations they allow
* tokens expire → refresh tokens
* endpoint discovery: originally unspecified

-----------------------------------------------------------------------------

# Transaction 1: four specified grant variants

* authorization code: OKish, but security can be improved

  * a lot of HTTP redirects

* client credentials: bots without end users

* implicit: don't use, trusts browser too much

* resource owner password credentials: NO, JUST NO!

* any of these may of course fail

-----------------------------------------------------------------------------

# Transaction 2: use access token

* send request + token to resource provider (server)


-----------------------------------------------------------------------------

# Transaction 3: get new access token

* When access token expires.

* Or when a client wants to give another client an access token,
  possibly with less scope.

-----------------------------------------------------------------------------

# 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"
...