devel:documentation:security:dev:authorization:evaluators

Introduction

Evaluators are used to provide permissions for database entities to users, they determine what any user can see and do in IdM. An user is assigned one or multiple roles and each role is assigned one or multiple authorization policies. Each authorization policy says "for X kind of entity, give the user permissions A, B and C according to evaluator C". When resolving permissions, the user gets a given permission for a given entity if at least one authorization policy with that permission says the user should have it.

Automatic roles

For common use-cases, IdM provides several roles with preconfigured permissions such as userRole, userManagerRole, superAdminRole and helpdeskRole. Those roles are created during IdM start by processors named Init*RoleProcessor. They're only created if they don't already exist, so editing them is possible and the changes won't get reverted during a restart of IdM.

The codes for automatic roles are in configuration properties idm.sec.core.role.*.

Supported operations

The evaluator isn't an entity by itself, so the only operation that can be done with it is selecting it in the detail of an Authorization Policy and selecting its parameters if it has any.

The evaluator is simply a specification of how an Authorization Policy provides permissions to users.

Lifecycle

Evaluators are usually queried under three different circumstances

Fetching a set of entities

When fetching a set of entities, the getPredicate method for each evaluator assigned to the user for the given entity is called. The permissions required are usually AUTOCOMPLETE, READ or READ_LIMITED, most common exception is the CANBEREQUESTED permission for roles during role request creation.

Rendering frontend elements

Many frontend elements - most often edit/delete buttons - should not be visible to users who don't have the permissions to make use of them anyway. For this reason, during frontend rendering, the getPermissions method for each evaluator will be called with the related entity to see if the user has the required permissions. Some frontend elements then won't appear at all while other will appear differently (e.g. editable fields will become uneditable).
Similar mechanism although without linking to specific entities exists for CREATE buttons and navbar elements - there, the frontend only checks whether the user has any authorization policy that could give them the appropriate permissions for any entity of the relevant type.

Internal queries

Some processes, for example bulk actions, can't be properly solved by manipulating frontend only, so backend code may manually call evaluator functions to assert the user has the appropriate permissions for certain actions - if the user doesn't have those permissions, the situation is resolved by throwing exceptions.

Getting Started

In an IdM with some users and roles, go to the Roles tab, open the detail of a role and click "Permissions". In the detail of a permission, you can select its assigned evaluator and set its parameters if it has any.

Types of Users

Admin

Admin user type refers to a user who usually has the superAdminRole with the APP_ADMIN permission. This user can perform all operations and is not restricted by any permissions in IdM. This kind of account typically only has one role, since the superAdminRole already grants access to everything.

The Admin's tasks with regards to roles and evaluators may include:

Creating new roles and configuring evaluators in their Authorization Policies
Assigning any role to any user
Creating rules for automatic role assignments for any role

Manager

Manager user type refers to a user who usually has the userManagerRole, which grants them the permission to manage certain roles (typically the ones that they're guarantors of).

Their typical tasks with regards to roles and evaluators may include:

Assigning roles they guarantee to users they have permissions for (typically their subordinates)
Creating rules for automatic role asssignments for roles they guarantee

Role request approver

Role request approver user type refers to a user who approves or disapproves a role request created by someone else. Depending on the configuration, this user may have a variety of roles (typically securityRole, helpdeskRole or roleManagerRole).

Their typical task is approving or disapproving a role request created by someone else. This type of user often, but not always, coincides with the Manager type.

Basic User

Basic user user type refers to a user typically with the userRole role.

Their typical task is requesting roles for themselves and usually waiting to have those requests approved by the Role request approvers.

Troubleshooting

Infinite recursion

Since many evaluators use other evaluators in their getPredicate and getPermission methods, there is a risk of creating an infinite recursion if a chain of such calls forms a circle. The simplest such case is combining an IdentityByContractEvaluator with an IdentityContractByIdentityEvaluator.

Note that this problem may occur over a combination of multiple roles. The solution is removing one of the responsible Authorization Policies and achieving the desired business outcome through a different combination of evaluators. If that is impossible, a new evaluator may have to be developed for the use case.