The StatPro Revolution Web API uses the OAuth 2.0 Authorization Framework for user authentication and authorization. Under this framework, a program that accesses StatPro Revolution Web API data is known as a client application. Each client application must be registered with the StatPro Revolution OAuth2 Server.
The Revolution OAuth2 Server currently supports three different types of client application:-
The differences between the types will be explained in later topics. As part of this overview, it is useful to see the workflow that a Server-Side Web application will follow to gain access to the Web API (many of the same steps apply to Native as well):-
The Revolution OAuth2 Server defines and supports three different types of application.
Server-Side Web applications are websites that are displayed in a normal browser window. To gain access to the Web API, the user is prompted at runtime to login to the Revolution OAuth2 Server and to explicitly grant access. If successful, the application is provided with an access token and refresh token. This type of application uses OAuth 2.0’s Authorization Code flow.
Server-Side Web apps are considered to be confidential in that the code that talks to the OAuth2 Server does not run on end users’ machines.
Native applications run on an end user’s computer desktop or mobile device. As with Server-Side Web apps, the user is prompted at runtime to grant access, and the OAuth 2.0 Authorization Code flow is used to provide a Native application with an access token and refresh token. A Native application, however, typically uses an embedded browser control to prompt the user for access since the application itself doesn’t run in a browser.
Native applications are not considered to be confidential with respect to the code that talks to the OAuth2 Server.
[Note: a native application that is supported by a backend web server can have its web server talk to the OAuth2 Server; in this case the web server’s application type would be Server-Side Web application. With respect to the StatPro Revolution OAuth2 Server, a ‘Native application’ is one where there is no web server involved, and the OAuth 2.0 code runs client-side, in the native application itself.]
Batch applications are those that typically do not display a user interface, especially not at runtime when access to the Revolution Web API is required. Such applications are designed to run unattended (e.g. overnight).
To support such applications, Data Feed User accounts are used. StatPro Client Services will create a “batch authorization” at setup time (as opposed to runtime) that allows a specific Batch application access to a Data Feed User’s data at runtime. The batch authorization is represented externally by a special type of password, known as an application-specific password (or ASP). The Batch application is then set up with the Data Feed User’s email address and ASP, which it uses at runtime (via the OAuth 2.0 Resource Owner Password flow) to get an access token.
Whether a Batch application is considered to be confidential or not depends on where it runs.
All three application types can get further access tokens without prompting the user. Batch applications simply present a Data Feed User’s email address and application-specific password to the OAuth2 Server again, whereas the first two application types use the previously issued refresh token (unless it has been discarded between user sessions of the app, or explicitly revoked by the app).
The StatPro Revolution OAuth2 Server (also referred to in this documentation as the OAuth2 Server) is based on the final OAuth 2.0 Authorization Framework specification, which was published in October 2012.
The authorization mechanism of the StatPro Revolution Web API is based on the final OAuth 2.0 Authorization Framework: Bearer Token Usage specification, which was also published in October 2012.
Also of importance to the OAuth2 Server, Web API and all client applications is the OAuth 2.0 Threat Model and Security Considerations document, published in January 2013.
From October 2018, the OAuth2 Server supports explicit revocation of refresh tokens by interactive applications according to the OAuth 2.0 Token Revocation specification.
Sample code is available on GitHub for all three application types. The samples show how an access token is obtained from the OAuth2 Server, and is then used to access data via the Web API.
The OAuth2 Server supports the Authorization Code grant type, or flow, as described in section ‘4.1. Authorization Code Grant’ of RFC 6749 for Server-side Web and Native applications.
The OAuth2 Server supports the Resource Owner Password Credentials grant type, or flow, as described in section ‘4.3. Resource Owner Password Credentials Grant’ of RFC 6749 for Batch applications.
The OAuth2 Server exposes three public OAuth 2.0 endpoints:-
The role of the first two programmatic endpoints is described in section ‘3. Protocol Endpoints’ of RFC 6749.
The role of the token revocation endpoint is described in section ‘2. Token Revocation’ of RFC 7009.
The OAuth2 Server has the following additional OAuth 2.0-related characteristics:-
Last updated: March 2019