ACL (Access Control List) implementation for the frontend. Loosely based on the XACML Standard.
This package contains the ACL engine with Angular integration support (Directive, Service).
A lot of the following is already well documented in the ACL Guide in the IMTP documentation. Take a look for more details.
The idea of ACL is to enable developers to write very flexible Building Blocks that can be adjusted to a wide variety of applications' needs. The following subsections briefly explain the core concepts of ACL.
Everything is a "Resource". Resources are the thing that make ACL work. You can think of resources as all the little things (mostly the visual ones) that make up a component (and thus a Building Block). A resource could be the headline of a Building Block or the first-name input of a form or anything else. Each resource is identified by a unique key (unique to the Building Block). The hierarchy of ACL resources is being taken into account in a Building Block's key when it's used inside an application. That means that two Building Blocks might very well both contain a resource with the key headline. Eventually the calculated keys of these resources would resemble a file path like page-a/header-building-block/headline or page-c/offerings/headline.
The subject states a user or type of user. This could e.g. be customer or agent.
Each resource has one or more "Action" assigned to it. The action specifies in what way the related resource can be manipulated. There are two possible actions: "view" and "edit". Viewable resources can be hidden or shown, whereas editable resources can be made readonly or editable. A headline resource for example can only have an action of "view", whereas a form-control resource could have both actions assigned.
For each resource there are rules (more on them below) that specify how this resource should be treated. The actual "Effect" of such a rule can be either "allow" or "deny". A viewable resource that has an effect of "deny" will be hidden from the user. An editable resource that has an effect of "deny" will be readonly. The latter exclusively applies to form controls.
An "Expression" can further finetune the effect on a resource. Expressions add conditions that further define when an effect will be applied.
The configuration for all resources is made up of "Rules". Each rule states a resource and whether it should be visible/hidden or if it should be editable/readonly. A rule is written in plain text in the following format:
<subject>, <resource>, <expression>, <action>, <effect>Real life examples could look as simple as this:
*, */headline, , view, denyor could get as complex as this:
*, */injured-driver-details/questions/*, s("$['expert-driver-selection'].selectedDriver") == "ANOTHER_DRIVER" and s("$['driver-details'].driver.party.partyType") == "INCOMPLETE_PERSON", view, denyThe entirety of the rules is called the "Policy" and each application is expected to provide this in a file called policy.txt.
The ACL "engine" drives the ACL system and is used to show/hide or enable/disable these resources. This engine receives a configuration (policy) for the various resources during build-time of an app and takes care of validating the expressions to dynamically adjust the applied rules during run-time.
This package provides means to comfortably use ACL in Building Blocks. Resources with a "view" action can be marked as a resource by adding the *aclTag="resource-id" structural directive in the Building Block's template. Resources with an "edit" action are slightly more complex and in most cases need to be added in the component itself.
*aclTag structural directiveThis directive is provided in the AclModule that can be imported from @allianz/taly-acl/angular. This directive accepts a string as value and can be used to mark an element in a component's template as an ACL resource. Elements with this directive can be targeted using ACL rules.
Example:
<h1 *aclTag="'headline'">This is my headline</h1>autoFormBindingFactory()TBD
acl.yml fileAll ACL resources of a Building Block need to be specified in a file called <bb-name>.acl.yml that is stored alongside the Building Block sources. This file is needed to allow app generation through the TALY schematics as well as to provide some insights for the WUI editor which needs to be aware of the available ACL resources in any given Building Block.
For each ACL resource there needs to be an entry in the corresponding *.acl.yml file. Each entry needs to state
aclKeyaclType that can be either display (view) or form-control (edit)labeldescriptiondefault with possible values of allow or denylabel and description will be shown in the WUI editor to explain to the user what this resource is about. The default can be used to state whether a resource should be allowed by default or if it follows an opt-in logic and needs to be allowed explicitly. The default is taken into account during app generation and will be added as a layer of base rules before any of the configured rules in your app-specific policy.txt take over.
Here is an example of such a file for a building block with the resources title, title/icon, message, and input:
- aclKey: title
aclType: display
label: Title
description: The title of this building block
- aclKey: title/icon
aclType: display
label: Title icon
description: The icon shown next to the title (hidden by default)
default: deny
- aclKey: message
aclType: display
label: Message
description: The message of this building block
- aclKey: input
aclType: form-control
label: Input
description: The input of this building blockSo far this file needs to be maintained manually so as a Building Block developer it is your responsibility to make sure that this file is in sync with the Building Block's resources.