Introduction

This document describes the concept for authorization of REST API calls based on the Intershop REST framework. The concept however is applicable in general for any REST based API that could be used by authenticated users with different access privileges.

References

• Concept - REST Framework

• Guide - REST Style Guide

• Concept - REST Framework Security
• Guide - Pipeline Security
• A7-Missing Function Level Access Control
• Guide - B2B Storefront Functionality (valid to 7.10.16)
• Reference - WebShop REST API
• JAX-RS Filters and Interceptors

Overview

Security Risk

One of the most critical web application security flaws stated in OWASP Top 10 specification are A4 - Broken Access Control and A10 - Under-protected APIs. Such flaws allow attackers to access unauthorized functionality.

Applications and APIs do not always verify the user is authorized for the target resource. Sometimes, function level protection is managed via configuration, and the system is mis-configured. Sometimes, developers must include the proper code checks, and they forget.

In order to prevent such flaws the following recommendations are given:

Your application should have a consistent and easy to analyze authorization module that is invoked from all of your business functions. Frequently, such protection is provided by one or more components external to the application code.

1. Do not hard code! - access control rules should be external to the application code.
2. Ensure access control rules can be updated and audited easily.
3. The enforcement mechanism(s) should deny all access by default, requiring explicit grants to specific roles for access to every function.
4. Implement an access control scheme that protects APIs from being improperly invoked, including unauthorized function and data references.
5. If the function is involved in a workflow, check to make sure the conditions are in the proper state to allow access.

The Intershop REST API Authorization Concept adopts these recommendations and reduces the risk for unauthorized access to customers data.

Roles and Permissions in ICM

In most of the cases authorization logic requires specific roles/permissions to be assigned to the authenticated user in order to be able to access particular functionality. Other authorization rules enforce the scope of the data a given user could access and does not rely on permissions, but on other attributes of the request and the user to take the authorization decision (for example if the currently logged in user belongs to the same customer that is requested, if the currently logged in user is the buyer of the requested basket resource, etc.).

Roles and Permissions in the Intershop B2C Storefront

In the B2C context currently there are no separate roles and permissions. Usually the user is allowed to work with his own data. Part of the functionality is publicly accessible and could be accessed by not authenticated users (for example catalogs, products information, etc.).

But certain functionality is accessible only for authenticated users (for example orders list). The same is valid for the Storefront B2C REST API.

Roles and Permissions in the Commerce Management Application

The ICM Commerce Management application users are assigned to user groups defined for the corresponding level (Channel, Organization, etc.). These user groups have assigned corresponding permissions. So the permissions of a user are determined by examining the user groups to which the user is assigned in the corresponding level. In the context of authorization this level is called authorization object. In order to access a given part of the Commerce Management application, the REST API the user must have assigned corresponding permissions for the related authorization object.

Roles and Permissions in Intershop B2B Storefront

The B2B storefront contains a management section for users of a customer buying organization. Here administrators of the buying organization can create and manage users with a predefined set of roles and permissions (Buyer, Approver, Account Admin, etc.).

The assigned roles are currently directly bound to the corresponding user. Each storefront role has a predefined set of permissions. The B2B assembly provides storefront REST API that exposes the available business features via REST Web Services. Access to some part of the REST API should be available only for users with specific B2B roles/permissions in the storefront.

For example only users with assigned permission APP_B2B_CREATE_COSTOBJECTTYPE could create cost object types for the customer buying organization via the B2B storefront REST API.

Intershop REST APIs

Intershop applications REST API is build using the Intershop REST Framework utilizing the Jersey JAX-RS library implementation.

An Intershop REST URI is constructed according to the following pattern:

http://<web-server>:<port>/INTERSHOP/rest/<ServerGroup>/<SiteID>/<AppUrlID>;loc=en_US;cur=USD/<Top-level Resources>

Example:

http://localhost:82/INTERSHOP/rest/WFS/inSPIRED-inTRONICS_Business-Site/-/customers/-/costobjecttypes/5ZgKDABww4sAAAFaydxBxASB

REST resources that have access restrictions require an authentication token provided in the request (provided in Authorization HTTP request header). This token is used to authenticate the user that made the REST request and during authorization to check his access permissions.

Currently the following REST API exists in the ICM landscape:

• B2C Storefront REST API - WebShop API for B2C customers
• SMB Storefront REST API - WebShop API for SMB customers
• B2B Storefront REST API - Extends the SMB Webshop API with additional B2B specific REST calls
• BackOffice REST API - Allows access to available batch processes (productimports, customerimports, etc.) and search indexes
• Contact Center REST API - Provides access to available channels, customers and users for a Contact Center Operator
• SMC REST API - Allows access to available domains and jobs

Authorization Concepts

REST Authorization concept apply the Mandatory Access Control principle, meaning any operation by any subject on any object is tested against the set of authorization rules (authorization policy) to determine if the operation is allowed.

Any authenticated user could manage their own recurring orders.
Authenticated users with assigned "Manage Users" permission could manage recurring orders of all users that belong to the same customer the user belongs to.

• Access to the REST resources is denied by default. Explicit record in the access control policy should exist in order to allow the access.
• Access Control Policy definition and checks are isolated from the source code defining the REST resources.
• There is no need to add manually any access control code when defining the REST resource classes
• Access control policy use the resource path template and HTTP method(s) as a key to define the access control rules
• One REST request could be matched to more than one ACL entry and authorization is successful only when the authenticated user satisfies the conditions of ALL entries.
• Default authorization policy requires successfully authenticated user. In case there are some public resources that should be accessible by anonymous users this must be explicitly allowed in the ACL configuration
• Default implementation of access control policy definition is properties file based (resources-acl.properties)
• Default access control policy is based on permission checks (permission based authorization)
• Access Control Policy is loaded during server startup and is cached in memory
• Authorization checks are enforced by using post matching JAX-RS container request filter

The following picture shows the different stages in the REST request processing chain and the place where authorization is done:

Involved Cartridges

• p_platform/core - security package contains some classes related to authorization (e.g., AttributeFinder)
• p_platform/bc_authorization - authorization service and policy related classes
• p_platform/rest - REST specific authorization implementation classes (e.g., RestAuthorizationFilter, RestAuthorizationService, UriTemplateAuthorizationRequestMatcher, RestAuthorizationRuleFactory)
• p_platform/pf_rest_test - contains authorization policy configuration for eTEST REST API in resources-acl.properties
• f_business/app_sf_rest - contains some specific authorization conditions (e.g., IsMemberOfCustomer, HasSameIdentity)
• f_business/f_checkout/bc_customer - contains some specific authorization attribute finders
• f_business/app_sf_rest_b2c - contains authorization policy configuration for B2C Webshop REST API in resources-acl.properties
• f_business/app_sf_rest_smb - contains authorization policy configuration for SMB Webshop REST API in resources-acl.properties
• f_business/i_operations/as_system - contains authorization policy configuration for SMC REST API in resources-acl.properties
• f_business/a_backoffice/as_backoffice - contains authorization policy configuration for Commerce Management application REST API in resources-acl.properties
• f_business/a_backoffice/as_contactcenter - contains authorization policy configuration for Contact Center REST API in resources-acl.properties
• f_b2b/app_sf_rest_b2b - contains authorization policy configuration for B2B Webshop REST API in resources-acl.properties

Components

• The RestAuthorizationFilter intercepts the requests to the REST Resources and creates a request to the configured REST API RootResource AuthorizationService.
• The authorization request contains basic information like requested resource path, requested action and the subject (user) that submitted the request to the Rest Resource.
• AuthorizationService uses the configured authorization policy to make a decision to grant access or deny access to the requested resource
• Authorization policy makes a lookup in the available authorization rules to find the rules that match the requested resource and action
• The authorization conditions of matched authorization rules are checked in order to calculate the authorization decision (PERMIT or DENY)
• In case the decision is PERMIT the matched method of the Rest Resource is executed and response is returned
• In case the decision is DENY then FORBIDDEN or NOT_AUTHORIZED error is returned and the matched method of the Rest Resource is not executed

The following sequence diagram shows the interaction between main components that participate in the REST authorization process.

ACL File Format

Currently the REST authorization policy is configured in a resources-acl.properties text file, located in the components folder of the corresponding cartridge, where the REST API is defined. During the ICM server startup this file is loaded and authorization policy configuration in the property file is transformed into the corresponding object structure, which is cached in memory and used during the REST requests authorization process.

The resources-acl.properties files must match a specific syntax. As all properties files, they are made of key-value pairs. Key describes the resource path template and HTTP method(s). Value describes the required authorization conditions that the user must fulfill in order to access the requested resource and action to be permitted. Authorization conditions could be based on permissions or on other user or resource attributes (being member of given customer, being buyer of the requested basket, etc.).
The following lines illustrate the general ACL syntax:

# permission list for a given context for a specific HTTP method of a REST resource
< HTTP Method >|< Resource Path Template >=<Condition1> [OR/AND] <Condition2>

# permission list for a given context for any HTTP method of a REST resource
|< Resource Path Template >=<Condition1> [OR/AND] <Condition2>

ACL Key

• ACL entry keys consists of HTTP method(s) and resource path URI template, separated by | character, which is mandatory.
• Resource path template defines the general resource path using placeholders for dynamic path parameters like ID-s. Starting point for the path is the part after the site name and URL ID of the app, as it is referenced in Webshop REST API.
• In case several HTTP methods share the same access control restrictions they could be defined in a single ACL entry using semicolon as separator. Example: < HTTP Method1>;< HTTP Method2>|< Resource Path Template >=<Condition1>
• In case no HTTP method is defined within, ACL entry access restrictions are valid for all HTTP methods for the defined resource path. Example: |< Resource Path Template >=<Condition1>
• So the key in the ACL entry is reflecting the action and resource path in the Intershop REST API Swagger documentation:
  

  

ACL Value

• The value for the ACL Entry defines authorization conditions that the user must fulfill. The following conditions are available out of the box:
  • isAnyUser - indicates that the related resource could be accessed by both authenticated and not authenticated users. Used for public REST resources like catalogs, product information, etc.
  • isAuthenticated - indicates that the related resource could be accessed by authenticated users in the default authorization object type for the application
  • isAuthenticated[<AuthorizationObjectType>] - - indicates that the related resource could be accessed by authenticated users in the explicitly provided authorization object type
  • hasPermission[<PermissionName>] - indicates  the user must have assigned specific permission in the default authorization object type for the application (for example in the B2B Storefront context it is the buying organization).
  • hasPermission[<AuthorizationObjectType>:<PermissionName>] - indicates the user must have assigned a specific permission in explicitly provided authorization object type (e.g., Channel, Organization, Enterprise)
  • isMemberOfCustomer[customerId] - authorization condition available for the Storefront REST API-s, indicating the authenticated user must belong to the same customer that is requested in the REST resource path
  • hasSameIdentity[userId] - authorization condition available for the SMB and B2B Storefront REST API-s, indicating the authenticated user must be the same user that is requested in the REST resource path
• Authorization conditions could be combined in Boolean expressions, in this way creating composite authorization conditions

Examples:

# Allow get for the ROOT resource which returns the available sub-resources list
GET;OPTIONS|/=isAnyUser

# Only user with granted APP_B2B_CREATE_COSTOBJECTTYPE permission within customer organization could create new cost object type
POST|customers/{customerId}/costobjecttypes=hasPermission[APP_B2B_CREATE_COSTOBJECTTYPE]

# Only user with granted APP_B2B_VIEW_COSTOBJECTTYPE permission within customer organization could see cost object type details
GET|customers/{customerId}/costobjecttypes/{costObjectTypeId}=hasPermission[APP_B2B_VIEW_COSTOBJECTTYPE]

# Only user with granted APP_B2B_MANAGE_USERS permission within customer organization could see, edit and delete users
|customers/{customerId}/users/{userId}=hasPermission[APP_B2B_MANAGE_USERS]

# OPTIONS HTTP method for customer resource does not require special access control checks
OPTIONS|customers/{customerId}=isAuthenticated

# Using more than one HTTP method in ACL entry when they require the same permission checks
PUT;DELETE|customers/{customerId}/costobjecttypes/{costObjectTypeId}=hasPermission[APP_B2B_MANAGE_COSTOBJECTTYPE]

# All resource paths under customer need to satisfy this access control rule
|customers/{customerId}{anyPath\:.*}=hasPermission[APP_B2B_MANAGE_CUSTOMER]

# Allow read-only access for anonymous users to catalog categories and products resources so not logged in users could browse products
GET|categories{anyPath\:.*}=isAnyUser
GET|products{anyPath\:.*}=isAnyUser

# All resource paths under specific customer need to satisfy isMemberOfCustomer authorization condition
GET|customers/{customerId}{anyPath\:.*}=isMemberOfCustomer[customerId]

# Composite authorization condition using the OR boolean operator
GET|customers/{customerId}/users/{userId}/recurringorders=hasSameIdentity[userId] OR hasPermission[APP_B2B_MANAGE_USERS]

Authorization Rules Overriding

There are some configuration properties in the ACL entry that determine how the authorization rules will be combined in case more than one authorization rule match the requested resource and action.

Default policy is that the user should satisfy the authorization conditions of all matched rules in order to have access granted. The first matched rule that returns a DENY result determines DENY result for the authorization request.

• Adding a new ACL entry for a resource for which there is already a matching rule for some of the parent resources corresponds to overriding a method and calling the super() method in Java world. So both rules will be executed when a request to this resource is made.
• In some cases almost all sub-resources of given start path share the same authorization policy, but there are 1 or 2 exceptions that need different authorization condition. In this case the [OVERRIDE] keyword could be used in front of these rules. The analog in Java world is overriding a method without to call the super() method. In this case the defined for such rule authorization condition should be enough to take the authorization decision for the request.
• In case there are more than one matched rules that use the OVERRIDE keyword, the most concrete rule will be used based on the resource path template and actions defined.

Examples:

# All resource paths under specific customer need to satisfy isMemberOfCustomer authorization condition
GET|customers/{customerId}{anyPath\:.*}=isMemberOfCustomer[customerId]

# Only this rule will be executed for recurringorders resource requests because the OVERRIDE keyword is used
[OVERRIDE]GET|customers/{customerId}/users/{userId}/recurringorders=hasSameIdentity[userId] OR hasPermission[APP_B2B_MANAGE_USERS]

Authorization Components Configuration

In order to enforce REST API authorization the following configuration must be done:

• Configure authenticationProvider for the REST API Root Resource
• Configure permissionProvider for the REST API Root Resource
• Configure ACL entries for your REST resources

For details see Recipe: Implementing authorization for a new REST API .

Possible Future Extensions

• Provide alternative AuthorizationRulesProvider implementation using Java code instead of properties file (builder pattern, etc.)

Assumptions & Limitations

• The whole REST request processing happens in a single thread (Rest Request Dispatcher, Rest Authorization Filter, Rest resource method invocation, etc.). The Intershop framework heavily relies on ThreadLocal variables to share data between components that interact during request processing.
• REST Authorization classes and related BO layer components do not store request specific data as class fields, but use the Provider concept (CurrentApplicationBOProvider, etc.). As the authorization policy related classes are instantiated during server startup and then cashed in the memory request specific data should not be created during class instantiation, but at runtime when the authorize() method for a concrete request is called.
• Resource path and HTTP method are enough for defining the access control policy. Matrix parameters, query parameters and HTTP headers do not contain additional information that could influence the authorization decision.
• REST API is implemented following the REST framework conventions, for example implementing RestCollectionResource for actions on resource collections ( GET list, POST item) and Item RestResource for actions on single resources (GET item, PUT modified item, DELETE item)
• REST responses for OPTIONS method do not contain confidential information. For pre-flight OPTIONS requests in CORS environments the authorization check is skipped and response code is always 200 OK.
• Final REST resource URI that will be processed by ICM will have the same structure regardless of any URL rewriting that is performed before the front controller. The authorization concept uses the REST resource path template for defining the authorization policy.
• No authorization policy cache invalidation is currently envisioned, meaning that changing the authorization policy rules will require restart of the ICM server in order for changes to take effect.

Non Functional Requirements

This section describes the expected conditions about the volumes of some of the data structures that will be processed during the authorization checks.

• ACL contains no more than 500 records
• Single ACL entry will not be related to more than 10 HTTP methods
• Single ACL entry will not contain more than 10 contexts
• Single context in an ACL entry will not contain more than 10 permissions/rules defined
• Each REST request will be not mapped to more than 10 relevant ACL entries