Permissions

In most applications not all data and functions are accessible for all users. And if data is accessible for a user, then possibly the user might only be allowed to read the data, not change it. Or the user is only allowed to see a subset of all records of a class, or only a subset of fields. This all can be defined by permissions. Permissions are organized in user groups that represent the different kinds of users of an application. For instance a webshop may define users of the application as customers or shop managers and make a user group for both of these types of users.   

There are three types of user groups:

• anonymous
  Anonymous users do not have to be identified. Has no permissions by default.
• regular
  Identified users have to logon to the application, usually with a login name and password combination. Has no permissions by default.
• super
  Super users are identified users who can generally perform more actions and access more data than normal users. Has broad permissions by default.

Class permission

The most basic permission is the class permission. The class permission has properties for search, read, update, insert and delete.

• Search indicates whether a user is allowed to search for records of this class.
• Read indicates whether a user is allowed to read records of this class.
• Insert indicates whether a user is allowed to insert new records of this class.
• Update indicates whether a user is allowed to update records of this class.
• Delete indicates whether a user is allowed to delete records of this class.

You can get to the class permissions either from the class details (tab Permissions), or from the User group details (tab Classes).

Below is an example of class permissions set in a class in the blueprint:

When defining permissions, it is possible to choose a value per operation. The possible values differ per operation.

For the search operation you can choose from several permission values:

• No
  The user is not allowed to search.
• Yes, but hidden
  The user can search, but cannot select the class from the menu. Use this only, when you create your own user interface design and want to provide a different navigation.
• Yes
  The user can search. The user will find an option on the application menu.
• Required
  The user can search, but at least one search field has to be used before the user can start searching.
• Helper
  The permission is calculated by a helper. For expert use only.

For the read, insert, update and delete operation the permission values are:

• No
  The user cannot perform this operation.
• Yes
  The user can perform the operation on all objects in the class.
• User related 
  The permission depends on how the current record is related to the user record.
• Cascading
  The permission depends on the permission of a foreign object.
• Helper
  The permission is calculated by a helper. For expert use only.

About user related permission

The value 'User related' is useful when permission depends on a relationship with the user record of the current user. (To create a user record and it's associated user account see: user accounts)

When setting user-related permission it is important to keep track of the relation between the field or class and the user record. The following situations may apply:

• In case the user is allowed to read its own user record, no relation has to be specified.
• In case at least one direct relation exists between the user class and the concerned class, the application uses the first relation, but we do advice to specify the relation explicitly, since there is no clear definition of "first".
• In case at least one indirect relation exists between the user class and the concerned class (with a maximum of two segments), the application uses the first relation, but we do advice to specify the relation explicitly, since there is no clear definition of "first".
• In all other situations you have to specify the relation explicitly.

To specify the explicit relation between the concerned class and the user class, declare the route in the "route to user class" property in the details view of the permission.

Example: Suppose customers are allowed to read all orders that are related to their own user record (using the relations as defined in the data model). This can be done by setting the Read class permission for the class order to 'User related'.

About cascading permission

The value 'Cascading' is useful when the permission is determined by the permission of a foreign record. If the value 'Cascading' is used for the read permission, the actual value will be the same as the read permission of the foreign record. If the value 'Cascading' is used for the insert, update or delete permission, the actual value will be the same as the update permission of the foreign record.

Example: Customers are allowed to read the order lines that are related to their own orders. This is done by setting the read permission to 'Cascading'. They are also allowed to insert, update and delete order lines. This is done by setting the update permission to 'Cascading'.  

The relation that is used to get to the foreign record has to be set explicitly in the blueprint. This can be done in the class details on the 'Permission' tab.

Field permission

Class permissions apply to every field of a class. Field permissions offer finer control by defining permissions per field. For field permissions to take effect, a class permission must first be in place.

Field permissions are also defined through the search, read, insert and update operations, but not delete.

• Search indicates whether a user group is allowed to use this field when searching for records.
• Read indicates whether this field is shown when viewing a record
• Insert indicates whether a user group is allowed to insert a value for this field when inserting a record.
• Update indicates whether a user is allowed to update this field, Read field permission must be granted.

Field permissions take precedence over class permissions. However, as mentioned, a class permission must be in place for field permissions to take effect.

Here's an example to clarify this: For a user group to be allowed to insert records of a class, the class permission for Insert must be granted. When class permission to insert has been granted, the user group has permission to insert all fields. Setting the Insert field permission of a field to 'no' will result in the user not being able to insert data in this field when inserting a record of the class. It would be redundant to set a field permission for Insert to 'yes'.

Alternatively, the option 'permitted fields only' can be checked in the details view of the class permission. This makes it so the user group has no field permissions until they are granted, reversing the situation described above. For example, with this option checked, setting class permission for Read to 'yes' now means you only have permission to read the class, but none of the fields! You are left with an empty looking record, until you grant field permissions.

Example: When an anonymous user is only allowed to see the 'first name' field of the person class and no other fields, the class permission read should have the value read = yes. This permission must have the 'permitted fields only' property set to true. Now we can go to the Fields tab, select 'person.First name' and set the read = yes.

Notes

When a user is allowed to search for or to insert records of a certain class, the class will automatically appear in the top menu of the application.

Parent user groups

When user groups have partly the same permission concerning classes and fields it can be helpful to define a user group hierarchy. When this is done, a user group might become a "sub-group" of another user group (which would then be its "parent"). A sub-group inherits all permissions from its parent. A hierarchy can be easily defined by setting a parent for a user group in the property "Inherits from" in the Properties tab of a user group.

Example: An application is used by customers and employees. First a distinction is made between customer users and employee users, then a manager might inherit employee permissions and have a few extra of it's own. The manager user group can be made to inherit the employee user group and given extra permissions on top of that.

You can also read about permission helpers.

Notes on security

1. Suppose there is a usergroup with implicit read permission (inherited or because it is a super) and no search permission. As a result, the user is not allowed to search, but they may be offered access to a record through other means than searching (such as a Velocity script). If no explicit read permissions are in place, they may wrongfully be permitted to view this data. 
   
   
2. When making user groups, be sure to work tidily. Cluttered permissions are hard to maintain and allow mistakes to sneak in. Work from the principle that users have no permission until explicitely granted.
   
   
3. A number of field properties can be set that are related to permissions, these allow for more control, but should be used with caution:
   1. Apply read permission of foreign class. This property is used for fields with a foreign class to determine if the read permission of the foreign class should be used to make up the lookup list. When this property is set to false the user will be able to see and select foreign records without having read permissions. Be mindful of the information that is contained in the labels of the foreign class. If, for example, these labels are the first and last name of a person, the user will be shown a list of all persons in the application.
   2. Public blob (read permission is ignored). This property can be set on fields that contain an image or a blob. Setting it to true will make it so the image or blob is always visible, no matter the read permission of the user. Take care to only set this property to true if this image can be shown in any situation, for instance, images for a public web page, or publicly accesible documents.