Bureaucrats, editor, reviewer, Administrators
13,550
edits
Changes
Jump to navigation
Jump to search
* Functions can be annotated with permission strings, and* Global permission functions can be written to ensure that the current user has sufficient permissions.=Preliminaries=
=Introduction=All permission [[XQuery 3.0#Annotations|annotations]] are assigned to the <code><nowiki>http://basex.org/modules/perm</nowiki></code> namespace, which is statically bound to the {{Code|perm}} prefix.
It is completely up to the user which The permission strings are used in an application. The strings may denote ids, users, user groups, applications, or any other realms. ==Checking permissions==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}} will be invoked before the actual target function will be evaluated. Two arguments can be specified with the annotation:==Checking Permissions==
* The first path argument ensures Functions that are marked with {{Code|%perm:check}} are so-called ''Security Functions''. These functions will be invoked before the actually requested function will only be called if the request path starts evaluated. Two arguments can be specified with the given string.* The second argument binds the permission strings of the invoked function, and some other request information, to a variable.annotation:
If several permission functions are available that match * A path can be specified as first argument:** The security function will only be called if the path of the user client requeststarts with the specified path.** In contrast to RESTXQ, all of them subordinate paths will be evaluatedaccepted as well.** If no path argument is specified, {{Code|/}} is assigned instead.* A variable can be specified in the second argument. The function A map with the shorted following keys will be bound to that variable:** {{Code|allow}}: Permission strings attached to the requested function; may be empty.** {{Code|path argument will }}: 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 called firstempty.
</pre>
<pre class="brush:xquery">
let $allow := $map?allow where not(user:list-details($user)/@permission = $perm?allow)
→Checking Permissions
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 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:
* Permission strings can be attached to RESTXQ functions.* With {{Version|9security functions, you can ensure that access to RESTXQ functions will only be granted to clients with sufficient permissions.0}} of BaseX, a light-weight permission layer has been added:
=Annotations=Preliminaries== All permission [[XQuery 3.0#Annotations|annotations]] are assigned to the <code><nowiki>http://basex.org/modules/perm</nowiki></code> namespace, which is statically bound to the {{Code|perm}} prefix.
==Attaching permissionsPermission Strings==
With the {{Code|%perm:allow}} annotation, one or more permission strings can be attached to a RESTXQ function:
<pre class="brush:xquery">
(:~ Public login Login page(visible to everyone). :)declare %rest:path("/") %output:method("html")function local:adminlogin() { <html> Please log in...: <form action="/login-check" method="post"> <input name="name"/> <input type="password" name="pass"/> <input type="submit"/> </form> </html>
};
(:~ Restricted Main page(restricted to logged in users). :)declare %rest:path("/main") %output:method("html")function local:adminmain() { <html> Welcome to the main page!: <a href='/main/admin'>admin area</a>, <a href='/logout'>log out</a>. </html>
};
(:~ Admin page. :)
declare %rest:path("/main/admin") %output:method("html") %perm:allow("admin") function local:admin() { <html> Welcome to the privileged administrator admin page. </html>
};
</pre>
An example:
(:~
: Global permission checks.
: Rejects any usage of the HTTP DELETE method.
:)
declare %perm:check %rest:DELETE function local:check() { let $method := Request:method() where $method != 'GET' return error((), 'Access is restricted denied to GET DELETE method.')
};
(:~
: Permission check: Area for logged-in users.
: Permissions: Admin area.
: Checks if the current user is admin; if not, redirects to the main page.
: @param $map perm map with permission data
:)
declare %perm:check('/main/admin', '{$perm}') function local:check-admin($perm) {
let $user := Session:get('id')
return web:redirect('/main')
};
</pre>
Some notes:
* 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|/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|redirection]] to another web page), no other functions will be invoked. This means that the function that has been requested by the client will only be evaluated if all security functions yield no result 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: 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]]). It is also possible (but rather unhandy) to accompany each RESTXQ function 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 on this page is pretty basic and straightforward:
* A login HTML page allows you to enter your credentials (user name, password).
* A login check function checks if the typed in data matches one of the database users. If the input is valid, a session id will be set, and the user will be redirected to the main page. Otherwise, the redirection points back to the login page.
* A logout page deletes the session id.
The following lines of code complete the image:
<pre class="brush:xquery">
declare
%rest:path("/login-check")
%rest:query-param("name", "{$name}")
%rest:query-param("pass", "{$pass}")
function local:login($name, $pass) {
try {
user:check($name, $pass),
Session:set('id', $name),
web:redirect("/main")
} catch user:* {
web:redirect("/")
}
};
declare
%rest:path("/logout")
function local:logout() {
Session:delete('id'),
web:redirect("/")
};
</pre>
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.
