Understanding OAuth 2 hybrid flow

Understanding OAuth 2 hybrid flow

Photo by kazuend on Unsplash

What do we mean by a flow?

OAuth is a series of protocols which define various ways of authorising users to access data and functionality. These different ways of authorising a user are known as flows, and they have specific names to make it easier to talk about them.

What is the Implicit Grant flow?

In the Implicit Grant flow, calling the /authorize endpoint returns an access token. This token grants access to data, and when it expires another token is requested from the same /authorize endpoint. Only the initial token request involves the user signing in, the subsequent requests are done in the background using an iframe. However, that process relies on third party cookies, for which reason Microsoft say

the implicit grant flow is no longer a suitable authentication method

Source: Microsoft identity platform and implicit grant flow

This problem is solved by the Authorization Code flow, which we will cover below. If you want to read more about the Implicit Grant flow, it is explained in detail by Microsoft in their article Microsoft identity platform and implicit grant flow.

What is the Authorization Code flow?

The key change with the Authorization Code flow is that calling the /authorize endpoint does not return an access token. Instead it returns an authorization code. What's the difference? The authorization code cannot be used to access data or functionality. The only thing it can be used for is to be passed to a second endpoint, the /token endpoint which returns the actual access token, along with a refresh token. When the access token expires, the refresh token is sent to /token which returns a new access token and a new refresh token. This means that after the initial authorisation, there is no need for subsequent requests to the /authorize endpoint.

The Authorization Code flow is explained in detail by Microsoft in their article Microsoft identity platform and OAuth 2.0 authorization code flow.

What is the Hybrid flow?

The Hybrid flow combines elements of both the Implicit Grant flow and the Authorization Code flow. The client application has a Client Secret which it stores securely. (This cannot be achieved with a single-page application or any other type of application which has all its data on the user's device. It can only be used for an application such as a web API, where the application data is stored securely on a server and cannot be accessed by the end user.) After the initial authorization request, the /token endpoint can be called using the Client Secret instead of a Refresh Token. (The Authorization Code from the /authorize endpoint must still be sent.)

Why would we use the hybrid flow?

Imagine a single page application (SPA) which calls an API, both of which you control and both of which should be authorised using OAuth. The SPA cannot store data securely, but the API can.

The Authorization Code flow can be used by the SPA because it doesn't rely on a Client Secret and it can use Refresh Tokens for getting new Access Tokens as they expire. The Hybrid flow allows the API to also use OAuth, even though it won't receive any Refresh Tokens, because the Client Secret can be used instead.

Summary

In a nutshell, the Hybrid flow is (as you might expect) intended to combine the benefits of both the Authorization Code flow and the Implicit Grant flow. Neither is suitable for authorising both an SPA and an API, but combining them in the Hybrid flow allows us to authorise both types of application.