A brief summary of the OAuth 2.0 RFC

< previousnext >

This is the briefest useful1 summary2 I could come up with for OAuth 2.0, after reading3 the original RFC.

Quick definitions

Protocol flow

This is essentially how the flow works (with time moving from left to right)4:

              Client: ------------------------------------------------->
                       \     / \             / \                     /
                        1   2   3           /   5                   /
                         \ /     \         /     \                 /
      Resource Owner: ------------\-------/-------\---------------/---->
                                   \     /         \             /
                                    \   4           \           /
                                     \ /             \         /
Authorization Server: --------------------------------\-------/-------->
                                                       \     /
                                                        \   6
                                                         \ /
     Resource Server: ------------------------------------------------->
  1. Request authorization from Resource Owner, preferably (but optionally5) through Authorization Server.
  2. Client receives Authorization Grant.
  3. Request Access Token with Authorization Grant.
  4. Authorization Server validates Grant & issues Access Token.
  5. Request protected resource with Access Token.
  6. Validate Access Token and serve request.

What are…

Authorization Grants?

This is a method the Client can use to get an Access Token from the Authorization Server, it can be one of four types6:

Access Tokens?

An Access Token is a time-limited token giving access to certain scopes. A Resource Server should be able to verify an Access Token without querying the Authorization Server. It could for example7 be a JWT8 with the scopes in the claims part.

Refresh Tokens?

Since Access Tokens time-out at some point, the Client needs a way to get a new one when that happens. This forces the Client to “recheck” with the Authorization Server every now and then, to see if they’re still authorized to access the protected resource.

So essentially, Refresh Tokens exist to allow you to revoke authorizations, or have sessions time out. This is how Refresh Tokens work:

              Client: ------------------------------------------------->
                       \             / \     / \     / \             /
                        1           /   3   4   5   6   7           /
                         \         /     \ /     \ /     \         /
     Resource Server: ----\-------/-----------------------\-------/---->
                           \     /                         \     /
                            \   2                           \   8
                             \ /                             \ /
Authorization Server: ------------------------------------------------->
  1. Client sends Authorization Grant to Authorization Server.
  2. Authorization Server sends back Access Token and Refresh Token.
  3. Client uses Access Token to request protected resource from Resource Server.
  4. Resource Server returns protected resource to Client9.
  5. Client uses expired Access Token to request (another) protected resource from Resource Server.
  6. Resource Server returns an Invalid Token Error.
  7. Client sends Refresh Token to Authorization Server10.
  8. Authorization Server sends back Access Token and optional Refresh Token.

Clients?

Clients are usually registered on Authorization Server. There are two types of clients:

Clients have a client identifier: a non-confidential string differing per Client. It’s defined/registered by Client on Authorization Server. These strings are unique per Authorization Server.

Endpoints on Authorization Server

Note that the RFC does not define the URI path for these endpoints.

  1. Authorization
    1. used to obtain Authorization Grant.
    2. MUST verify Resource Owner identity.
    3. MAY get a URL-encoded query paramater, which MUST be retained11.
    4. MUST NOT include fragment component (e.g. #home).
    5. MUST use TLS.
    6. MUST support GET, MAY also support POST.
    7. MUST accept a response_type parameter (one of code, token).
    8. MUST accept redirect_uri request parameter.
    9. accepts scope token through scope parameter which is a space-separated list of scopes.
    10. MAY fully or partially ignore scope, but MUST sent scope response parameter if it does.
  2. Token
    1. used to obtain Access Token (and optional Refresh Token).
    2. MUST accept only POST.
    3. Client must authenticate itself.
    4. see Aiii.
    5. see Aiv.
    6. see Aix.
    7. see Ax.

Ending remarks

While I make a lot of jokes about the protocol and its definition, I actually love the OAuth 2.0 spec: it’s pretty clear and well-defined. The scope is super tight and some things are a bit confusing until you get a more complete overview, but it’s incredibly useful and helpful.

In the interest of making this an overview document and keeping it summarized, you’ll probably have noticed by now that I make extensive use of footnotes12. A lot of important information is there, so if you haven’t yet, I’d recommend you take the time to read them.

Also: I consider this a “living document,” and I very much welcome corrections or additions. You can find my contact details on my personal website. If you wanna help me out, consider sharing this on the relevant social medias.

  1. We define “useful” here as meaning “completely useless for any practical purposes that aren’t ‘diving deeper into OAuth 2.0’”, so take that as you will. 

  2. While this does summarize the OAuth protocol, it leaves out a ton of actually vital information. 

  3. Yes, I did read all 76 pages of the original RFC. I like reading jargon-filled specs–that’s how I learnt most about CompSci, and I can’t imagine anyone else does as well. That’s why I wrote this! 

  4. I might replace these with pretty graphics later, but I guess this works for now, right? 

  5. An Authorization Grant could be username & password, which would come directly from the Resource Owner. 

  6. As with a lot of things, the RFC is broad enough that this actually includes all possible extensions–there are four types defined in this RFC. 

  7. Exactly how a lot of tokens should work is (sadly?) outside the scope of our lovely RFC13. Authorization Codes, Access Tokens, Refresh Tokens, and more are essentially free to implement however you prefer, except that they have to fulfill certain requirements. 

  8. See also the JWT profile for OAuth 2.0

  9. Yes, this is the normal flow where everything goes according to plan. I copied this from the RFC, and they include a non-expired Access Token flow before showing the flow for the expired Token. Probably to show a more realistic scenario?

    These still wouldn’t happen right after each other though! 

  10. This is where the Authorization Server can return an error when the Resource Owner’s authorization has been revoked. 

  11. I honestly don’t know what this means at this point. If anyone knows, send me a tweet–please! 

  12. These footnotes are quickly growing to be longer than the document itself. 

  13. And the RFC authors are very happy to tell you that!