@restorecommerce/acs-client NPM

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.

It is also possible to configure authorization:unauthenticated_user as subject with identifiter and token in the configuration, if the subject is empty then the token from this configuration will be used.

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	(https://github.com/restorecommerce/access-control-srv#whatisallowed)	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.