StatPro Revolution Web API
Authorization using OAuth2
- Supported application types
- API Authorization Management
- OAuth 2.0 specifications
- Sample code
- Characteristics of the Revolution OAuth2 Server
Special Notice: The API Authorization Management website will cease to exist from the middle of May 2019. See more details in the Change Log.
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:-
- Server-Side Web application
- Native application
- Batch 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 Server-Side Web client application issues an authorization request to the StatPro Revolution OAuth2 Server (i.e. the browser window that the application is displayed in is redirected to the OAuth2 Server).
- The StatPro Revolution OAuth2 Server first prompts the user to login, and then to allow or deny access to his/her Revolution data by the client application.
- If allowed, the StatPro Revolution OAuth2 Server responds to the client application (via a redirect) with an 'authorization code'.
- The client application issues a request to the StatPro Revolution OAuth2 Server to swap the authorization code for an access token and a refresh token (using an HTTPS POST).
- Armed with the access token, the client application issues requests to the StatPro Revolution Web API for the user's data (portfolios, portfolio analyses, results data, etc.).
- If/when access to the StatPro Revolution Web API fails because the access token's lifetime (typically an hour) has expired, the client application issues a request to the StatPro Revolution OAuth2 Server for another access token (via the refresh token, using an HTTPS POST).
Supported application types
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).
API Authorization Management
The StatPro Revolution OAuth2 Server is used at runtime, when an application wants access to a user's data via the Web API. For Server-Side Web and Native applications, the user logs in, grants or denies access, and is then automatically logged out. The user interface is kept as simple and as clean as possible, and focusses the user exclusively on the process of granting or denying the current request for access.
In addition to this runtime process, there is the need for "setup time" activity by users, which can be performed at any time. The StatPro Revolution API Authorization Management website provides this capability, allowing a user to:-
- View which resource services (if any) he/she has access to.
- View his/her outstanding authorizations for Server-Side Web and Native applications. These 'interactive' authorizations allow the applications in question to continue to get access tokens from refresh tokens without prompting the user.
- Revoke interactive authorizations so that the applications in question can no longer access the user's data.
- View the Fair Usage statistics for the application that is associated with any one of his/her outstanding authorizations. Fair Usage statistics are displayed for the application in conjunction with the user's tenancy.
OAuth 2.0 Specifications
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.
Characteristics of the Revolution OAuth2 Server
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:-
- Authorization endpoint = https://revapiaccess.statpro.com/OAuth2/Authorization
- Token endpoint = https://revapiaccess.statpro.com/OAuth2/Token
- Token Revocation endpoint = https://revapiaccess.statpro.com/OAuth2/RevokeToken
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:-
- currently the only supported Resource Server (aka Resource Service) is the Revolution Web API, whose scope identifier is "RevolutionWebApi" (without the quotes)
- currently the only access tokens that are issued are Bearer access tokens
- issued Bearer access tokens are always base64-encoded
- the format of issued authorization codes, access tokens and refresh tokens is opaque; the only public information is that Bearer access tokens are base64-encoded
- authorization codes and refresh tokens may currently be GUIDs, but this is an implementation detail and is subject to change
- the lifetime of Bearer access tokens is currently set to one hour, but this is an implementation detail and is subject to change
- a response containing a Bearer access token will always indicate its scope and its lifetime
- for the Authorization Code grant: a response containing a Bearer access token will always contain a refresh token
- for the Resource Owner Password Credentials grant: a response containing a Bearer access token will never contain a refresh token
- getting a new Bearer access token from a refresh token will always a) invalidate the refresh token and b) cause a new refresh token to be issued.
Last updated: February 2019