summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorLars Wirzenius <liw@liw.fi>2020-11-14 19:54:51 +0200
committerLars Wirzenius <liw@liw.fi>2020-11-14 19:54:51 +0200
commita0c3e945da7cabd7b9b28f29d98e74b53ec10455 (patch)
treeb5810051832bd7b56efb103d540786f4ad655207
parent2ae01fab3ab6cde97fc667c814f66569a59f4bdc (diff)
downloadyuck-a0c3e945da7cabd7b9b28f29d98e74b53ec10455.tar.gz
oauth2: access and refresh token types
-rw-r--r--yuck.md101
1 files 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