oAuth2 is the standard way of exposing your API’s internally and externally via standard authorization flows. As of 2016, OAuth2 and OpenID Connect are defacto standards to secure your APIs.
Below are most common use cases handled by oAuth2.
- Web Applications (3rd Party or Internal) requiring api access on user’s behalf
- Browser based applications (3rd Party or Internal) requiring api access on user’s behalf
- Native Mobile Applications (3rd Party or Internal) requiring api access on user’s behalf
- Web Applications (3rd Party or Internal) requiring api access on their own behalf
Overall, oAuth2 provides specific authorization flows for web applications, desktop applications, mobile phones, native applications and other devices like tv,printer etc. It also supports extending the protocol to provide compatibility with future device requirements.
From technical point of view, most of the exposed API’s use oauth2 style model where consumer app of the api is handed over the token (some unique random string) per user and consumer app will use that token to perform operations on protected http resources for that user.
In early 2000, as web applications were getting very popular, new use cases were appearing. One of the use case was one web application accessing user’s data from different web application to do interesting things. For example application like flicker (photo sharing app) which required user’s photo’s from user’s google account
- User has an account in google where his photos are stored
- User creates an account in Flickr
- Flickr asks user to enter google username/password on their websit
- Flickr takes the user’s username/password, login in google account using google’s custom clientLogin protocol and download the photo’s in user’s Flickr accoun
This was first step to social integration but had it’s own limitations. User’s had to share their password with Flickr in this case. Other drawbacks were on password change, applications like Flickr would have broken. Only way user could have revoked the access was by changing his password which was also not very good approach
It resulted in companies like google, yahoo to develop custom protocols like Google’s AuthSub & Yahoo’s BBAuth. Typical flow in these custom protocol’s was as follows
- Flick creates an app in google account
- User has an account in google where his photos were stored
- User creates an account in Flickr
- Flickr redirects user’s to google accoun
- User login in the google account and grant access to Flickr ap
- Flick app would get a token which it will use to get the user data in subsequent requests by invoking provider apis(google)
It was a great first step but it was time consuming for developer’s to understand & integrate custom protocol of each identity/api provider(google,yahoo) with their applications. Hence, Major api provider’s decided to create a standard protocol for these web based authorization flow’s. That’s how oAuth1.0 came in picture and eventually oAuth2.
This is the time where IT world was also moving towards API driven economy.
oAuth1.0 was developed in 2007 and had some inherent issues. oAuth2.0 addressed oauth1.0 limitations. For example, it imposed strong cryptographic requirements on clients, it did not support revocation all that well, and its model had important architectural limitations that made it unsuitable for being used outside the web-app-to-web-app-server communications case. Those limitations made it hard for OAuth to be applied in many business scenarios.
- Allows better support for non-browser based clients
- No longer requires client applications to have cryptography
- oAuth 2.0 tokens are short lived
- Client Id / Client Secret - generated by authorization server on registration. In simple words, generated by API provider for API consumer. Based on these attributes, API provider can identify API consumer.
- Access Token - token which is generated based on client authentication and client id & secret. Also, known as Bearer Token.
- Refresh Token - Refresh token used to get access token. Refresh tokens are long lived.
Before diving in grant types, lets go over common roles in oAuth2
- Resource owner - Entity who owns the data. typically an user.
- Client - The mobile app, web site, etc. that wants to access data via API’s on behalf of the Resource Owner.
- Resource server - The service that exposes the data via api i.e API Provider
- Authorization server - oAuth Server which issues tokens in exchange of username/password, client credentials etc.
Some API providers may use the same application for both the authorization server and resource server.
On High level, access token is issued in exchange for a valid grant. oAuth2 supports different grant types to support various use cases:
- Password - Exchange user name/password to get the access token. Great for trusted Browser based and mobile applications where front end and backend is owned by same company or entity. Allows CRUD operations on user level protected HTTP resources via API’s.
- Authorization Code - Redirect user to the authorization server to authorize client which results in issue of access token. Great for apps running on web Servers. Allows CRUD operations on user level protected HTTP resources via API’s.
- Implicit - Redirect user to the authorization server to authorize client which results in issue of access token. Great for 3rd Party Browser based and mobile applications. Allows CRUD operations on user level protected HTTP resources via API’s.
- Client Credentials - Client gets access token in exchange of its own identfier and password. Great for application level CRUD operations access.
Extension Grant Used to extend the OAuth 2.0 grant types for specific scenarios (e.g. the SAML bearer extension grant).
SAML Based Extension grant - Exchanges user SAML token to get Access token to invoke the API. Most commonly used for Single Sign on Scenarios where company does not own the user’s identity (username,password) but want to use API driven architectures.
JWT Based Extension grant - Exchanges user JWT token to get Access token to invoke the API. Most commonly used for Single Sign on Scenarios where company does not own the user’s identity (username,password) but want to use API driven architectures.
High level flow is as follows:
- User logs in into the application with username password.
- Application code on client side makes POST request on token endpoint with username and password and grant type as ‘password’.
- Server replies with access token.
- Application code on client side stores the token in local cache and sends the token on each subsequent api as authorization header.
- Server validates the token and respond back with data or error message.
Since the entire source code is available to the browser, they cannot maintain the confidentiality of their client secret, so the secret is not used in this case.
- If you or your company owns the users identity (i.e. username,password etc.) and you want to create Mobile or web applications on top of your api’s. Hence, it works great for API driven apps.
- Can be used in place where API’s are protected by HTTP Basic access authentication. With Basic auth, application has to have access to user’s password continuously in comparison to Resource owner flow where password is required only once.
The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for confidential clients i.e. The applications which can keep client id/secret secure on the server side.
- When API security is of utmost importance and the OAuth token shouldn’t be leaked to the browser, where the user may get access to it.
The implicit grant type is used to obtain access tokens (it does not support the issuance of refresh tokens) and is optimized for public clients known to operate a particular redirection URI.
- The browser is strongly trusted and there is limited concern that the access token will leak to untrusted users or applications.
- If an application wants to do CRUD operations on the data stored where application itself is the owner of the data. ex. if application is the owner of some storage api where it can use client credentials issued by API to perform CRUD operations.
- When a resource owner has granted an application access to their resources out of band. Used only in specific cases.
- Used commonly for B2B and intra-company Server to Server api invocations.