Introduction to OAuth

Now that we have outlined some of the hurdles with an on-premise installation, we can dive into learning about OAuth and how ReportPlus Server handles the flow for a typical user trying to access data. First we’ll start with an overview of the technology, then we’ll detail the registration process for a typical API (e.g. Google Analytics API), next we’ll define how to configure the web app, and finally we’ll step through the process of authorizing the app.

What is OAuth?

OAuth is a standard protocol that enables a third-party application like a web application to obtain limited access to an HTTP service (e.g. REST Web API) on behalf of a resource owner. This is accomplished by orchestrating an approval action between the resource owner, an authorization server, and the third-party application where the owner, via the authorization server, grants the third-party application access to protected resources typically on another server (the HTTP Service). “Because the resource owner only authenticates with the authorization server, the resource owner’s credentials are never shared with the client”, thus eliminating the need for the application to itself store and secure the owner’s credentials ("The OAuth 2.0 Authorization Framework”). After the resource owner completes the authorization step, a unique access token is issued to the application, which the application can later use to retrieve resources from a given resource server (HTTP Service). The following diagram lays out the sequence of steps that occur in a typical OAuth 2.0 flow. In the section titled Authorize ReportPlus Server for Google Analytics Data Retrieval, we will cover how ReportPlus Server handles OAuth in more detail.

OAuth 2.0 flow to access typical Google API

  1. End-user wishes to access some remote resources and Initiates flow.

  2. Application redirects to external webpage (in external authorization server) where user is presented with a sign-in page (if not already signed-in) and prompted for credentials.

  3. User enters credentials and authorizes access to protected resources.

  4. Authorization server returns authorization code to application.

  5. Application exchanges authorization code for user-specific access token.

  6. Application stores access token for later use.

  7. Application consumes API endpoint (HTTP Service) by passing along appropriate parameters and access token.


Beginning OAuth

Before any application is able to initiate an OAuth protocol, it first must be registered with an appropriate authorization server. At a high level, registration in general follows the same basic steps.

  1. The app administrator logs into the registration page.

  2. The administrator provides some basic information about the type of application being registered.

  3. The administrator submits the information and in return is granted a set of identifying credentials.

The information that is provided is mostly standard and it usually involves divulging things like the type of application (e.g. desktop, mobile, web), a URL endpoint where an access token should be forwarded to, and some other miscellaneous information such as application name and/or application description. The exact process varies from server to server and one needs to consult the proper documentation to find out provider-specific instructions, nevertheless, despite the exact registration process, ultimately the goal is to define the identity of the application that needs access to an API and to retrieve a set of app-identifying credentials to initiate OAuth.

Prevailing Approach for Registering an On-Premise Application for OAuth

Given the complexities of the OAuth protocol and the potential pitfalls inherit with developing secure solutions, most third-party vendors choose to let every on-premise installation manage its own registration rather than creating a solution that eliminates this step. That is to say, each installation should register, obtain, and maintain its own set of API credentials and access tokens as needed instead of depending on a central body to do so. The least costly way to achieve this at this time, would be to give the app administrator easy and ample access to third-party OAuth configuration documentation, and the tools to configure the application for consuming OAuth protected APIs.