StatPro Revolution Web API


Authorization using OAuth2


Tenancies: primary and alternative

When the Revolution Web API and the Revolution OAuth2 Server were created, a Revolution user was a member of a tenancy. I.e. each user belonged to, was a member of, his/her tenancy. There was no notion that a user could also be a member of a different tenancy. This is why neither the Web API nor the OAuth2 Server offered any information about the tenancy involved in a user's data access. It's also why the OAuth2 Server didn't allow for the user to select between different tenancies, at the time of allowing an authorization.

Since the time when the OAuth2 Server was created, Revolution users have gained the ability to optionally become members of other tenancies, in addition to their home tenancy. These other tenancies are known as alternative, or alt, tenancies. The home tenancy is known as the user's primary tenancy.

Starting in December 2016, the OAuth2 Server now allows users to select which of their tenancies to use, when allowing an authorization. This allows applications such as Revolution-i and the Web API Explorer to extract and display Web API data from one of a user's alt tenancies, and not just from the user's primary tenancy. In addition, the OAuth2 Server now provides information about the tenancy involved when it returns an access token to a client application.

This section describes how application authors can take advantage of this new functionality in their own apps.

NOTA BENE: the new functionality is not enabled automatically; applications must explicitly opt-in to use it. Also, there are restrictions imposed by the OAuth2 Server in allowing users to select tenancy. Finally, application authors should carefully consider whether it is appropriate and/or safe for them to allow users to select between their tenancies.


Restrictions on alt tenancy access

  1. Batch mode access to alt tenancies is not supported. In others words, a batch authorization (represented externally by a Data Feed User's email address and an Application-Specific Password) can only target the Data Feed User's primary tenancy. (Also note that Data Feed Users cannot have alt tenancies in the first place.)
  2. By default, Interactive mode access to alt tenancies is not enabled. Instead, an application that is requesting an Authorization Code (as part of the OAuth 2.0 Authorization Code Grant) must signal at runtime that it is able to cope with the fact that the user may select an alt tenancy as the tenancy from which data will be extracted, and that the choice of tenancy may vary from one interactive session to the next. In other words, the application is explicitly opting-in to this new functionality, and is signalling that it can cope with the consequences.
  3. Interactive mode access to alt tenancies is only enabled if the scope of the authorization request is limited to the Revolution Web API resource service only.

In addition, the following limitations may apply at runtime...

A user's alt tenancy is not listed as being selectable by the user

This situation occurs when an application has been registered as being accessible only by users in one tenancy, or in a small number of related tenancies (as opposed to all tenancies). If a user is a member of an alt tenancy, and that alt tenancy is not listed as being selectable by the user, it simply means that the app has been registered as not being accessible by users in that tenancy.

After a user allows access to an alt tenancy, the OAuth2 Server refuses to grant access

One reason for access being denied is that the alt tenancy in question is not licensed for usage of the Revolution Web API. To check if this is the case, please contact StatPro Client Support.

The other main reason for access being denied to a user is that the user's role within the alt tenancy does not afford them access to Revolution Web API data. The user should check on their user role and its permissions with one of the alt tenancy's owners.


Should an app allow user tenancy selection?

An interactive (i.e. non-batch) application that would allow the user to select which tenancy to access in any one interactive session must be able to cope with this simple, but far-reaching, fact.

There are many things that can go wrong with this new functionality. For example, if the application updates existing state in any one interactive session, then the fact that the tenancy could change from session to session may cause the app to fail with a runtime error - or worse - may cause bad calculations to be made in-app.

Before opting-in to the new functionality re. tenancy selection, an existing application should:-

  • be able to categorize any currently-stored data as pertaining to the user's primary tenancy
  • be able to categorize data pulled from the Web API in the future by tenancy
  • be able to understand the extra tenancy information that will be included in the access token response (see below).

Note: unless an application explicitly opts-in to allow user tenancy selection, the behaviour and responses of the OAuth2 Server will be exactly the same as before, when it only knew about a user's primary tenancy. (A small caveat to this is that an app can get tenancy information, but again, this must be explicitly enabled.)


User tenancy selection

Server-Side Web apps and Native apps can allow user tenancy selection by including additional query string allow_tenancy_selection=true in the initial authorization request.


Server-Side Web App

Before (tenancy selection disallowed):-

GET https://revapiaccess.statpro.com/OAuth2/Authorization?response_type=code&client_id=s6BhdRkqt3&scope=RevolutionWebApi&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1

After (tenancy selection allowed):-

GET https://revapiaccess.statpro.com/OAuth2/Authorization?response_type=code&client_id=s6BhdRkqt3&scope=RevolutionWebApi&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&allow_tenancy_selection=true HTTP/1.1


Native App

Before (tenancy selection disallowed):-

GET https://revapiaccess.statpro.com/OAuth2/Authorization?response_type=code&client_id=s6BhdRkqt3&scope=RevolutionWebApi&state=xyz&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob HTTP/1.1

After (tenancy selection allowed):-

GET https://revapiaccess.statpro.com/OAuth2/Authorization?response_type=code&client_id=s6BhdRkqt3&scope=RevolutionWebApi&state=xyz&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&allow_tenancy_selection=true HTTP/1.1


Allowing user tenancy selection automatically causes the OAuth2 Server to include tenancy information in the access token response. This is described in the section below.


Tenancy information

Allowing user tenancy selection (see the section above) causes the OAuth2 Server to include information about the selected tenancy in the JSON-based access token response. Even if the user only belongs to their primary tenancy, and no alternatives, this information will still be included.

Before (no tenancy info):-

{
    "access_token": "<base64-encoded access token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "RevolutionWebApi",
    "refresh_token": "3c5a821e-795e-44f7-abf4-ec0c0eb9bd30",
    "user_id": "4289ee5d82e3d8fb48ce4048e82344bc44ced59122a34db287c2457379aeb3e9",
    "user_name": "A Person"
}

After (with tenancy info):-

{
    "access_token": "<base64-encoded access token>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "RevolutionWebApi",
    "refresh_token": "3c5a821e-795e-44f7-abf4-ec0c0eb9bd30",
    "user_id": "4289ee5d82e3d8fb48ce4048e82344bc44ced59122a34db287c2457379aeb3e9",
    "user_name": "A Person",
    "tenancy": {
        "code": "COMPANY",
        "name": "A Company Ltd",
        "isPrimary": true
    }
}

Notes:-

  1. The identified tenancy is the target tenancy - i.e. the tenancy that the access token targets - whether the user selected it from a choice of tenancies or not.
  2. The code of the tenancy is static and unique.
  3. Where possible, the code of the tenancy should not be displayed to end users.
  4. The name of the tenancy is its display name. It is not static (i.e. it can be changed) and it is not guaranteed to be unique.
  5. The isPrimary member is a flag indicating whether the tenancy is the user's primary tenancy (true) or one of his/her alternative tenancies (false).


Tenancy information without user selection

Any application, including Batch applications, can request that tenancy information is included in the JSON data of the access token response (see above), without enabling user tenancy selection. (Because there is no user tenancy selection, the tenancy in question will be the user's primary tenancy, by definition.)

For Server-Side Web apps and Native apps, the request to the Token endpoint that swaps an authorization code for an access token must include parameter include_tenancy_info=true to enable this feature.

For Batch apps, the request to the Token endpoint that swaps a username and password for an access token must include parameter include_tenancy_info=true.

Example (for a Server-Side Web app):-

POST https://revapiaccess.statpro.com/OAuth2/Token HTTP/1.1
Host: revapiaccess.statpro.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&include_tenancy_info=true

See the section above for details of the access token response and the included tenancy information.

Notes:-

  1. It is possible, but not recommended, to enable user tenancy selection but disable the inclusion of tenancy information by specifying include_tenancy_info=false in the request to the Token endpoint.
  2. Requests to the Token endpoint to swap a refresh token for an access token ignore the include_tenancy_info parameter. The decision to include tenancy information will have been made beforehand: either in the original access token request, or in the initial authorization request.


Last updated: January 2017


To Top