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