OAuth2 in human terms

When browsing the internet for information about OAuth2, it proves to be quite a feat to find articles that are both comprehensive and comprehensible.

Indeed, OAuth2 is based on a set of somewhat less than trivial principles that are, however, applied in a number of different use cases each presenting certain peculiarities, complexities and/or simplifications.

So, we thought we’d give it a shot and try to explain OAuth2’s guiding principles and – in a subsequent series of blogposts – their application in a number of commonly occurring use cases.

Let’s start by suggesting a metaphor to explain some of the basic principles. Bear in mind that a metaphor – by definition – should not be interpreted literally and seldom fully matches its subject.

Here we go:

Bob Books (Resource Owner) likes books (Resource). He likes them so much that he orders multiple books each week online. Because Bob Is not always at home, he prefers not to let them deliver at home, but in a warehouse (Resource Server) where he rents some personal space.

The warehouse obviously wants to make sure that access to products within the warehouse is only granted to parties with appropriate authorizations. However, the warehouse wishes to concentrate on their core activities and does not want to be bothered with the management of credentials, authorizations etc. To that end, they work together with a security company (Authorization Server) that has a small office with a security guard at the warehouse reception desk. The security guard’s task is to verify people’s credentials (identify and authenticate) and authorizations (scope) and eventually hand out an access badge (Access Token).

  • That badge is valid for a limited amount of time e.g. only 1 hour.
  • The badge only gives access to the owner’s space in the warehouse (scope).

Whoever wants to fetch products from the warehouse must present an appropriate badge (no ID, no passwords, … only this badge) to the warehouse clerk. The clerk then will get the requested products from the owner’s space.

Now, Bob has several possibilities to get to his books.

Access without delegation (without OAuth)

When Bob wishes to get his books, he first phones to the guard. After proving his identity (e.g. using a password), the security guard sends him a an access badge by mail. With that badge, Bob can now go to the loading area where a warehouse clerk will get the books Bob wants from Bob’s space.

Drawback : It’s a lot of hassle for Bob to carry all those books. He’s interested in reading, not carrying!

In IT Terms : A user accesses an API directly.The user asks an “API key” by providing his credentials (e.g. Basic Authentication), and uses that API key in every API request. 

With delegation (with OAuth)

Scenario 1 (Implicit)

Bob buys so many books that he can’t carry them anymore. He needs someone else to help him with that. He ask his friend and roommate Tom Transport (Client) to help him.

Bob calls the security guard. After proving his identity, the security guard sends the badge to his home address. As Tom lives in the same house, he can pick up the badge and use it to get the books. Bob can stay at home now!

Limitation : Bob and Tom need to live in the same house

In OAuth terms : grant type “Resource Owner Credentials”. E.g. A user (Bob) uses a (local) Windows application (Tom) to access an API. The user enters his personal credentials in the application so the application can request an access token at the authorization server. Only to be used if the user cannot communicate with the authorization server directly!

Scenario 2 (Resource Owner Credentials)

Bob can’t be bothered to accompany Tom anymore. He trusts Tom enough to give him his ID card (careful!) so Tom can fetch the books by himself.

At the guard’s desk, Tom shows Bob’s ID card. The guard was already informed somehow that Bob allows other people to use his ID card. Tom will, however, have to present his own ID card to the guard upon which Tom will receive a badge. Having obtained a valid badge, Tom can proceed to the loading area and get Bob’s books.

Advantage : Bob doesn't have to communicate with the security guard.

Drawbacks :

  • Bob needs to fully trust Tom, since Tom can impersonate Bob now as Tom has Bob’s ID.
  • Bob cannot restrict Tom to only getting his books in the warehouse. There may be other goods from Bob there.

In OAuth terms: grant type “Resource Owner Credentials”. E.g. A user (Bob) uses a some application (Tom) to access an API. The users enters his personal credentials in the application so the application can request an access token at the OAuth server. (to be used with the utmost caution and if no other possibilities exist!)

Scenario 3 (Authorization code)

Bob has his voice back and changes his password as Tom really shouldn’t have it. They go back to scenario 1 (Implicit).

Now Tom moves out. This means that Tom doesn’t have immediate access to the badge anymore: Bob would need to send the badge by mail to Tom. However, Bob doesn’t trust the postal service. Any postman could open his letters, copy the badge and use the copy to steal Bob’s books.

Instead of directly requesting a badge from the security guard, Bob requests an authorization code. This is a time limited code that can be used only once to request a badge, and only by Tom . Bob sends the authorization code to Tom by mail. Upon reception, Tom phones the security guard, gives the authorization code and proves his own identity. The guard sends the badge by mail to Tom. Now Tom can get Bob’s books.

If the postman intercepts and copies the authorization code, he can only steal the books as long as Tom didn’t use the code, or that the code didn’t expire. Assuming that Tom is very fast, the security risk is much lower than before.

Advantage : The communication between Bob and Tom is less security sensitive. The badge cannot be intercepted. (Assumption is made that the exchanges with the security guard are secure)

In OAuth terms : grant type “Authorization Code”. E.g. A user (Bob) uses a server-side web application (Tom) to access an API. The user needs to request an authorization code at the authorization server (security guard). The web application uses the authorization code to request an access token (badge). Even if the connection between user and web application is not secure, an attacker can only intercept the authorization code, which will be invalid by the time he tries to use it.

Peter Oosterlynck & Mathieu De Zutter