Introduction to OAuth

Open Authorization protocol which abbreviates to OAuth is a widely used authorization protocol. First of all, let me explain what problem is being solved by OAuth with a simple and common example.

Let’s say I am using a photo editing application called “photo editor” and editing some photos. Also, I use an application called “photo viewer” to safely store my photos which I can view, upload and download. I am thinking of editing a few of the photos which I uploaded to the “photo viewer” application sometime back using the “photo editor” application. So my requirement is now to edit photos that reside in the “photo viewer” application using the “photo editor” application. This is one of the simple examples I started with to learn OAuth. There are two solutions that came to my mind at the first glance.

1. I download the required photo from the “photo viewer” application and I ask from the “photo editor” application to get it edited.
2. I share credentials of the “photo viewer” application with the “photo editor” application and ask the “photo editor” to get the photo and edit it on my behalf.

Thinking on these approaches further, there are several issues associated with them.

In the first approach, two applications are not connected with each other to perform the job anyway and we cannot consider it a programmatic way of doing it. In the second approach, two applications are connected but the following issues can be observed.

1. Since the “photo editor” application accesses the “photo viewer” application by using its credentials, the “photo editor” application should maintain the credentials on its own.
2. Sharing the credentials means the “photo editor” application will get full access to the “photo viewer” application and there is no controllable or collaborative way of doing it.
3. Even though I require to revoke the given access to “photo editor” later, the only way to do that is to change the credentials of the “photo viewer” application.

OAuth resolves the above issue by defining a way to delegate the access of a protected resource on behalf of the resource owner or on its own. Before digging into the technical aspect of OAuth, first understand a few terms which should be understood by anyone who learns OAuth protocol.

Following are the key roles in OAuth along with their responsibilities.

1. Protected resource — Resource that a third-party application requires to access to perform a particular task.
2. Resource owner — Entity that owns the protected resource. The resource owner is capable of granting access to the protected resource.
3. Resource server — Entity which holds the protected resource. Access requests for the protected resource with access tokens are served by the resource server.
4. Client — Third-party application which requests access to the protected resource with the authorization of the resource owner.
5. Authorization server — Issue access tokens. This is done after getting the resource owner’s permission to give access to its protected resource for a third-party application.
6. User agent — The entity that the resource owner uses to make the interaction with the client. This can be a web browser or a native application.

Access token and Refresh token are two types of tokens used in OAuth.

Access tokens — Access tokens are simply the credentials used to get access to the protected resource. This represents the permission given by the resource owner to get access to its protected resource by the third-party application. The access token contains a specific scope and duration which is granted by the resource owner and enforced by the authorization server. Moreover, the access token is an abstract layer that replaces different authentication constructs such as username and password and it provides a simplified way which the resource server can work with. Instead of working with different types of authentication mechanisms, the resource server can use a unified way of authenticating whoever third parties want access to the protected resource resides within it.

Refresh token — The use of a refresh token is to get a new access token when the access token is expired or get an additional access token identical to the previous one or with lesser in scope. Refresh tokens are issued and shared only with the authorization server and never go to the resource server.

As we discussed earlier, an access token is a form of credential which is required to get access to the protected resource. To request an access token, the client should have the resource owner’s authorization which is known as the authorization grant. There are four main grant types defined in the OAuth scope. Let’s detail each grant type and how they differ from each other.

Authorization code grant

In the authorization code grant type, an authorization code is obtained to represent the resource owner’s authorization to access the protected resource. The authorization server acts as an intermediary between the client and resource owner to get the authorization grant. Instead of the client directly asking permission to access the protected resource from the resource owner, the resource owner is redirected to the authorization server via the resource owner’s user agent. The authorization server authenticates the resource owner and gets the authorization from the resource owner to give access to its protected resource. With this approach resource owner is authenticated only with the authorization server and credentials are not getting exposed to any other party. The following diagram illustrates the flow of the authorization code grant.

1. Client wants to access the resource owner’s protected resource.
2. Client initiates the flow by redirecting the resource owner’s user agent to the authorization server’s authorization endpoint. The client includes client identifier, requested scope, local state, and redirection URI (Redirect URI points out where the resource owner’s user agent should be sent back once the process is completed) in the request.
3. Authorization server authenticates the resource owner and gets its permission to grant access to the protected resource. The authorization code represents the obtained permission for accessing the resource.
4. User agent is sent back to the redirect URI with the resource owner’s decision (whether the permission is granted or not).
5. Once the client has the authorization code (if permission is granted), it requests the access token from the authorization server’s token endpoint.
6. At the token endpoint, the client is authenticated and the authorization code is validated. Based on that access token is issued to the client.
7. Client requests the resource by giving the obtained access token to the resource server.
8. Resource server provides access to the protected resource.

Implicit grant

This is a simplified version of the authorization code grant. No authorization code is involved and instead access token is directly obtained. The client application is obtaining the access token as a result of authorization. Unlike the authorization code grant, the client is not authenticated by the authorization server. It relies on the presence of the resource owner and a valid redirect URI. An access token is issued once the authorization is obtained from the resource owner and encoded in the redirect URI and sent to the client. However, this may cause exposing the access token to the resource owner and the other applications which reside on the same device. Let’s look into the steps involved with the following diagram.

1. Client wants to access the resource owner’s protected resource.
2. Client initiates the flow by redirecting resource owner’s user agent to the authorization server’s authorization endpoint.
3. Authorization server authenticates the resource owner and gets its permission to grant access to the protected resource.
4. Resource owner’s user agent is sent back to the client with the Access Token encoded in the redirection URI.
5. Client gets the access token and asks for access to the protected resource from the resource server.
6. Resource server provides access to the protected resource.

Resource owner’s credential grant

In this approach resource owner’s credentials (username and password) are shared with the client. This is done based on a trust relationship between the resource owner and the client. Further, this approach is to be used only when there are no other alternatives available to use. The following diagram illustrates the flow of the resource owner’s credential grant.

1. Client wants to access the resource owner’s protected resource.
2. Client calls the authorization server with password credentials given by the resource owner. The resource server authenticates the client and also validates the resource owner’s credentials given by the client.
3. Upon valid credentials, the authorization server gives the access token to the client.
4. Client asks for access to the protected resource by giving the obtained access token.
5. Resource server grants access to the protected resource.

Client credentials

The client is requesting the access token only by providing its credentials or any other supported means of authentication. In there, the client acts on behalf of the resource owner or the client can be also a resource owner. For only confidential clients this approach should be used. Let’s see the flow of this grant type to get a more clear understanding.

1. Client wants to access the resource owner’s protected resource.
2. Client directs to the authorization server and gets authenticated with the authorization server.
3. If the authentication is successful, the client gets the access token and then requests access to the protected resource.
4. Resource server permits access to the protected resource.

I am sure now you have a basic understanding of the OAuth framework, main keywords, and four main grant types and their flows. Probably the very next question that pops up is how do we select the best flow for our applications. The next session will walk you through in which scenarios each approach is applicable.

The decision of which OAuth flow should be implemented in your application mainly depends on the type of your application. Other than that factors like trust level between the resource owner and client, the required level of end-user experience also should be considered.

To start with we can check that the client is also a resource owner and it is a machine-to-machine authorization. If so there is no need for end-user authorization. In this case, client credentials can be used to obtain the access token.

If the client is a web application that is hosted on a server, the authorization code grant should be used. Both the access token and the refresh token can be obtained. Since the access token is directly passed to the server which hosts the client application, there is no exposure of the access token to the resource owner or any other party.

In the next point, we can check that the client and the resource owner have an absolute trust relationship. In that case, the client can be trusted and resource owners’ password credentials can be shared with the client. Once the password credentials are shared with the client it is sent to the authorization server and get the access token. This flow is recommended only when no redirect-based alternatives are available to use.

In the cases where the client is a Single Page Application (SPA) that runs on browsers using JavaScript like scripting languages, the implicit grant type can be used. But with the inherent security threat of exposing the access token to other parties, Authorization Code Flow with Proof Key for Code Exchange (PKCE) is recommended to be used. Further for native/mobile application type clients also Authorization Code Flow with PKCE is recommended.

Hope you grab some knowledge on OAuth to continue the learning. Thank you for reading.

References

RFC 6749 - The OAuth 2.0 Authorization Framework

Auth0