@restorecommerce/acs-client

Access Control Service Client

Usage no npm install needed!

<script type="module">
  import restorecommerceAcsClient from 'https://cdn.skypack.dev/@restorecommerce/acs-client';
</script>

README

acs-client

VersionBuild StatusDependenciesCoverage Status

Features:

  • A generic client for the access-control-srv.
  • It uses grpc-client to access the exposed API via its gRPC interface.
  • It constructs the request object expected by access-control-srv when requesting access to a particular resource with a specific action on it.
  • It supports access requests for both methods isAllowed and whatIsAllowed exposed by access-control-srv.
  • It provides an optional caching mechanism for the two operations based on a redis store.
  • It evaluates the condition for whatIsAllowed requests.
  • It returns the decision made by the ACS.

Configuration

The access-control-srv URN configurations needs to be set using authorization configuration to acs-client from access requesting microservice. The URN for the role scoping entity for Organization/ business units must be set using the configuration property authorization.urns.orgScope.

orgScope: 'urn:\<organization\>:acs:model:<Entity_Name>

ex: orgScope: urn:restorecommerce:acs:model:organization.Organization

The caching configurations for redis can be set using authorization:cache configuration.

For testing and debugging the access control checking can be dsiabled as a whole via the enabled flag. This will supress the access control checking via the ACS and always permit any request. If the ACS checks should be performed (and thus logged) but not enforced, the enforce flag can be set to false which is useful for debugging the ruleset.

API

The client exposes the following API:

accessRequest

It turns an API request as can be found in typical Web frameworks like express, koa etc. into a proper ACS request. Depending on Operation respective api's isAllowed and whatIsAllowed are invoked from access-control-srv. Requests are performed providing Request message as input and response is Response message type. For the read operations it extends the filter provided in the ReadRequst of the input message to enforce the applicapble poilicies. The response is DecisionResponse or policy set reverse query PolicySetRQResponse depending on the requeste operation isAllowed() or whatIsAllowed() respectively.

Request

Field Type Label Description
subject io.restorecommerce.user.Subject required Subject user details (ID, token, role-associations and hierarchical scopes)
resource Resource [ ] required contains resource name, resource instance and optional resource properties
action Enum required action to be performed on the resource (CREATE, READ, MODIFY, DELETE or ALL)
ctx ACSClientContext required context containing subject and context resources for ACS
opeation Operation required operation to perform either isAllowed or whatIsAllowed
database string optional database used, currently 'arangoDB' and 'postgres' are supported
useCache boolean optional defaults to true, if set to false then ACS cache is not used and ACS request is made to access-control-srv

Response

Field Type Label Description
DecisionResponse DecisionResponse optional Access decision; possible values are PERMIT, DENY or INDETERMINATE
PolicySetRQResponse PolicySetRQResponse [ ] optional List of applicable policy sets along with obligations if any

Resource

Field Type Label Description
resource string requried resource entity or operation name
id string optional instance identifier of the resource
property string [ ] optional list of fields for accessing or modifying resource

ACSClientContext

Field Type Label Description
subject io.restorecommerce.user.Subject required Subject user details (ID, token, role-associations and hierarchical scopes)
resources CtxResource [ ] optional context resources

CtxResource | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | id | string | required | resource identifier | | meta | io.restorecommerce.meta.Meta | required | meta object containing owner information | | [key] | any | optional | optional resource properties |

Operation | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | | operation | string | required | operation to perform isAllowed or whatIsAllowed |

DecisionResponse

Field Type Label Description
decision io.restorecommerce.access_control.Decision required Access decision; possible values are PERMIT, DENY or INDETERMINATE
obligation Obligation [ ] optional list of obligations
operation_status io.restorecommerce.status.OperationStatus required operation status code and message

Obligation

Field Type Label Description
resource string required resource name
property string [ ] required list of resource properties

PolicySetRQResponse

Field Type Label Description
policy_sets [ ] io.restorecommerce.policy_set.PolicySetRQ required List of applicable policy sets
obligation Obligation [ ] optional list of obligations

isAllowed

This API exposes the isAllowed api of access-control-srv and retruns the response as Decision. Requests are performed providing io.restorecommerce.access_control.Request message as input and response is io.restorecommerce.access_control.Response message.

whatIsAllowed

This API exposes the whatIsAllowed api of access-control-srv and retruns policy sets list containing list of applicable policies and rules. Requests are performed providing io.restorecommerce.access_control.Request message as input and response is io.restorecommerce.access_control.ReverseQuery message.

Caching

This client supports caching for isAllowed and whatIsAllowed access request operations if authorization:cache options are set. The time to live for redis key can be set using authorization:cache:ttl configuration. The hash key for caching the request is generated using MD5 hash algorithm. For whatIsAllowed operations Request Object is used to generate the hash key and for isAllowed operations io.restorecommerce.access_control.Target Object is used since the resource data changes. Each of the ACS request is associated with an ID of subject, this subject ID is included in the hash key as prefix to keep track of mapping between ACS requests and cached data. The cache can be invalidated by invoking flushCache api with subject ID as prefix parameter.

Development

Tests

For a simple example on how to use this client with a access-control-srv check the test cases.

  • Run tests
npm run test

Usage

  • Install dependencies
npm install
  • Build
# compile the code
npm run build