oe-data-acl

Introduction

Standard Loopback ACL feature allows defining access type (READ/WRITE) on a remote-method or API level. This means, if READ permission is granted for certain Model, all the records can be read. Conversely, if READ permission is NOT granted, none of the records can be accessed. The Data ACL functionality provides the missing feature of specifying the filter conditions on data for specific role or user.

The Data ACL functionality builds on top of Loopback ACL, documented here. It is a recommended read before this document.

Dependency

  • oe-logger
  • oe-cloud

Development

$ git clone http://evgit/oecloud.io/oe-data-acl.git
$ cd oe-data-acl
$ npm install --no-optional
$ npm run grunt-cover

You can find coverage report in coverage folder.

Installation

$ npm install oe-data-acl --save

Enabling the feature

To enable this feature, you must add an entry into application’s app-list.json file as shown below.

  {
    "path": "oe-data-acl",
    "enabled": true
  }

Using Data ACL

Data ACL rules are described as an array of objects, each of which consists of attributes of Data ACL model

Property Required Description
model Required Model Name
principalType Required The type of access to apply. One of:
  • USER
  • ROLE
principalId Required Principal identifier (Depending upon principalType). The value must be one of:
  • A user ID
  • One of the predefined dynamic loopback roles like $everyone, $owner etc.
  • A static role name
filter Required Only the where part of the loopback filter object, determines which data can be accessed by user
property Optional Model’s Method Name (create, update etc.)

use * or blank for all properties.

Example for methods on relations __create__addresses, addresses is relation name here.

accessType Optional READ, WRITE, EXECUTE, * (for all)
group Optional To use a mix of and and or conditions, different group value can be used to make and condition for filters. Multiple Data ACLs with in same group are always or condition. All Data ACLs with no group value are treated as a single same group.
errorCode optional error code to be used for data access error

It is mandatory to setup Loopback ACL along with Data ACL to get combined functionality, as Data ACL supports filter for ALLOW only.

Examples

Standard ACL for allowing WRITE access on a model to role ROLE123 is given as below

{
      "accessType": "WRITE",
      "principalType": "ROLE",
      "principalId": "ROLE123",
      "permission": "ALLOW"
}

To restrict access only where category property of the model is Books, and entry in Data ACL model can be posted.

{
        "model": "modelABCD",
        "principalType": "ROLE",
        "principalId": "ROLE123",
        "accessType": "WRITE",
        "filter": {"category": "Books"}
}

The filter condition supports standard loopback conditions, which can include operators like or, and, inq etc.

Examples

{
    "filter": {"department": {"inq" : ["d1", "d2", "d3"]}
}
{
    "filter": {"or":[{"field1": "value1"},{"field2": "value2"}]}
}
{
     "filter": {"and":[{"field1": "value1"},{"field2": "value2"}]}
}

If Data ACL is not defined, user can access all the data provided ACL allows it.

Dynamic values in filter

For dynamic values, you can refer any call context field using @CC. or @ctx.. Example

{
     "filter": {"approver" : "@CC.username"}
}

Multiple Data ACLs

System allows multiple Data ACLs for same model and property. In case multiple Data ACLs are applicable for a given principal, filters of all Data ACLs with no group specified are taken as OR condition.

For example following two Data ACLs will actually apply a single filter condition like category is Books or Music.

{
        "model": "modelABCD",
        "principalType": "ROLE",
        "principalId": "ROLE123",
        "accessType": "WRITE",
        "filter": {"category": "Books"}
}
{
        "model": "modelABCD",
        "principalType": "ROLE",
        "principalId": "ROLE123",
        "accessType": "WRITE",
        "filter": {"category": "Music"}
}

Usage of Group property in Data ACL

To use a mix of and and or conditions

For example following Data ACL combines to single filter category (Books or Music) and Country (India or Ireland)

{
        "model": "modelABCD",
        "principalType": "ROLE",
        "principalId": "ROLE123",
        "accessType": "WRITE",
        "group" : "category",
        "filter": {"category": "Books"}
}
{
        "model": "modelABCD",
        "principalType": "ROLE",
        "principalId": "ROLE123",
        "accessType": "WRITE",
        "group" : "category",
        "filter": {"category": "Music"}
}
{
        "model": "modelABCD",
        "principalType": "ROLE",
        "principalId": "ROLE123",
        "accessType": "WRITE",
        "group" : "country",
        "filter": {"country": "India"}
}
{
        "model": "modelABCD",
        "principalType": "ROLE",
        "principalId": "ROLE123",
        "accessType": "WRITE",
        "group" : "country",
        "filter": {"country": "Ireland"}
}