@restorecommerce/acs-client

acs-client

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. For write operations it uses isAllowed and for read operations it uses whatIsAllowed operation 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 Decision or policy set reverse query PolicySetRQ depending on the requeste operation isAllowed() or whatIsAllowed() respectively.

Request

Field	Type	Label	Description
subject	io.restorecommerce.user.Subject or io.restorecommerce.user.ApiKey	required	User Subject user details (ID, role-associations and hierarchical scopes) or ApiKey
request	Resource or Resource [ ] or ReadRequest	required	list of target resources or read request
action	Enum	required	action to be performed on the resource (CREATE, READ, MODIFY, DELETE or ALL)
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
Decision	Decision	optional	Access decision; possible values are PERMIT, DENY or INDETERMINATE
PolicySetRQ	PolicySetRQ [ ]	optional	List of applicable policy sets

Resource

Field	Type	Label	Description
type	string	requried	resource entity name
fields	string [ ]	optional	list of fields for accessing or modifying resource
instance	string	optional	instance identifier of the resource
namespace	string	optional	namespace prefix for resource entity

ReadRequest

Field	Type	Label	Description
entity	string	requried	resource entity name to be read
args	io.restorecommerce.resourcebase.ReadRequest	optional	query arguments
database	string	optional	database for read request, currently arangodb and postgres are supported
namespace	string	optional	namespace prefix for resource entity

Decision

Field	Type	Label	Description
decision	io.restorecommerce.access_control.Decision	required	Access decision; possible values are PERMIT, DENY or INDETERMINATE

PolicySetRQ

Field	Type	Label	Description
policy_sets	[ ] io.restorecommerce.policy_set.PolicySetRQ	required	List of applicable policy sets

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.

flushCache

This API flushes the ACS cache from redis. An optional prefix key can be provided to flush instead of entire cache.

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