Security and Permissions

Tibbo AggreGate has a flexible and highly customizable security architecture. Most system resources have an associated permission level. A permission level describes who may access the resource.

A Permission level defines if access to some resource is allowed. It works like this: if the permission level of a user requesting access includes the permission level of the requested resource, access is granted. Otherwise, it is denied.

Permission Level	Includes	Comments
None	None	No permissions assigned. This permission level is assigned to any user who tries to access the system without a prior login. Very few operations may be executed with this permission level, such as the login operation, registration of new user account (if the Enable users self-registration global configuration option is enabled) etc.
Observer	None, Observer	The minimal permission level possible. Basically, this level allows to view most information, but no data modification is possible. It can be also useful to give someone "demo" permissions to view certain objects. Observers may view device settings and events, but cannot configure devices and execute operations provided by hardware.
Operator	None, Observer, Operator	This is the permission level most everyday users should have. It allows viewing most non-system data and performing some basic data modification operations. Operators may configure hardware devices and execute device-provided operations, but cannot create/delete devices or edit device communication and data processing settings.
Manager	None, Observer, Operator, Manager	This permission level allows all data browsing and editing activities like managing hardware devices, editing reports templates, creating and managing alerts, etc.
Engineer	None, Observer, Operator, Manager, Engineer	The level that allows all operations with non-system data, including potentially dangerous operations, like running scripts. This permission levels should be assigned to system engineers.
Administrator	None, Observer, Operator, Manager, Engineer, Administrator	This permission level allows the execution of administrative actions: make changes to LinkServer global configuration, stop/restart the server, manage user accounts, etc. Basically, if a user has Administrator permission level within a context, they can do everything with this context.

If you wish to check what permission level is required to access a particular context, variable, function, event or action, please see Context Reference.

Advanced information: To understand what we mean when we say a permission includes another permission, you're going to have to think about permissions as binary bitmasks. If you're not sure what a bitmask is, please see http://en.wikipedia.org/wiki/Bitmask.

A permission level is internally expressed as a bitmask. For example, the internal bitmask for None is 00000000, while for Observer it is 00000001, and for Administrator is 00011111. So, as you see, the Administrator mask (it's a mask - not just a number) includes the Observer and None masks, because it has a 1 in every position where the other masks have 1.

This method is used because it is more versatile and powerful than just a numeric scale (i.e, None is 0, Observer is 1, etc).

If the permission level of a user requesting access to a certain resource is Manager and the required permission level for the resource is Admin, access will be denied because Manager level does not include Admin.

If the permission level of a user requesting access to a certain resource is Manager and required the permission level for the resource is Manager, access will be granted because Manager level includes Manager.

Every context has a default permission level. In order to be able to execute some operations with this context, a user must have this permission level or a higher one for it. Specific variables, functions, events or actions may require other permission levels than the default level.

The default permission level defined for almost all context in the LinkServer is Observer. Here is a list of all exceptions (contexts whose default permission level differs from Observer):

The default permission level of the Root Context of LinkServer is None. It means that even non-authenticated users may execute some actions with this context. But the Restart Server and Stop Server actions that are defined in this context require Administrator permission level in this context. Thus, only users whose permissions table defines Administrator permission level for the Root context will be able to stop or restart the server.

The default permission level of the User context is Observer. But the Delete action defined in this context has an Administrator permission level. Thus, a user having the Observer permission level for this context will be able to view account status, but will not be able to delete it. The Administrator permission level is required for that.

Every user account has a permissions table property. This table is used to determine the permission level effective for a given context. This is the permission level with which attempts to gain access to that context. If the effective permission level of a user includes the permission level of a resource, access will be granted.

The permissions table has two columns: Context Mask and Permission Level. When a user tries to access some resource, LinkServer uses the permissions table to decide whether access should be granted or not. See permission checking for details.

The last line of the permissions table must define permission level for all contexts, i.e. contain the "*" Context Mask.

Every resource (variable, function, event, action) of a context has its own permission level, but there is no way to give users a dedicated permission level to a certain context resource. It's only possible to set a user's permission level for the context as a whole. This means that the system provides pre-defined scenarios of interaction with a context, and permission levels for context resources are assigned to avoid access conflicts in these scenarios. For example, if a certain context action changes some variables of this context, the action's permission level must include the permission levels of any accessed variables, otherwise the action may internally fail with Access Denied error even though the user was allowed to execute it.

When a new user account is created, LinkServer builds a default permissions table for it. The contents of this table depends on the account name, and on the contents of two LinkServer global properties: Additional Permissions For New Users and Default User Permissions. If all items are enabled in Default User Permissions and the Additional Permissions table is empty, the permission table for new accounts will be quite simple:

The first line of this permissions table declares Manager-level access to all contexts that are defined under the user's own User context (e.g. users.NAME_OF_USER.alerts etc.).

The second line denies access to contexts of all other LinkServer users by setting None-level permissions for them. Thus, the effective permission level for the context users.user123.widgets will be None (Unless, of course, the new account happens to be user123).

The third line defines Manager-level to all other contexts that are not related to user accounts. This prevents a new user from executing administrative actions. For example, a new user will not be able to view administrative events because the Default Permission Level of the Administration context is Administrator. They would also not be able to stop or restart the LinkServer, because the Stop server and Restart server actions (defined in the Root Context) require Administrator-level access to this context.

The items in Default User Permissions property are listed under Default User Permissions. If they're all disabled, the permissions table of a new account will contain several additional restrictive records:

Context Mask	Permissions
users.NAME_OF_USER.dsgroups	None
users.NAME_OF_USER.devgroups	None
users.NAME_OF_USER.filters	None
users.NAME_OF_USER.alerts	None
users.NAME_OF_USER.common	None
users.NAME_OF_USER.jobs	None
users.NAME_OF_USER.queries	None
users.NAME_OF_USER.widgets	None
users.NAME_OF_USER.autorun	None
users.NAME_OF_USER.favourites	None
users.NAME_OF_USER	Manager
users.*	None
common	None
reports	None
*	Manager

These additional records prevent the user from accessing two global contexts (Global Common Data container and Reports) along with some of his own contexts (Alerts, Queries etc.).

All records from the Additional Permissions For New Users table are added to the top of the permissions table and thus have highest priority. For example, let's assume we have two records in the Additional Permissions table:

Assuming all items in Default User Permissions are enabled, we'll get the following permissions table for a new user:

Context Mask	Permissions
users.NAME_OF_USER.widgets	Administrator
external_device_servers	Administrator
users.NAME_OF_USER	User
users.*	None
*	User

When a user tries to access a resource, LinkServer browses his permissions table line by line, starting from the first (topmost) one.

If the context path of the resource being accessed matches or extends the context mask defined in the current line of the permissions table, the permission level defined in this line will be used as the effective permission level for this path. Once a matching line is found, no other lines are matched. So, for example, if you start the table with the * context (i.e, that's the first line in the table) no other lines will ever be checked, because that line matches all contexts. That's why * is always the last line in the table.

The effective permission level determined at the previous step is then compared with the permission level required by the resource being accessed. If the effective permission level includes the permission level required by the resource, access is granted. Otherwise, it is denied.

If the context path of the accessed resource doesn't match or extend any mask defined all throughout the table, the effective permission level for the resource being accessed is defined by the last line in the permissions table, because it always defines the permission level for all contexts (* Context Mask).

Line	Context Mask	Permissions
1	users.test	Manager
2	users.*	None
3	*	Manager

1. John tries to access user.abc.alerts. The permission level required to access that resource is Manager. The first line in the table, users.test, doesn't match or extend the users.abc.alerts mask, so we move on to the second line, users.* and see that it does extend users.test. This second line specifies None as the permission level, and so access will be denied.

2. John tries to access event_filters.filter1, requiring a Manager permission level. John's effective permission for event_filters.filter1 will be defined by the third line in the table, and thus access will be granted.

3. John tries to access users.test.queries, requiring an Administrator permission level. His effective permission level for that context is defined by the first line in the table. It will be Manager (lower than Administrator), and thus John will be denied access to users.test.queries.

The effective permission level of the default administrator for any context is Admin, because all context paths extend the * mask. So the administrator may execute any operation in any context.

When a user's permission table is adjusted so as to keep them from accessing some of their own resources, the resources are not actually destroyed or affected in any way. In fact, some other user may have access to these resources even if their owner has no access to them.

John, the guy from the last example, has an Alerts context, users.john.alerts. This path always exists. Initially John can access his Alerts, because Default User Permissions let him do so. He logs onto LinkServer and creates an alert, alert1. Then, the administrator adjusts John's permissions table so that John can no longer see his Alerts context (for example, by adding a record with Context Mask users.john.alerts and Permissions None to the beginning of the table). This does not destroy alert1. It doesn't even stop it from working. Some other LinkServer users may still have access to this alert, and be able to configure and monitor it. Once the administrator lets John access his alerts again, alert1 will show up under his Alerts context.