# 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

WeOmni Authorization
WeOmni Authorization
Policy Management
Policy Management
Policy Enforcement
Policy Enforcement
Viewer does not support full SVG 1.1

# 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.

Users in IT department have administrative access to the company IT wiki space
Users in IT department have administrative access to the company IT wiki space
Users in IT department
Users in IT department
MaryJames
Administrative permissions
Administrative permissions
viewupdateIT wiki space
Access Policy
Access Policy
Viewer does not support full SVG 1.1

# 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.

Users in IT department can view orders
Users in IT department can view orders
Administrators can administrate orders
Administrators can administrate orders
ordersordersIT usersview
Policy
Policy
Policy
Policy
James
Subject Group
Subject Group
IT departmentMary
            Administrate action group
            Administrate action group
Action Group
Action Group
updateviewdelete
Bob can view orders
Bob can view orders
Boborders
Policy
Policy
viewAdministratorsadministrateAdminstratorJamesBobHR departmentPam
Viewer does not support full SVG 1.1

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.

Amanda Corp. Organization Strructure
Amanda Corp. Organization Strructure
PaulNorth AmericaDIvision ManagerAmandaCEOSmithAsia PacificDIvision ManagerJaneMarketing ManagerEmmaSales ManagerMaryMarketing ManagerPamSales ManagerTomMarketing OfficerAdamSale AgentJohnMarketing OfficerTimSale AgentBillySale Agent
Viewer does not support full SVG 1.1

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.

Access Policy Design
Access Policy Design
Company ReportsNorth AmericaReportsAsia PacificReportsNorth AmericaMarketing ReportsNorth AmericaSales ReportsAsia PacificMarketing ReportsAsia PacificSales ReportsSmith 2020-01.pdfSmith 2020-02.pdfPam 2020-02.pdfTim 2020-02.pdfBilly 2020-02.pdfJohn 2020-02.pdfAmandaPaulSmithJaneEmmaMaryPamTim ReportsBilly ReportsBillyTim
Viewer does not support full SVG 1.1

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.

WeOmni Platform
WeOmni Platform
WeOmni
Authorization
WeOmni...
View reports
View reports
Report ViewerApplication
Call policy enforcement API
Call policy enforcement API
Application Server
Application Server
Manage access policies
Manage access policies
Administrator
View reports
View reports
User
Manage access policies
Manage access policies
WeOmni
Developer Portal
WeOmni...
Reports
GUI for WeOmni platform administration
GUI for WeOmni platform admi...
Extract subject and
resource from request
Extract...
Viewer does not support full SVG 1.1

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?
Last Updated: 7/17/2020, 11:09:13 AM