API Basics - oAuth at a glance

In this article we are going to browse the basics every programmer should have about oAuth

oAuth in a nutshell

  • oAuth stands for Open standard for Authorization
  • It’s a token-based protocol, the token is a key to talk with the API Server
  • It uses an access token, often a JSON Web Token (JWT, another open standard)
  • oAuth has different versions. oAuth2 is simpler to use than previous versions
  • No backwards compatibility: oAuth2 server is not compliant with oAuth1 client and the other way around

Authentication vs Authorization

Authorization is Access, Authentication is Identity

oAuth provides just authorization to consume the API. It gives you the key to open the door, but does not give API a way to know who you are

OpenID Connect is a standard solution which can complement oAuth 2.0 with authentication (identity)

You can easily use a SaaS/PaaS system to add authentication to your oAuth implementation

Using oAuth with your API

If you want to efficiently secure your API, you may use an oAuth Server, which will guarantee that you only consume the API with an access token, instead of communicating your credentials in each request for example. This is more secure.

The following schema shows the principle behind using oAuth to consume an API :

Web architecture with oAuth Server
  1. you require an access token with an authorization request (POST /token)
  2. the authorization server (oAuth server) returns an access token
  3. you can now create requests encapsulating access token for the API
  4. API returns specified responses

JSON Web Token (JWT) access token

the JWT access token is composed of three parts :

  • Header : information about encryption used, to know how to verify properly the access token
  • Payload : set of claims (as oAuth Server, Expiry, Not usable before, Client Id, Scopes (helps to limit access to the API), custom data…)
  • Signature : used to make sure that the access token and especially the payload is not tampered by an attacker or else

It is finally encoded in a base64 string

How is an access token validated

To validate an access token, we need to ensure it is coming from the good oAuth server.

To do that, the oAuth server exposes a public key when using an asymmetric encryption, or you must know the key when using a symmetric encryption.

JWT (see: https://jwt.io) can be signed using an HMAC or an RSA encryption.

In any case the access token must be validated to ensure the identity of the authorization server that delivered it. To do so the signature part of the token is recreated by the resource server and compared to the one provided in the token. If it’s the same, everything's okay !

For example, the method for RSA to recreate the signature from the resource server is

base64UrlEncode(header) + "." +


Useful tools to use during your API development

  • swagger : auto-documentation showing what is exposed by the API
  • postman : chrome extension to forge HTTP queries

Specifications :