Authorization

Introduction

Authorization is a function that most applications require to implement, simply because, an application has to protect its resources by controlling who can access and manage these resources.

WeOmni Authorization Platform (aka. Authz) is a solution to facilitate access control within your application, it is highly customizable and allows developers to build their own access policy to protect resources in the application. At its core, the WeOmni Authorization Platform provides the following functionalities:

1. Access policy management
2. Access policy enforcement

Access Policy Management

In the WeOmni Authorization Platform, access control is done by describing and managing a set of access policies. An access policy consist of the following properties:

1. A subject that attempts an access
2. A resource that is being accessed
3. An action being attempted on the resource

Here are some examples of access policies:

Policy	Subject	Action	Resource
James can view any merchant information	James	view	merchant
Users in a marketing group can create a campaign report	Marketing group users	create	campaign report
True Smart Merchant application can receive payment notifications	True Smart Merchant	receive	payment notification

To manage access policies, the WeOmni Authorization Platform provides APIs for CRUD operations over the policy properties. See API Reference for details.

Group management

For a complex access policy, it might be easier to manage a group of subjects (or actions, or resources) in the policy. Here are some examples of groups:

• Employees in IT department
• Sale agents managing merchants in Bangkok
• A campaign administrative action which consists of all actions available to manage a campaign
• A restrictive user role which can only view basic merchant information
• A group of APIs which returns personal user information

The WeOmni Authorization Platform provides APIs to manage groups and entities within a group. Groups can be described in an access policy the same way like other policy properties.

The following picture illustrates an access policy with groups.

Access Policy Enforcement

Access policy enforcement is a process to determine whether the subject is allowed to perform an action on a resource. It is done by comparing the request context (consisting of subject, resource and action) with the created access policies and only allows if the request context matches any access policies.

To provide better understanding, consider the following access policies.

Here are some examples of the result after passing the request context to the acceess policy enforcement API.

Context		Allowed? / Denied?	Notes
Subject	Resource Action
James	View orders	Allowed	Because James is in IT department. Or, James is an administrator.
James	Update orders	Allowed	Because James is an administrator.
James	Delete orders	Allowed	Because James is an administrator.
Mary	View orders	Allowed	Because Mary is in IT department.
Mary	Update orders	Denied	No matched policy.
Mary	Delete orders	Denied	No matched policy.
Pam	View orders	Denied	No matched policy.
Pam	Update orders	Denied	No matched policy.
Pam	Delete orders	Denied	No matched policy.
Bob	View orders	Allowed	Because Bob can view orders.
Bob	Update orders	Denied	No matched policy.
Bob	Delete orders	Denied	No matched policy.

Integration Example

Requirements

In this example, we will explain how to utilize the WeOmni Authorization Platform to create a reporting system for Amanda Corp. Permission to view a report will be in hierarchical structure, that is, a supervisor (direct or indirect) is able to view a report of his / her subordinates.

Below is the organization structure of the Amanda Corp.

Given the above structure, here are some examples of how the permission works.

• Amanda can view everyone's reports because she is the CEO of the company
• Paul can view Jane's and Emma's reports including their subordinates' reports
• Pam can view Tim's and Billy's reports
• Tim can view only his own reports

Access policy design

To satisfy the requirements, we can define the access policies as follows.

This can be done in the WeOmni Developer portal or by directly calling the WeOmni Authorization Platform APIs, the process can be split into the following steps.

1. Define resource groups and their relationships
2. Associate a resource to a resource group
3. Define subjects
4. Define access policies

Resource Group Definition
First, let's start by define a resource group and its relationship to create the hierarchical structure above.

1. Create a resource group with key reports-company to represent reports in the company
2. Create a resource group with name reports-division-ap to represent reports in Asia Pacific division
3. Add reports-division-ap to the resource group reports-company
4. Repeat until resource group structure is completed

Resource Definition
In this step, we create a resource and if the resource belongs to a group, associate it to its group.

1. Create a resource Smith-2020-01.pdf
2. Create a resource Smith-2020-02.pdf
3. Associate Smith-2020-01.pdf to the group reports-division-ap
4. Associate Smith-2020-02.pdf to reports-division-api
5. Repeat until resource association is completed

Subject Definition
The step to define a subject is pretty straight-forward, in this case, we will simply create a subject for each person in the company. We could also create a subject group for easier management but it is not required in this example.

1. Create a subject Amanda
2. Create a subject Paul
3. Repeat until all subjects are created

Access Policies Definition
The last thing is to create access policies and associate subject, resource and permitted action together.

Subject	Action	Resource
Amanda	view	reports-company
Paul	view	reports-division-na
Smith	view	reports-division-ap
Jane	view	reports-department-marketing-na
Emma	view	reports-department-sales-na
Mary	view	reports-department-marketing-ap
Pam	view	reports-department-sales-ap
Tim	view	reports-officer-tim
Billy	view	reports-officer-billy

Application API design

In this example, we will structure the application server to extract the information about the subject and resource (reports) it wants to access.

The application can define the APIs as follows to return resources from different organization structure.

Constraints and Limitations

Here are use cases that the WeOmni Authorization Platform does not support by the current design. WeOmni platform development team may enhance the WeOmni Authorization Platform in future to support them.

Listing resources the subject has access to

Currently, the WeOmni Authorization Platform cannot return resources that the subject has access to, for example, the following questions are not supported by the APIs:

• What reports can the subject 'Amanda' view?
• How many shops can the subject 'James' manage?