@restorecommerce/acs-client

!Versionversion!Build Statusbuild!Dependenciesdepend!Coverage Statuscover
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 | | operationstatus | 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 | | ----- | ---- | ----- | ----------- | | policysets | 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