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.
write	global, local	Modify and update databases.
read	global, local	Read from and query databases.
none	global, local	No access.

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.

Algorithms

The algorithms for which password hashes are stored can be configured via AUTHALGORITHMS, supplied as a comma-separated list in order of priority. Three 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.
digest	MD5 hash required by Clients of Version 8 to 12, and by the HTTP Context if AUTHMETHOD is set to Digest. As the hash is unsalted and equivalent to the password itself, it is not stored by default.

By default, only salted-sha256 hashes are created. When the configured algorithms change, the hashes of the listed algorithms are transparently recomputed on a user's next password-based login; hashes of other algorithms are preserved, as they were computed from the same password. Client/server and HTTP digest logins cannot trigger this, as they never reveal the plain-text password.

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).

For all operations, admin permissions are required:

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: Password algorithms can be configured via AUTHALGORITHMS, including PBKDF2 encryption.
• Updated: The unsalted digest hash is no longer stored by default.

Version 8.0

• Updated: Revised user management.