Permissions (beta)

Permissions can be used to restrict access for specific features, so only authorized users can access them. In principle, a User needs an ALLOW connection to a Permission to be able to access functionalities that require that Permission.

Permission checks against the database are only performed when permissionsEnabled is set to true in the configuration, and the license edition includes the Permission feature. If permissions are disabled, every logged-in user is treated as having full (root) access.

The Permission node

Permissions are defined as nodes with an IA_Permission label, and can have the following properties:

Key	Description	Value
name	The name of the Permission (must be unique). If set to a built-in Permission name (see below), it will be used to determine access to the specified Graphileon core functionality.	string
error	Error message to display when access is denied.	string
expression	Javascript expression to evaluate whether the user should have access. *	Javascript string
cypher / gremlin / sparql	Query to execute against the store to determine whether the user should have access, in the given query language. *	Query string
query	Fallback query, used only if none of the language-specific query properties above are set.	Query string
store	The name of the store on which to execute the specified query. Defaults to application.	string
batch	If true, the Permission is evaluated once for a whole result set (batch) instead of once per row when used with filter/flag REQUIRE relations. The expression/query should then return an array with one {allow: boolean} object per row.	boolean

* Queries should return only one row with an allow (boolean) column, that determines the user's access. Expressions can either return a boolean directly, or an array with a single object containing an allow property (similar structure to the query result). If both an expression and a query are defined, both have to allow access.

* Both queries and expressions can use parameters, prefixed with $ (e.g. $myParam === 123). Parameter values are filled in by REQUIRE relations to the Permission, similar to how Triggers fill in parameter values for Functions.

* In contrast to Functions and Triggers, the global (@) symbol only contains user (for the currently logged in user) and version (Graphileon version) properties.

Granting permissions: ALLOW and DENY relations

A user is granted a Permission through an ALLOW relation:

(user:IA_User)-[:ALLOW]->(permission:IA_Permission)

The connection may also be indirect, through up to 3 MEMBER hops (e.g. team membership, or nested teams):

(user:IA_User)-[:MEMBER]->(team:IA_Team)-[:ALLOW]->(permission:IA_Permission)
(user:IA_User)-[:MEMBER]->(team:IA_Team)-[:MEMBER]->(parent:IA_Team)-[:ALLOW]->(permission:IA_Permission)

Similarly, a DENY relation (direct, or indirect through MEMBER relations) explicitly denies a Permission:

(user:IA_User)-[:DENY]->(permission:IA_Permission)

A DENY relation always takes precedence: if a user has both an ALLOW and a DENY path to the same Permission, access is denied. DENY even overrides the root permission (see below).

The root permission

A user with an (indirect) ALLOW relation to the Permission named root is granted all permissions, and skips the evaluation of expression/query properties of other Permissions. Only an explicit DENY relation to a specific Permission can still deny access for such a user.

Evaluation order

When a Permission is checked for a user, the following steps are taken, in order:

1. If the context entity has a public: true (or $public: true) property, access is allowed without further checks.
2. If the user is not logged in, access is denied (NotLoggedIn).
3. If the user has a DENY path to the Permission, access is denied (DeniedByRelation).
4. If the user has the root permission, access is allowed.
5. If the user has no ALLOW path to the Permission, access is denied (NoALLOWRelation).
6. The Permission's expression (if any) is evaluated; if it does not allow, access is denied (DeniedByExpression).
7. The Permission's query (if any) is executed; if it does not allow, access is denied (DeniedByQuery).
8. Access is allowed.

Requiring permissions: the REQUIRE relation

Any node (e.g. a Function, Dashboard, or a plain data node) can be protected by connecting it to a Permission with a REQUIRE relation. The for property of the relation determines which action the Permission is required for:

(node)-[:REQUIRE {for: 'read'}]->(permission:IA_Permission)

When the corresponding action is performed on the node, all Permissions connected with a matching REQUIRE {for: ...} relation are checked, and all of them must allow access. A node without REQUIRE relations is not restricted (beyond the reserved CRUD permissions listed below).

The following for values are used by the Graphileon core:

for value	Checked when	Notes
read (default)	A node, Function or Dashboard is read/loaded.	Also used to filter the dashboards listed for a user.
execute	Before a Function instance executes.	Checked at execution time (in addition to read, which is checked when the Function is loaded). If denied, the Function does not execute and the error is shown to the user.
query	Before a Query Function executes.	Event context contains store, params and options.
filter	After a Query Function executes; rows that are not allowed are removed from the result.	Event context contains params and data (the result table); for non-batch Permissions each row is checked separately with (%).row.
flag	After a Query Function executes; adds a column (default _permissions) with an allow/deny flag per Permission, instead of removing rows.	Column name can be changed with the Query Function's permissionsColumn parameter.
send	Before an Email Function sends an email.
request	Before a Request Function executes.
action:{action}	Before a DataManagement Function performs the given action (e.g. action:create, action:read, action:update, action:delete, action:import).	See DataManagement for the available actions and their contexts.

Passing parameters to the Permission

Properties of the REQUIRE relation that are prefixed with $ are evaluated as expressions and passed as parameters to the Permission's expression and query. Within these expressions, (%) refers to the event context of the action (see the table above), and (@) to the global context (user, version).

Example: restrict reading of a node

Only users connected to the document:read Permission can read the Document node:

(doc:Document)-[:REQUIRE {for: 'read'}]->(p:IA_Permission {name: 'document:read'})
(user:IA_User)-[:ALLOW]->(p)

For an example using parameters and a query-based Permission, see the DataManagement permission examples.

Permission error codes

When a permission check fails, the resulting error contains one of the following codes:

Code	Meaning
NotLoggedIn	The user is not logged in.
Denied	Access denied (generic).
NoALLOWRelation	The user has no (indirect) ALLOW relation to the Permission.
DeniedByRelation	The user has an explicit (indirect) DENY relation to the Permission.
DeniedByExpression	The Permission's expression did not allow access.
DeniedByQuery	The Permission's query did not allow access.
InvalidPermission	The Permission definition is invalid.

The message shown to the user can be customized with the Permission's error property.

Reserved permission names

There are a number of permission names that are used to control access to Graphileon core. Basic CRUD (create/read/update/delete) permissions are common to all entity types listed below. For example, all listed entities have the read permission. The full name of the read permission for the User entity would be user:read, whereas for Dashboard it would be dashboard:read.

The CRUD permissions below can be applied to any of these entity types: app, dashboard, diagram, file, function, node, permission, profile, relation, store, team, token, trigger, user and style.

Permission	Allows to	Context	Examples
create	Create an entity	The entity to create	user:create, trigger:create
delete	Delete an entity	The entity to delete	user:delete, trigger:delete
read	Read an entity	The entity to read	user:read, trigger:read
write	Create/update/delete an entity	The entity to write	user:write, trigger:write

CRUD Exceptions

Permission	Note
app:{permission}	For all App CRUD permissions, please refer to the App data structure.
function:read	Is granted automatically to all logged-in users (no Permission node required).
user:delete	Is granted automatically to any user attempting to delete their own User.
user:read	Is granted automatically to any user attempting to read their own User data.

Additional permission names

Besides the basic CRUD permissions, Graphileon has the following reserved permission names:

Permission	Allows to	Context	Notes
email:custom	Write a custom email	Email Function
language:translate	Manage translations
query:custom	Execute custom query	function: Query Function node queries: executed queries (by language) store: the store to execute against
query:debug	See query debug info
settings	Manage settings
store:config-info	Get installation info
store:test-connection	Test connection to a store	Store config
team:add-team	Add team to other team	parent: Parent team node child: Child team node
team:add-user	Add user to team	team: Team node user: User node
team:remove-team	Remove team from other team	parent: Parent team node child: Child team node
team:remove-user	Remove user from team	team: Team node user: User node
team:users	List team user	Team node
user:dev-mode	Set own user to dev mode	User node to update
user:review-request	Review user registration requests	User node to review
debug	View debug information