How do ACLs work?

Introduction:

ACLs is an extra authentication backend in ADR Nexus server. It has a predefined set of permissions that can be reused across user-groups and object categories. These permissions and their association with object categories are stored in the database, making them persistent. ACLs is backwards compatible: older versions of external tools like template editor and EnSight can still communicate without changing anything.

Basics:

Users/Groups

• A standard user in Ansys Dynamic Reporting can be assigned to a particular group, or more than one group.

• A group can also contain multiple users. (A many-to-many relationship between user and group)

• A user may or may not belong to a group.

• You must add users to the appropriate groups depending on their roles.

• In order to make use of ACLs, a user must belong to at least one group.

Superusers

• A superuser or admin (eg. the default nexus user) is a user who has uncontrolled and unrestricted access to almost every operation and object in Ansys Dynamic Reporting, regardless of which group he/she belongs to. Objects available to a superuser are unfiltered.

• Almost any operation that is requested by a superuser will not undergo any permission checks through ACLs. So, please create superusers carefully.

• Unlike users, a superuser only sometimes may need to belong to a group in order to make use of ACLs and categories, depending upon the operation.

Categories

• Categories, in addition to being a way of grouping similar kinds of data objects, are also a way of defining access of a user-group over a set of objects.

• The permissions of a user-group over an object category applies to all objects assigned that specific category. Eg: if a user X belongs to group A and group A has 'change' permissions on an item category C, then the user has 'change' permissions (i.e can edit all items) over all objects that are assigned the category C.

• For backwards compatibility, all existing items(which will have no categories assigned) from old databases will be visible to any user without restrictions. When filtering occurs, a user is shown all items he has permissions on AND also all items that do not have any categories assigned(i.e do not have any permissions assigned through the categories).

• Note that at any point, a user will only be able to perform operations with/on categories that the user owns, i.e has 'own' permissions on through any of the groups the user is a member of. The only exception to this is the superuser who has unrestricted access and can perform any operation on all available objects and categories.

Permissions

• Access of user-groups over objects are controlled through several predefined permissions.

• Even though users may not belong to a group at all, in order to make use of the ACLs feature, a user must belong to at least one group. This is because users cannot have permissions of their own.

• There are 4 basic permissions: add, change, view, delete. There is one 'super' permission : own, which overrides all the 4 basic permissions.

• A group can be assigned one or multiple permissions. Similarly, one permission can be assigned to one or multiple groups. (A many-to-many relationship between group and permissions)

• If a user has 'change' permissions, he is automatically assumed to have 'view' permissions as well.

Permissions are of 2 types:

- per-category

- global

per-category permissions

• A per-category permission is, as it suggests, permission of a group tied to one specific object category. For example: with an item-category, a permission assigned for a group G to a particular category A is specific to that category (and inherently, the items assigned that category) and is called a per-category permission.

• An object-category can have multiple groups/users with multiple permissions assigned on itself. Example: item-category A can be owned by group A and group B, only viewed by group C, only changed by group D, only changed or deleted by group E, and so on. It is very flexible.

global permissions

• In addition to per-category or per-item permissions, we also have global permissions which are permissions on all objects of a class/type. These are the permissions available through the admin interface while creating/editing a group. This will override any per-category permissions. Example: If the 'Can delete item category' global permission is assigned to a group G through the admin interface, group G (and in turn any user belonging to G) will have 'delete' permissions over all item categories(and in turn all items assigned any category).

• In any case, a global permission will always take priority over per-category permissions.

• Note that even though the implementation exists, per-category 'add' permissions do not make sense because there won't be any category to check the add permission on, unless you add it. Hence, we just use 'global' add perms for these cases.

• A user's group needs to be assigned the global 'Can add item' permissions and 'Can add item category' permissions to create an item and an item-category respectively.

Working:

The working is simple and straightforward:

• When you create a category, it is saved in the database along with the permissions and the user groups that were specified for the category.

• A relation is created in the database between that category and the list of groups through the permissions that were specified, respectively.

• The available category may then be assigned to any object: in our case, items.

• Whenever you deal with a category, it has to be owned by at least one of your groups in order for you to edit, delete or assign it to an object.

• Once an object is assigned a category, the permissions specified for the groups initially, will apply to the object as well.

• Henceforth, any access to that object must go through a layer of permission checks which check if any of the user's groups have the required permissions on at least one of the categories assigned to that object. If not, access to that object will be denied. This check makes use of the relation that was stored in the database initially.

• Similarly, the list of objects that a user has permissions on, is determined by the categories that the user has permissions on, through the various groups the user belongs to. For example, when querying for items to delete in Ansys Dynamic Reporting, only those items with categories on which the user's group(s) has 'delete' permissions, are returned.

• At any point, if a user is not authenticated/logged in, i.e is 'Anonymous', and whatever object he is trying to access has no owner-group assigned to any of its categories(i.e the object has no owner), the anonymous user will be given access to it. Objects with categories that have owners need authentication and membership in the corresponding group that owns any of the categories.