Skip to main content

OAuth 2.0

OAuth 2.0 is the industry-standard protocol for authorization and it was developed to provide a universal way to secure communication between different services. The standard provides guidelines to build the authentication service but leaves many decisions to the implementers. Nevertheless, most of the web services that do implement OAuth 2.0 for their API come to many of the same decisions, and so most of the implementations look very similar.

In this brief guide, we are going to illustrate the basic concepts of the standard, it should contain all you need to know about OAuth 2.0! 😁

A detailed description of our implementations of the OAuth 2.0 flows is available here:

Do I need to read this?

Despite this mini-guide being optional and not necessary to use our API, we recommend reading it as it clarifies many concepts of the protocol that you will encounter very often.

In the following sections, you can find a concise description of the fundamentals of the OAuth 2.0 protocol that will help you to understand some concepts widely used in our documentation. If you want to further investigate the OAuth 2.0 standard, feel free to check out the Additional Resources section, where we collected a lot of useful resources that should help you to fulfill your thirst for learning! 😌

🎉  Who’s joining the party?​

Let’s start by introducing the subjects that take part in the authentication process:

First of all, we have the app that you developed, which we’re going to name Client Application. It’s the applicant who wants to access the user’s data.

This allows us to introduce the second subject, the End-User. He’s the owner of the data you want to access, and we need his authorization to do so.

The user’s data in this case are stored in Fatture in Cloud’s server, which we’re going to name Resource Server. To access this data we need a token, a string that acts as permission to ask the Resource Server to provide us the information we need.

The token will be provided to us by the last subject, the Authorization Server. This can be a separate entity from the Resource Server, but in our implementation, they are technically the same. For the purpose of this guide though, we will assume that they are two separate entities.

🔑  Wait a minute, what are tokens?​

Tokens are like keys, they allow the possessor to perform certain operations. There are two main types of tokens:

  1. The Access Token is the final token the Client Application will use to request data to the Resource Server. It expires, so it is required to request a new access token to continue using the APIs.
  2. When an Access Token expires, you don’t need to redo the whole process again. The Refresh Token allows the Client Application to request a new Access Token directly to the Authorization Server. It can also expire, but its expiration time is usually much larger with respect to the Access Token.

When also the Refresh Token expires, you need to re-execute the Authorization flow to obtain new tokens.

🔀  OAuth 2.0 flows overview​

OAuth 2.0 specifies several Flows that can be used to retrieve those tokens. Each one of them is specialized for a different use case:

  • Implicit Flow
  • ✅  Authorization Code Flow
  • Client Credential Flow
  • Resource Owner Password Flow
  • Assertion Flow
  • ✅  Device Authorization Flow

Currently, the Fatture in Cloud API supports the Authorization Code Flow and Device Authorization Flow.

🔐  Authorization Code Flow​

The Authorization Code Flow is the most common of the OAuth 2.0 grant types. Like the other flows, it describes how the application can retrieve the token required to interact with the APIs.

Wanna get technical?

Our implementation of this flow can be found here.

At a high level, the flow can be divided into the following steps:

  1. The End-User wants to use the Client Application.
  2. The Client Application wants to access the user’s data, so it contacts the Authorization Server to get permission.
  3. The Authorization Server asks the End-User whether to grant the requested permissions to the Client Application.
  4. If the End-User approves the request, the Authorization Server redirects him to the Client Application with an Authorization Code in the query string.
  5. The Client Application contacts the Authorization Server to exchange the Authorization Code with an Access Token. In addition to the Access Token, the Authorization Server will provide a Refresh Token.
  6. The Client Application uses the received tokens to access the user's data.

As you can see, the Authorization Code flow introduces a new token called Authorization code. It is a short-living one-time use token generated by the Authorization Server, and its only purpose is to be exchanged for an Access Token.

Since the Authorization Code Grant requires the exchange of the Authorization Code for the Access Token, it provides an additional layer of security not present in other grant types. The code exchange step ensures that an attacker isn’t able to intercept the Access Token, given that the Access Token is always sent via a secure backchannel between the Client Application and the Authorization Server.

The authorization step is performed directly by the End-User on a page provided by the Authorization Server, so the application needs to expose a Redirect Endpoint that will be used by the Authorization Server to send the Authorization code.

📱  Device Code Flow​

The Device Code Flow is an authorization process designed explicitly for browserless and input-constrained devices such as smart TVs, media consoles, picture frames, printers, or hardware video encoders. It can be also used for use cases where the Client cannot safely store a secret (making it impossible to use the Authorization Code Flow), such as CRM plugins or pure frontend applications.

Wait a minute!

To enable this flow for your application, you have to contact us! We would like to know why you want to use the Device Authorization flow before activating it.

The Device Code Flow tries to overcome the restrictions that affect the Client Application by asking the End User to manually access a web page, where the authentication and authorization steps will be performed; this second device will usually be a PC or another device browser-provided, where the End User will be able to open the page and perform the requested operations easily.

We can then split the Device Code Flow into two different paths, one for the device where the Client Application is running (named "Device Flow") and one for the secondary device (named "Browser Flow"); the two flows will be executed parallelly until the End-User authorization will be provided.

The Device Flow is executed on the device where the Client App is running, e.g. the device with the restrictions mentioned above.

The steps are the following:

  1. The End-User wants to use the Client Application.
  2. The Client Application wants to access the user’s data, so it contacts the Authorization Server to get permission.
  3. The Authorization Server sends a verification URL and a code to the Client Application, which displays them to the End-User.
  4. The Client Application starts polling the Authorization Server for the authorization result. This process continues until the End-User approves the request.
  5. The first Client Application's check following the End-User approval will be successful, and the Authorization Server will provide the Access Token and Refresh Token to the user.
  6. The Client Application uses the received tokens to access the user's data.

The Browser Flow will be executed manually by the user on a secondary device of his choice, and it can be placed between steps 3 and 5 of the Device Flow:

  1. The End User will open the verification page, writing the verification URL on a secondary device of his choice.
  2. The page will require the End User to insert the code and to give permissions to the Client Application to perform the operations on the API

📚  Additional Resources​