Date:	Author:	Version:	Changes:	Completed	Ext.	Is in Core
		0.1	Doc. created		x	N/A
22 November 2018	Emil Ifrim	0.2	Brand Enabling	Yes	x	N/A
15 January 2019	SD	0.3	Download pdf-file
17 March 2023	Emil Ifrim	04	Fine Grain Security
06 February 2025	Emil Ifrim	0.5	Java 21 Upgrade	Yes	x	N/A

Overview

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

Authentication:
1. Client-authentication: The database table OAUTH_CLIENT_DETAILS (replaced by OAUTH2_REGISTERED_CLIENT after Java 21 Upgrade, core 11.23 or upwards) 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)asd
2. User/Operator/Client-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.
Authorization: A fine grained access rights control implemented in all resources that shall have limited access. This layer is customizabile: 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 is considered open for access, unless brand access check is in place. 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. There are three strategies/scenarios to obtain an Access Token.

User-authentication - this corresponds to a Selfcare use-case scenario. The authentication is done by validation username/password in the USERS table. An URL example for this scenario is (note grant_type=password value):

Authentication URL

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

CURL example

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&brand_key=#myBrandKey"

where:
#myusername, #mypassword are taken from Users table
#myBrandKey is taken from the Brand table
myclientid, myclientsecret are taken from OAUTH_CLIENT_DETAILS table

Angular example

function login(credentials) {
      var data = 'username=' +
        encodeURIComponent(credentials.username) +
        '&password=' +
        encodeURIComponent(credentials.password) +
        '&grant_type=password&scope=read%20write&' +
        'client_id=myclientid&' +
        'brand_key=myBrandKey';
      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;
              });
    } 
 
 
where:
credentials.username, credentials.password are taken from Users table
myBrandKey is taken from the Brand table
myclientid, myclientsecret are taken from OAUTH_CLIENT_DETAILS table (OAUTH2_REGISTERED_CLIENT table after Java 21 upgrade, core 11.23 and above)

Operator-authentication - this correspnds to a Customercare use-case scenario. The authentication is done by validation username/password in the OPERATORS table. An URL example for this scenario is (note grant_type=operator_password value):

Authorization URL

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

CURL example

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

where:
#myusername, #mypassword are taken from Operators table
#myBrandKey is taken from the Brand table
myclientid, myclientsecret are taken from OAUTH_CLIENT_DETAILS table (OAUTH2_REGISTERED_CLIENT table after Java 21 upgrade, core 11.23 and above)

Clint-authentication (Java 21 upgrade, core 11.23 and above)- this correspnds to a M2M use-case scenario. The authentication is done by validation of registered client clredentials in the OAUTH2_REGISTERED_CLIENT table. An URL example for this scenario is (note grant_type=client_credentials value):
Authorization URL
```
https://host:port/appcontext/oauth/token?operator=#myoperatorusername&grant_type=client_credentials&brand_key=#myBrandKey
```
CURL example
```
CURL example:  curl -v -X POST -u myclientid:myclientsecret http://host:port/appcontext/oauth/token -H "Accept: application/json" -d "grant_type=client_credentials&uoperator=#myoperatorusername&brand_key=#myBrandKey"

where:
#myoperatorusername is taken from Operators table
#myBrandKey is taken from the Brand table
myclientid, myclientsecret are taken from OAUTH_CLIENT_DETAILS table (OAUTH2_REGISTERED_CLIENT table after Java 21 upgrade, core 11.23 and above)
```
Since Rator code needs an Operator in the execution context (e. history, logging), the request needs the Operator username as request parameter.
This means that endpoint invokations using an access token obtained using client_credentials flow are considered to be done on the behalf of an Operator. This implies that the client using the client_credentials flow is responsible for authentication the Operator. This might be considered a security risk, so use client_credentials flow only if the other flows cannot be used.

Authorization

Authorization is done in two steps:

Brand Access
In order to obtain an access token, the client has to have configured the proper authorization. That is, in the OAUTH_CLIENT_DETAILS table, a client has to have defined proper values in AUTHORITIES column. Those authorities must have the following prefix: ACCESS_BRAND_ .After the prefix there should be the brand_key (uppercase) that the respective client has access to. The brand_key parameter should be sent as QUERY parameter in the request for the token.

Example of registered client:

CLIENT_ID	RESOURCE_IDS	CLIENT_SECRET	SCOPE	AUTHORIZED_GRANT_TYPES	WEB_SERVRE_REDIRECT_URI	AUTHORITIES	ACCESS_TOKEN_VALIDITY	ADDITIONAL_INFORMATION	AUTOAPROVE
swagger-ui		swagger-ui-secret	read,write	password,operator_password		ACCESS_BRAND_BRAND_X	600

Example: given a brand key with a value of RATOR_X , the authority tag should be ACCESS_BRAND_RATOR_X .
If a client has access to multiple brands, those should be separated by , (e.g ACCESS_BRAND_RATOR_X, ACCESS_BRAND_RATOR_Y)

CURL example

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

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 the @RatorSecured annotation that can have few input attributes, in orderto define the assesed field or the Role of the logged in user.

Access Configuration

@RatorSecured(requiredRole = Role.OPERATOR , assertOn = "subscriptionId")
public Response updateNpFlow(@PathParam("subscription-id") SubscriptionId subscriptionId) {...}

@RatorSecured(requiredRole = Role.SUB_OWNER, assertOn = "userId")
public Collection<ContactPoint> getContactPointsForUser(@PathParam("user-id") UserId userId) {...}

@RatorSecured(requiredRole = Role.OPERATOR, restrictorFactory = OperatorAccessRestrictorFactory.class)
    public Collection<Product> getProducts(@Context RESTContext ctx) { ... }

Brand Access Check

In case of a multi branded environment it is possible to restrict access to the "public" endpoints by enabling the brand access check in the configuration file (Properties.txt). This is done by setting the following parameter:

Enable brand access check for public endpoints

rest.api.security.public.brand_access_check=true

When the above parameter is in place an access token (Authorization: Bearer access_token) is required to be sent in the request. For public endpoints one can obtain a access token by using the "operator_password" grant type.

Authorization URL

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

CURL example

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

where:
myclientid, myclientsecret are taken from OAUTH_CLIENT_DETAILS table
#myBrandKey is taken from the Brand table

Swagger

To configure swagger to use this authentication scenario, an additional parameter has to be set in Properties.txt file:

rest.swagger.auth.flow=operator_password

Swagger UI and proxy

To configure swagger to allow testing endpoints when REST is deployed behind a proxy (e.g CI/CD and docker) an additional parameter has to be set in Properties.txt file:

rest.swagger.api.context_path=/rator-rest-api/v1 #the valuehas to adjusted according to the proxy configuration

CORS

In order to be able to access both the AUTH app and REST app from Javascript clients, CORS parameters need to be configured. Below there is an example of how that can be done:

CORS

rest.auth.cors.allowed-origins=*
rest.auth.cors.allowed-methods=GET, PUT, POST, DELETE, OPTIONS
rest.auth.cors.allowed-headers=*
rest.auth.cors.exposed-headers=
rest.auth.cors.max-age=3600 

rest.api.cors.allowed-origins=*
rest.api.cors.allowed-methods=GET, PUT, POST, DELETE, OPTIONS
rest.api.cors.allowed-headers=Origin, X-Requested-With, Content-Type, Accept, Authorization, X-RATOR-brand-key
rest.api.cors.exposed-headers=
rest.api.cors.max-age=3600

Browser not supported