Changes

Non-trivial web applications require a user management: Users need to log in too to a web site in order to get access to protected parts of a web site, and depending pages; Depending on their status (role, user group, …), they can be offered different views; etc. One popular way to realize this is to start each RESTXQ function body with a call to a security function. This function raises an exception if The light-weight permission layer simplifies permission checks a user is not logged in, or has not enough permissions to call the requested REST endpoint.lot:

With {{Version|9.0}} of BaseX, a light-weight permission layer has been added: * Functions Permission strings can be annotated with permission strings, andattached to RESTXQ functions.* Global permission With security functions , you can ensure that access to RESTXQ functions will only be written granted to ensure that the current user has clients with sufficient permissions.

<pre classsyntaxhighlight lang="brush:xquery">

</presyntaxhighlight>

The permission strings may denote ids, users, user groups, applications, or any other realms. It is completely up to the user which strings are used, and which functions will be annotated. In the given example code, only the last function has a {{Code|%perm:allow}} annotation.

Functions that are marked with {{Code|%perm:check}} are so-called ''Security Functions''. These functions will be invoked before the actual target actually requested function will be evaluated. Two arguments can be specified with the annotation:

* A path argument can be specified with the as first argument. Such a :** The security function will only be called if the path of the client request path starts with the given stringspecified path. ** In contrast to RESTXQ, all subordinate paths are included herewill be accepted as well.* With * If no path argument is specified, {{Code|/}} is assigned instead.* A variable can be specified in the second argument, various permission-specific information can . A map with the following keys will be bound to a mapthat variable:** {{Code|allow}}: Permission strings attached to the requested function; may be empty.** {{Code|path}}: Original path of the client request.** {{Code|method}}: Method of the client request ({{Code|GET}}, {{Code|POST}}, …).** {{Code|authorization}}: Value of the HTTP Authorization header string; may be empty.

<pre classsyntaxhighlight lang="brush:xquery">

</presyntaxhighlight> Notes: * If several permission functions are available that match the user request, all of them will be called one by one. The function with the shorted path argument will be called first. Accordingly, in the example, if the {{Code|/main/admin}} URL is requested, all three security functions will be run.* If a security function raises an error or returns any result (which can be a redirection or any other XQuery value), no other functions will be invoked. This means that the actually invoked function will only be evaluated if all security functions yield no result or error.* As shown in the first function, the {{Code|%perm:check}} annotation can be combined with other RESTXQ annotations (excluding {{Code|%rest:path}} and {{Code|%rest:error}}).* In the example, it is assumed that a logged in user is bound to a session variable (see further below)

The map, which can be bound to a variable (in this example {{Code|$perm}}), has the following keysSome notes:

{| class="wikitable" width="100%"|- valign="top"! Key! Description|-| * If several permission functions are available that match the user request, all of them will be called one after another. The function with the shortest path will be called first. Accordingly, in the example, if the {{Code|allow/main/admin}}URL is requested, all three security functions will be run in the given order.* If a security function raises an error or returns any XQuery value (e.g. a [[Web Module#web:redirect| Permission strings attached redirection]] to another web page), no other functions will be invoked. This means that the function that has been requested function.|-| {{Code|path}}| Original path of by the client requestwill only be evaluated if all security functions yield no result and no error.|-| * As shown in the first function, the {{Code|method%perm:check}}| Method of the client request (annotation can be combined with other RESTXQ annotations, excluding {{Code|GET%rest:path}}, and {{Code|POST%rest:error}}.* In the example, …it is assumed that a logged in user is bound to a session variable (see further below)|}.

The permission layer was designed to provide as much flexibility as possible to the web application developer. Some extreme cases: * It is possible to completely work without permission strings, and realize all access checks based on the request information (path, method, and properties returned by the [[Request Module]]).* Each It is also possible (but rather unhandy) to accompany each RESTXQ function can be accompanied by its individual security function. The bare minimum is a single {{Code|%perm:check}} function. Without this function, existing {{Code|%perm:allow}} annotations will be ignored.

There are numerous ways how users can be authenticated in a web application (via OAuth, LDAP, …). The approach demonstrated in on this article page is very straight-forwardpretty basic and straightforward:

<pre classsyntaxhighlight lang="brush:xquery">

</presyntaxhighlight>