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 :
- you require an access token with an authorization request (POST /token)
- the authorization server (oAuth server) returns an access token
- you can now create requests encapsulating access token for the API
- 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