From a0c3e945da7cabd7b9b28f29d98e74b53ec10455 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 14 Nov 2020 19:54:51 +0200 Subject: oauth2: access and refresh token types --- yuck.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 99 insertions(+), 2 deletions(-) diff --git a/yuck.md b/yuck.md index 83fb647..7039850 100644 --- a/yuck.md +++ b/yuck.md @@ -201,14 +201,111 @@ Booksite -> Alice: Your book, bitte ## Token types -FIXME: explain different token types: access, refresh. what are their -use cases? Token does not need to be JMT of OAuth. +OAuth has two types of tokens: access and refresh. Access tokens are +used by the application to access resource providers. Refresh tokens +are used by the application to request a new access token from the +identity provider. + +OAuth does not specify the format of the tokens, and leaves it to the +identity provider. The resource provider needs a way to verify that a +token is valid. The validation mechanism is also not specified by +OAuth. However, the [JSON Web Token][] (JWT) specification is commonly +used. This will be covered in detail in the OIDC part of this +document. + +### Access tokens + +An access token is sufficient to access data on a resource provider, +on its own. A valid access token itself represents all the +authorization to access a protected resource via a resource provider. +Every access token granted on behalf of a resource owner does not +necessarily grant full and complete access to every resource owned by +end user, but may be limited in some way: a particular token may give +access only to a particular resource, or only certain kinds of access +(read vs write vs delete). Access tokens may also have a limited life +time, after which the resource provider refuses to accept them. + + +Access tokens are "bearer tokens", which means that any person or +software with a copy of the token can use it, within the constraints +encoded in the token itself. As such, access tokens are to be +considered sensitive data, just like all other credentials. + +### Refresh tokens + +A refresh token is used by the application to get a new access token, +without requiring the end user to grant one. When the end user grants +a token it is an interactive process, and may involve +re-authenticating them. This means it can be quite tedious and +irritating, if it happens often. + +An application may need a new access token for various reasons. For +example: + +* If access tokens expire, the application will use its refresh token + to get a new access token. + +* An access token may be revoked, but a refresh token may allow the + application to get a new one. The old access token revocation may be + due to the resource provider noticing suspicious activity. For + example, if the access token might be tied to a specific IP address, + but when a mobile application moves to a new network, its address + changes, invalidating the old access token. + + Revoking access tokens can be tricky, as the revocation needs to be + communicated to all the resource providers. For this reason, access + tokens often have a short life time. Refresh tokens are easier to + revoke, as only the identity provider needs to know about the + revocation. Thus a combination of short-lived access tokens and + longer-lived refresh tokens allows fairly rapid, but not instant, + revocations in a simple manner, without making the end user + re-authenticate themselves many times an hour. + +* The application may need to give an access token to another + application, but give them less access. In our book printing + example, the usual email application Alice uses to process all her + email might have a button to order a book, and the application could + automatically get a read-only access token to give to the book + printing service. The application could use a refresh token to get + the extra read-only access token without Alice having to interact + again with the identity provider directly. + +When the application uses a refresh token, the identity provider +validates it and, if everything is OK, responds with a new access +token, and possibly a new refresh token. + +The sequence diagram shows the protocol flow for when Alice's web mail +application orders a book for her. + +~~~plantuml +@startuml +hide footbox + +actor Alice +entity "Web mail \n application" as Webmail +entity "Identity provider" as IDP +entity "Book service" as Booksite +database "Email service" as Email + +Alice -> Webmail: Want book! +Webmail -> IDP: Give read-only access token, \n here is my refresh token +IDP -> Webmail: Your access token \n and a new refresh token +Webmail -> Booksite: Send Alice book, here is a read-only access token +Booksite -> Email: Give Alice's emails, here's my access token +Email -> Booksite: The emails you asked for +Booksite -> Alice: Your book! +@enduml +~~~ # The OIDC 1.0 protocol: authorization code FIXME: write this +## JSON Web Token format + +[JSON Web Token]: https://tools.ietf.org/html/rfc7519 + # Acknowledgement Thank you to Ivan Dolgov and Pyry Heiskanen for reviewing merge -- cgit v1.2.1