Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
#. * A path can be specified as first argument: ** The security function will only be called if the path of the client request starts with the specified path. ** In contrast to RESTXQ, all subordinate paths will be accepted as well. ** If no path argument is specified, {{Code|/}} is assigned instead.#. * A variable name can be defined as specified in the second argument. A map with the following keys will be bound to that 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.
no edit summary
This page presents the web application permission layer of BaseX, which can be used along with [[RESTXQ]].
Non-trivial web applications require a user management: Users need to log in to a web site in order to get access to protected pages; Depending on their status (role, user group, …), they can be offered different views; etc. With {{Version|9.0}} of BaseX, a The light-weight permission layer has been added that simplifies permission checks a lot:
* Permission strings can be attached to RESTXQ functions.
With the {{Code|%perm:allow}} annotation, one or more permission strings can be attached to a RESTXQ function:
<pre classsyntaxhighlight lang="brush:xquery">
(:~ Login page (visible to everyone). :)
declare
</html>
};
</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 actually requested function will be evaluated. Two arguments can be specified with the annotation:
An example:
<pre classsyntaxhighlight lang="brush:xquery">
import module namespace Session = 'http://basex.org/modules/session';
return web:redirect('/main')
};
</presyntaxhighlight>
Some notes:
* If several permission functions are available that match the user request, all of them will be called one by oneafter another. The function with the shorted shortest path argument will be called first. Accordingly, in the example, if the {{Code|/main/admin}} URL is requested, all three security functions will be runin the given order.* If a security function raises an error or returns any result XQuery value (which can be e.g. a [[Web Module#web:redirect|redirection or any other XQuery value]] to another web page), no other functions will be invoked. This means that the actually invoked function that has been requested by the client will only be evaluated if all security functions yield no result or and no 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 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.
=Authentication=
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 pretty basic and straightforward:
* A login HTML page allows you to enter your credentials (user name, password).
The following lines of code complete the image:
<pre classsyntaxhighlight lang="brush:xquery">
declare
%rest:path("/login-check")
web:redirect("/")
};
</presyntaxhighlight>
For a full round trip, check out the source code of the [[DBA]] that is bundled with BaseX.
=Changelog=
;Version 9.1
* Added: {{Code|authorization}} value in permissions map variable
The Module was introduced with Version 9.0.
