Overview

This page describes the security layers of the REST web app. There are two security layers:

1. Authentication: 
   1. Client-authentication:The database table OAUTH_CLIENT_DETAILS describes the servers, which are allowed to make calls to the REST web app. (Typically this will be the selfcare web app and, when in development, the Swagger UI)
   2. User-authentication: A username/password based security layer that upon each requests matches a token from the request against an in-memory map from token to logged in users.
2. Authorization: A fine grained access rights control implemented in all resources that shall have limited access. This layer is customizable: The customer can register their own rules. The default rules are all based on "ownership": Account-ownership, BillingGroup-ownership and Subscription-ownership.

Authentication

Authentication is triggered by the Authorization layer. If a resource does not require Authorization, then it's considered open for access. The Authentication protocol used is OAUTH2  and the implementation used is from Spring Framework.

In order to call REST resources that require Authorization, the calling client has to provide an Access Token. Obtaining an Access Token can be done by calling a specific URL:

https://host:port/appcontext/oauth/token?username=#myusername&password=#mypassword&grant_type=password
 

CURL example:  curl -v -X POST -u myclientid:myclientsecret http://host:port/appcontext/oauth/token -H "Accept: application/json" -d "grant_type=password&username=#myusername&password=mypassword"

where:
#myusername, #mypassword are taken from Users table
myclientid, myclientsecret are taken from OAUTH_CLIENT_DETAILS table

function login(credentials) {
      var data = 'username=' +
        encodeURIComponent(credentials.username) +
        '&password=' +
        encodeURIComponent(credentials.password) +
        '&grant_type=password&scope=read%20write&' +
        'client_id=myclientid';
      return $http
        .post('/oauth/token',
            data,
            {
              headers : {
                'Content-Type' : 'application/x-www-form-urlencoded',
                'Accept' : 'application/json',
                'Authorization' : 'Basic ' +
                  base64Service.encode('myclientid'	+ ':' + 'myclientsecret')
              }
            }).success(
              function(response) {
                //store the access token
                return response;
              });
    } 

Authorization

Fine-grained access control is about limiting the access to specific resources, or even to limit the access to code blocks within a single resource. The current version of the REST app uses our own framework for this. The framework defines two abstract classes, whose implementations stand in a one-to-one relationship with a resource (an @Path annotated method). The two classes reflect the kind of questions/checks needed in the code.

• AccessController: Implementations must implement a single method called assertAccessible(AccessContext), which returns a boolean. This method is called before entering the resource.
• AccessRestrictor:  Implementations must implement a single method called restrict(List<?>). This is called before returning Lists of objects, and provided the customer with an opportunity to filter away restricted resources (such as Subscriptions, for which the caller does not have some sort of ownership over.