Protecting REST APIs with OAuth 2.0

What is OAuth 2.0

If you are software developer on web, chances are you have heard of OAuth 2.0. It is a security protocol used to protect a large number of web APIs. OAuth 2.0 allows a software to access web APIs. In many ways OAuth 2.0 can be considered as a “valet key” for API resources, not all cars will have a valet key but valet key provides an additional security for your car. You can restrict access with valet key as ignition only and prevent access to glove box and boot. Similarly with OAuth 2.0 you can you can limit access to your web resources.

For example you have a database and a Restful APIs to perform create,read,update,delete operation on this database. Obviously we do not want anyone with the URL to perform these operation. OAuth 2.0 helps you to solve this problem.

The OAuth 2.0 authorisation framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf.

OAuth 2.0 allows us to access the resource with a JSON Web Token (JWT). Let us unpack this statement and and see what is JWT token and who provides it, what are the encryption or encoding standards used to protect the token from anyone impersonating it.

Actors in OAuth 2.0

OAuth 2.0 is all about getting access to resources or in other words allowing an application to access the resources on behalf of an end user. Now let us see who all are the participants in this authorisation flow.

  • Resource owner -A resource owner is a person sitting with a web browser. Resource owner can be considered as an end user.
  • Client-Client is a software that need to access some resources. In case of a javascript application client and resource owner will be same. Twitter application in your mobile phone is a client getting tweets from the apis provided by twitter.
  • Authorisation server- Authorisation server provides JWT tokens for authenticated clients. Using this token required resources can be accessed.
  • Protected resource- This can be an API server which provides some kind of service. Service can be a database operation,downloading a file,triggering another application. In the below diagram protected resource is shown as locked.

Components in OAuth 2.0

We have already seen the actors involved in authorisation flow now let us see what are the components in OAuth 2.0.

  • Access token- It is an artefact provided by the authorisation server to the client. An access token or simply token indicates clients right to access the resources. The client’s job is to receive the access token and proceed with this access token to protected resource.
  • Scopes- They are certain set of access rights at a protected resource. Scopes are important mechanism in providing access rights to the client. Scopes are defined by protected resource based on the API it is offering. Taking our database example API defines several scopes for reading, updating deleting the database. Based on the scope of token received different database operations can be performed. For example if the token received has read and update scope it,client cannot perform an update operation on the database using provided API.
  • Refresh token- Refresh tokens are used to gain new access token without involving resource owner. Access tokens will have an expiration period, so if the access token got expired client can use refresh token to gain new access token. Refresh tokens are never sent to the protected resource. Refresh tokens can also be used to down scope the access, for example down scope from all operation on database to read only.
  • Authorisation grant- The process of giving access to a protected resource using oauth protocol is called authorisation grant. Every successful authorisation grant will result in client getting a token.

Authorisation grant types

OAuth 2.0 has many methods for getting access tokens, designed for different use cases.

  • Implicit grant type- Implicit grant type is used for application that has no distinction between client and resource owner. For example a javascript application running on web browser. Implicit grant type use front channel communication for getting token, we will see later what is a front channel communication. In this method client inside web browser uses an authorisation method such as username and password already created in the authorisation server to get a access token. Using this token protected resources can be accessed. The key shown in the figure is authorisation credentials provided by client to the server.
  • Client credential grant type- What happens in a case where there is no explicit resource owner, such a case could arise in a situation where some back end servers require access token. In such case clients acts on its own behalf.
  • Resource owner credential grant type- In this method resource owner trades with client with username and password, with this username and password client authenticate with the authorisation server and will acquire a token.

Interaction with actors and components in authorisation flow

We have already seen different components and and actors in oauth 2.0 now let us see how communication takes place between these actors and components. Let us see two different communication method front channel and back channel communication for authorisation grant.

  • Back channel communication- In this method authorisation server provides a token endpoint for the client to make requests. Client will make a call to the authorisation server with a form encoded parameter and server responds with a JSON object containing token. All the communication takes place through the back channel, we can see from the figure that no browser is involved in the authorisation grant flow.
  • Front channel communication- Front channel communication is a method were communication takes place via a web browser. This communication takes place using HTTP redirection and callback.

For example the client will send an HTTP redirect to the browser containing required information. The target of redirection is to a server with query parameters. A sample URL is shown below.

Location: http://localhost:9001/authorize?client_id=oauth-client-1&response_type=code&state=843hi43824h42tj

Server will parse this URL, and server will redirect to the browser with a redirect uri. Browser will follow this uri and will be served by the client application. A sample OAuth call back is shown below.

Location: http://localhost:9000/oauth_callback?code=23ASKBWe4&state=843hi43824h42tj

OAuth tokens

Let us give a quick glance at what we have learned so far we looked at the actors and components in oauth 2.0 and how these components communicates with each other and every successful communication results in getting a token. Now how do these tokens contains all the information we need is there any encoding or encryption standard applied to these tokens or what is the structure of these tokens.

Unsigned JWT tokens


Above given is an example of a sample unsigned JWT token separated by a period (.) now let us separate the token into two parts based on the period symbol.


Each of these value is a JSON object encoded using BASE64 encoding method , first part of the token is called header and second part is the actual payload. Now let us decode the header using a base64 decoder and see what does it contains.

"typ": "JWT",
"alg": "none"

The type indicates the type is JWT token and “ald:none” indicates it is an unsigned token. Now let us see what is in the payload of JWT token.

"sub": "1234567890",
"name": "Jack Reacher",
"admin": true

The payload part of a JWT token contains all other information needed. We can add the necessary information in these token. In addition to these structured data JWT provides a set of claims, these tokens provides a set of operations using these tokens. The below diagram shows some of the claims.

JSON object signing and Encryption (JOSE)

Some of you may have noted that the unsigned token we created earlier was a terribly insecure thing, like any one could create such a token and send to the protected resource, some naive server may accept it and return the resource

Symmetric signatures using HS256

One of the method to prevent such attack is symmetric signing your token with an encryption algorithm and share your secret key with the authorisation server and protected resource. So the header of the token would contain.

"typ": "JWT",
"alg": "HS256"

The above header indicates that it is signed with an HS256 encryption algorithm. Now the all overall structure of the token would look like Header.Payload.Signature


Asymmetric signatures using RS256

In the previous example we saw the secret key is shared between authorisation server and protected resource which means both of them can generate access token, which we do not want, so we use an asymmetric encryption and only share the public key with the protected resource. Authorisation server will have both public and private keys.