User Management

The user management defines which permissions are required by a user to perform a database command or XQuery expression.

This page describes the database users that BaseX authenticates against. It should not be confused with the Permissions layer, which governs access to RESTXQ functions in web applications.

Permissions are mostly relevant in the client/server architecture, as the Graphical User Interface and the Command-Line Interface are run with admin permissions. There are a few exceptions, such as the xquery:eval function: Its execution scope can also be limited by specifying a permission.

Please take care of usual security measures: ensure that your password will not end up in your command-line history, avoid sending passwords via ordinary REST requests, etc.

Permissions

Five permission levels exist. A higher level includes all lower levels: for example, every user with write permission may also execute commands that require read. read and write can be assigned both globally and locally (per database); create and admin are global only.

Permission	Scope	Description
admin	global	Manage users and administer the server.
create	global	Create and drop databases, access external resources (files, URLs).
write	global, local	Modify and update databases.
read	global, local	Read from and query databases.
none	global, local	No access.

Updated: Permissions are also checked for databases that have already been opened.

Global permissions apply to a user across all databases. Local permissions are applied to individual databases; they have a higher precedence and override the global permissions. If no local permission is set for a database, the global permission is inherited.

Usernames must follow the valid names constraints, and the database patterns must follow the Glob Syntax.

Trusted Code

Added: Code can be untrusted.

In addition to the permissions of the user, code has a maximum permission, which is checked as well. Code is trusted if its maximum permission is create or higher, and untrusted otherwise. Untrusted code cannot access external resources, such as files, URLs or Java classes: an attempt is rejected with err:FODC0016, even if the user has the required permissions. Databases can still be read and updated.

The maximum permission is lowered when code is:

• loaded with fn:load-xquery-module without enabling the trusted option (the code is untrusted), or
• evaluated with xquery:eval and a permission option (the code is restricted to the specified permission).

The maximum permission can only be lowered: it is inherited by code that is loaded or evaluated by restricted code, and it is retained by function items that are returned to the caller.

Algorithms

Added: Password algorithms can be configured via AUTHALGORITHMS, including PBKDF2 encryption.

Removed: The unsalted digest (MD5) algorithm.

The algorithms for which password hashes are stored can be configured via AUTHALGORITHMS, supplied as a comma-separated list in order of priority. Two algorithms are available:

Algorithm	Description
salted-sha256	SHA-256 hash computed with a random salt; used for standard authentication and by client/server logins.
pbkdf2	PBKDF2 with HMAC-SHA256; a slower, brute-force-resistant alternative to salted-sha256.

By default, only salted-sha256 hashes are created. See AUTHALGORITHMS for how hashes are recomputed when the configured algorithms change.

The digest (MD5) hashes of previous versions are ignored when users.xml is parsed, and they are dropped when the file is written next.

Operations

Note that a running BaseX instance will not get notified of changes when you change the permissions with a standalone instance of BaseX (see Concurrent Operations for more details).

Most operations require admin permissions. Users without admin permissions can still view their own user information and change their own password.

XQuery

Various User Functions exist to organize users and their permissions:

Create user test with no permissions:

user:create('test', 'top-secret')

Show detailed information about user test:

user:list-details()[@name = 'test']

Drop user test:

user:drop('test')

Commands

Create new user test:

$ basexclient
Username: admin
Password: ...

> CREATE USER test

The password will be requested on the command line. By default, the user will have no permissions ('none').

Change password of user test to 71x343sd#:

> ALTER PASSWORD test 71x343sd#

If the password is omitted, it will be requested on the command line.

Grant local write permissions to user test:

> GRANT write ON unit* TO test

As a consequence, the test user will only be allowed to access (i.e., read and write) databases starting with the characters unit.

Show all users and their global permissions:

> SHOW USERS

Storage

The permission file users.xml is stored in the database directory. This file can be manually edited; it will be parsed once when BaseX is started.

Changelog

Version 13.0

• Added: Trusted Code: Code can be untrusted.
• Added: Password algorithms can be configured via AUTHALGORITHMS, including PBKDF2 encryption.
• Updated: Permissions: Permissions are also checked for databases that have already been opened.
• Removed: The unsalted digest (MD5) algorithm.

Version 8.0

• Updated: Revised user management.