OAuth 2.0 and Grant Types

Introduction

Security, in information technology (IT), is the defense of digital information and IT assets against internal and external, malicious, and accidental threats. Security is critical for enterprises and organizations of all sizes and in all industries. Weak security can result in compromised systems or data, either by a malicious threat actor or an unintentional internal threat.

Information security encompasses a broad set of strategies for managing the process, tools, and policies that aim to prevent, detect, and respond to threats to both digital and non-digital information assets. This includes several specialized categories, including the below.

Figure 1: It Security - Specialized Categories

Access Control

Access to protected information must be restricted to people, entities (systems) that are authorized to access the information. In many cases, the enterprises encompass heterogeneous systems that process the protected information, must also be authorized. This requires that mechanisms be in place to control access to protected information.

Access Control generally considered in below three steps:

Figure 2: Access Control

This document describes the OAuth 2.0 based access control and grant types.

OAuth 2.0 Authorization framework

Traditional access to protected data like basic authentication requires sharing the username and password to systems or third party applications. This creates a dependency on maintaining the user details and management (which user should access what) on the entity which is hosting the protected information. This might be an overhead on the particular entity (let us say resource server). The following diagram depicts the flow of accessing protected information with the described approach.

Figure 3: Basic Authentication - Access to Protected Information

With the above approach, there is a good possibility for threats (e.g. man in the middle etc.) since by possessing username and password anyone can impersonate the client. Also revoking access will only be possible by removing the user or user access control to protected information.

Introduction and Terminology

The OAuth 2.0 authorization 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. (https://tools.ietf.org/html/rfc6749)

Figure 4: OAuth 2.0 Authorization Framework - Authorization Layer

OAuth adds a new layer called Authorization Layer for enabling access for protected information for the clients.

Unlike the OAuth 1.0 protocol, OAuth 2.0 provides a rich authorization framework (not a protocol) with well-defined security properties.  However, as a rich and highly extensible framework with many optional components, on its own, this specification is likely to produce a wide range of non-interoperable implementations. In addition, this specification leaves a few required components partially or fully undefined (e.g., client registration, authorization server capabilities, endpoint discovery).  Without these components, clients must be manually and specifically configured against a specific authorization server and resource server in order to interoperate.

The following diagram depicts the abstract flow of OAuth 2.0 Authorization framework.

OAuth defines four roles: Resource Owner, Resource Server, Client, and Authorization Server.

Figure 5: OAuth 2.0 - Abstract Protocol Flow

Resource Owner (User): An entity capable of granting access to protected information. When the resource owner is a person, it is referred to as an end-user.

Resource Server (API Server): The server hosting the protected information, capable of accepting and responding to protected resource requests using access tokens.

Client: An application making requests to access protected information on behalf of the resource owner and with its authorization. 

Authorization Server: The server issuing access tokens to the client after successfully authenticating the resource owner and obtaining authorization.

Resource Server and Authorization Server interact with each other to verify the access tokens. There can be various levels of these interactions (3-legged OAuth, 4-legged OAuth, etc.).

Authorization Grants

OAuth 2.0 specification defines four grant types: authorization code, implicit, resource owner password credentials, and client credentials - as well as an extensibility mechanism for defining additional types.

Authorization Code Grant: The authorization code grant should be very familiar if you’ve ever signed into an application using your Facebook or Google account.

The client directs the resource owner (user) to an authorization server, the user will then be asked to login to the authorization server and approve the client. If the user approves the client they will be redirected from the authorization server back to the client with the authorization code.

The client will now send a request to the authorization server with authorization code and client credentials (id and secret) to generate a token. Finally, client can continue to use the token until it expires to access protected information from the resource server. Figure 5 depicts the same flow.

Implicit Grant: The implicit grant is a simplified authorization code flow optimized for clients implemented in a browser using a scripting language such as JavaScript. Implicit grant is similar to the authorization code grant but instead of authorization server returns an authorization code that is exchanged for an access token, the authorization server returns an access token.

Figure 6: OAuth 2.0 - Implicit Grant

Note: Implicit grant does not return a refresh token because the browser has no means of keeping it private

Resource Owner password credentials: This grant is a great user experience for trusted first party clients both on the web and in native device applications.

Figure 7: OAuth 2.0 - Resource Owner password credentials

Client Credentials: The simplest of all of the OAuth 2.0 grants, this grant is suitable for machine-to-machine authentication where a specific user’s permission to access data is not required.

Figure 8: OAuth 2.0 - Client credentials

OAuth 2.0 Authorization Grants – Use cases

Implementing Authorization Grants for APIs always depends on the type of consumer consuming the APIs. In some cases, this is also dependent on End User experience.

Authorization Grant: If the client application consuming the API has a backend or server-side component which can save the method for acquiring tokens then Authorization Code Grant is preferred. For example, if the client is a web application with a back end and resource owner (API owner) can issue the grant by confirming access.

Implicit Grant: If the client application consuming the API is a browser-based application without any back-end for saving the method for acquiring tokens Implicit Grant is preferred. For example, if the client is a web application with Angular JS. This involves the resource owner (API owner) to issue the grant by confirming access.

Resource Owner password credentials: If the client application consuming the API is browser-based application or Mobile Application without any back-end for saving the method for acquiring tokens this Grant is preferred. For example, if the client is web or mobile application with Angular JS and well-trusted application. Tokens can be directly generated for consuming APIs.

Client credentials: If the client application consuming the API is a Machine and does not require permission from API owner this grant if preferred. There are cases this grant is preferred if one would like to improve the end-user experience and the Mobile Application is well trusted.

The following diagram depicts the use cases for considering the above authorization grant types.

Figure 9: Authorization Grant - Use cases

webMethods API Management – OAuth 2.0 Support

webMethods Integration Server, webMethods API Gateway supports OAuth 2.0 Authorization framework. The supported grants are listed below.

API Management 2.0: webMethods API Gateway – Authorization Code, Implicit and Client Credentials Grants, Resource owners’ credentials.

ESB: webMethods Integration Server – Authorization Code and Implicit Grants

Resource Server and Authorization Server

The new API Management platform contains the product API Gateway which hosts APIs along with the Gateway (Enterprise Gateway) capabilities. In the case of API Management, APIs themselves are treated as protected information (or resources).  Hence Gateway Server can be treated as Resource Server that is hosting the protected information. The following diagram depicts the Software AG’s API Management Platform.

Figure 10: Software AG's API Management Platform

As described in the earlier sections, the OAuth 2.0 Authorization Framework introduces Authorization Layer and Software AG’s API Management platform supports OAuth 2.0’s Authorization Layer. The variations are described considering Authorization Code Grant as an example.

API Gateway as Resource Server and Integration Server as Authorization Server:

Figure 11: API Gateway as Resource Server & IS as Authorization Server

The above example represents a 3-legged OAuth 2.0 flow.

API Gateway as Resource Server and Third Party Authorization Server:

Figure 12: API Gateway as Resource Server & Third-Party Authorization Server

The above example represents a 3-legged OAuth 2.0 flow.

API Gateway as Resource Server and Authorization Server:

Figure 13: API Gateway as Resource & Authorization Server

The above example represents a 2-legged OAuth 2.0 flow.

webMethods API Gateway also provides preprocessing and post-processing steps, if one wishes to extend to n – legged OAuth2 flow.

webMethods API Management – Generating Access Tokens

webMethods API Management implements OAuth 2.0 Authorization Grant flows according to RFC https://tools.ietf.org/html/rfc6749 .

webMethods API Gateway with External Identity Provider: https://tech.forums.softwareag.com/t/securing-apis-using-3rd-party-oauth-2-provider-in-api-gateway/237218

webMethods API Gateway as Identity Provider: https://tech.forums.softwareag.com/t/securing-apis-using-oauth-2-in-api-gateway/237217