How does it work?

Let's revisit our example scenario. You have just signed up for the service GoodApp, and now GoodApp would like to suggest contacts for you to add by looking at your Facebook friends. In the last chapter, we looked at the old model, where GoodApp would ask you for your username and password and use them to access your Facebook friend list on your behalf. We then looked at the new, superior model that uses OAuth 2.0 to achieve the same thing, but in a much more secure and manageable way.

The (simplified) workflow looks like this:

Here are the steps:

1. You ask GoodApp to suggest you contacts.
2. GoodApp says, "Sure! But you'll have to authorize me first. Go here…"
3. GoodApp sends you to Facebook to log in and authorize GoodApp.
4. Facebook asks you directly for authorization to see if GoodApp can access your friend list on your behalf.
5. You say "yes".
6. Facebook happily obliges, giving GoodApp your friend list. GoodApp then uses this information to tailor suggested contacts for you.

The image and preceding workflow presents a rough idea for what this interaction looks like using the OAuth 2.0 model. We will be curating this image and elaborating on particular steps, and sequences of steps, in order to build an increasingly accurate picture of the workflow as it works with OAuth 2.0. The first steps that we will examine more closely are steps 3-5. In these steps, the service provider, Facebook, is asking you, the user, whether or not you allow the client application, GoodApp, to perform a particular action. This is known as user consent.

User consent

When a client application wants to perform a particular action relating to you or resources you own, it must first ask you for permission. In this case, the client application, GoodApp, wants to access your friend list on the service provider, Facebook. In order for Facebook to allow this, they must ask you directly.

You may be familiar with this process already if you've ever tried to access resources on one service from another service. For example, the following is an example of a user consent screen that is presented when you want to log into Pinterest using your Facebook credentials.

Incorporating this into our flowchart, we get a new sequence:

Here are the steps:

1. You ask GoodApp to suggest you contacts.
2. GoodApp says, "Sure! But you'll have to authorize me first. Go here…"
3. GoodApp sends you to Facebook. Here, Facebook asks you directly for authorization for GoodApp to access your friend list on your behalf. It does this by presenting the user consent form, which you can either accept or deny. Let's assume you accept.
4. Facebook happily obliges, giving GoodApp your friend list. GoodApp then uses this information to tailor suggested contacts for you.

Notice how we've substituted the exchange of asking for consent with the process of presenting the user consent form to the user. When you accept this user consent form, you have agreed to allow GoodApp access to your Facebook friend list on your behalf. That is, you have delegated read-only authority for your Facebook friend list to GoodApp.

We can curate this workflow some more. There is a very important step in the preceding process that warrants a larger discussion. It is step 4 where GoodApp and Facebook finally exchange the information that has been requested. In the preceding diagram, we present it as a single step where Facebook gives the information to GoodApp. However, in reality, this is a much more complicated exchange that occurs, which depends on many factors. It is this step, actually, where the bulk of the book focuses since this secure and controlled exchange of information is at the crux of what OAuth 2.0 does. Let's take a closer look.

Two main flows for two main types of client

After you have granted permission for GoodApp to access your friend list on your behalf, an interaction must happen between GoodApp and Facebook to then exchange information. However, this interaction differs depending on the client application and its capabilities.

OAuth 2.0 supports the exchange of information in various ways through the use of different workflows. In OAuth 2.0 terminology, these are called grant types. There are two main grant types that OAuth 2.0 describes that facilitate the majority of OAuth 2.0 use cases. They are:

• Authorization code grant
• Implicit grant

The authorization code grant is often referred to as the server-side workflow, whereas the implicit grant is often referred to as the client-side workflow. To understand the difference between these two workflows and their purposes, we must understand the concept of trust.

Tip

The OAuth 2.0 Authorization Framework

The OAuth 2.0 specification actually describes two additional grant types: the resource owner password credentials grant and the client credentials grant as well as the ability to create your own custom grants to suit your needs. However, even with all of this flexibility, the implicit grant and authorization code grant are the ones most commonly used in practice in the consumer space, and so are the ones we will focus on in this book.

For more information on the other grant types defined by the OAuth 2.0 specification, see Appendix A, Resource Owner Password Credentials Grant, and Appendix B, Client Credentials Grant.

Trusted versus untrusted clients

When dealing with various OAuth 2.0 providers, there are only two levels of trust: trusted and untrusted. The categorization of a client into either of these trust levels is determined by two simple capabilities: the ability to securely store and transmit information. These two levels can then be summarized as follows:

• A trusted client is an application that is capable of securely storing and transmitting confidential information. Because of this, they can be trusted to store their client credentials, tokens, or any other resources necessary for their application.

  An example of a trusted client may be a typical 3-tier client-server-database application whereby the presence of a backend server often facilitates the secure storage and transmission of any confidential information.

• An untrusted client is one which is incapable of securely storing or transmitting confidential information. Because of this, they cannot be trusted to store their client credentials, or any other confidential information.

  An example of an untrusted client is a browser-based application, say, an HTML/JavaScript application, where there is no server available for which to securely store information. All information must be stored in the browser, which is fully accessible to the users and should be considered public.

Tip

The OAuth 2.0 Authorization Framework

In the OAuth 2.0 specification, the terms trusted and untrusted are referred to as confidential and public, respectively.

Notice that in the untrusted example, there was no mention of the ability to securely transmit the information. This is because such a browser-based application is unable to even securely store the information, which already makes it untrusted. Whether or not they are able to securely transmit the information is irrelevant at this point. Clients must be able to support both capabilities, not just one, in order to be considered trusted.

Tip

What about mobile?

Mobile devices are treated the same. Depending on the platform's ability to securely store and transmit information as well as the client developer's implementation, mobile devices can be treated as either trusted or untrusted.

For more information, see Chapter 10, What About Mobile?

Now that we know the major distinction between the two types of clients, let's look at the two different workflows that were designed for each: authorization code grant for server-side (trusted) flows, and implicit grant for client-side (untrusted) flows. We'll start with the implicit grant first because it is simpler.