Access Control List

Access control list (ACL) is the new implementation of instance-level security which supports two basic ways of controlling an access to an entity:

• configuring an owner with an unlimited access
• configuring various entries that might grant or deny certain operations (e.g. read/write or even modify ACL permissions) to certain roles

Basically, using the access control list you can grant or deny CRUD and custom operation permissions to different roles on instance level.

Besides that, there is a way to override all these checks by configuring the Administrable meta-data. Since this defines a universal override of the configured security, we will mostly ignore this when discussing concrete use cases to avoid being repetitive.

All security checks (except for the Acl and AclEntries deletion) can be overridden with the Administrable meta data.

Administrable

This MD can be configured on HasAcl or Acl types, and is typically configured with a RoleSelector and a UseCaseSelector with use-case being "acl". Configuring this MD on HasAcl grants rights on any HasAcl sub-type, while configuring it on Acl grants rights to modify the Acl.entries property.

To use ACL in your model, make sure to have the access-control-model as a dependency.

General

The access-control-model's HasAcl interface introduces the acl property where you can add individual ACL entries. To be able to manage permissions on instance level, make sure that your model depends on the access-control-model and the entity type you want to manage permissions for extends HasAcl.

If your entity type extends HasAcl you can set an owner and an ACL for it's instance. Instances inheriting after HasAcl are checked by the SecurityAspect when being queried or manipulated by the privileged roles defined by the individual ACLs. Other operations are checked by custom code.

The Acl interface is the main force behind the ACL functionality.

The operation permissions are resolved based on the entries in the permission list, which is populated with AclEntry instances.

For an overview of all ACL-related classes, see JavaDoc.

ACL Entries

It is the entries in the list that control the operation permissions for a given role. Each entry must contain:

• an AclPermission - GRANT or DENY
• a role
• an AclOperation

The ACL works by accumulating the effects of the single entries. Entries with an AclPermission.DENY permission are treated with priority over the entries with an AclPermission.GRANT permission for the same operation.

Acl instances are used on and shared amongst HasAcl instances to control access to them.

An AclEntry is a single immutable entry that either grants or a denies a concrete operation for a single role. The standard operations (it is possible to define your own and implement support for it) are given by the AclOperation enum (which is available as a property on AclStandardEntry). The individual constants have the following semantics:

Even though an AclEntry grants or denies a concrete operation for a single role, you can use $all as the role which applies the given entry to all users. Also bear in mind that when you assign a WRITE permission for a role, you must assign the same role a READ permission as well. Otherwise, that particular role will not have read access to the entity instance and the instance will not even be displayed in Control Center.

Note that with ASSIGN_ACL we check the old Acl value which is being overwritten. We do not however check the newly assigned Acl at all, so it is theoretically possible for a user to assign such Acl that the users themselves won't be able to access the entity later.

For more information on user roles, see User Roles

HasAcl

HasAcl is the super type for access-controlled entity types. It can optionally have an owner that has full access on the instance. All other permissions can be optional by assigning a sharable Acl to the acl property.

If an instance has an owner the absence of an Acl means that no one else has any access to the instance. If an instance has no owner, the absence of an Acl means that everybody has full access to the instance.

A security aspect configured to a persistence layer changes the queries on every type that extends HasAcl to filter by access rights within the persistence layer to properly support paging. Also, the updates on the persistence layer should be checked to happen within the limits of the assigned access rights.

Furthermore, the returned deep structure from the filtered top-level entities should be trimmed whenever the access control demands it. This can only happen after the initial query has already filtered the top level.

If we examine the HasAcl type, it has two different properties that offer two different ways how to protect an entity.

HasAcl.owner is a property which contains the name of the user who has an unlimited control over the entity. It is very important to remember that the owner property can only be set when creating the entity or by the user who currently owns the entity.

HasAcl.acl is a property which can be assigned with an Acl instance, which is an object that aggregates access information based on user roles (i.e. describes which role is allowed to perform what kind of an operation). This property can only be assigned when creating the entity, but the current user, or if the current user currently has the right to replace or modify the Acl, which is explained later.

Acl is just a collection of AclEntries which are stored in the Acl.entries property, and contains another property called accessibility which cannot be modified by a user but is managed automatically, and contains pre-processed information which reflects read-access defined by entries. This is only used as an optimization to make querying faster. Every time an Acl is modified, this accessibility is updated automatically.

Using Access Control

Every entity instance whose entity type extends HasAcl has an acl property where you can assign (also with GME) instances of ACL.

For more information, see Using Access Control