Difference between revisions of "User Management"

From BaseX Documentation
Jump to navigation Jump to search
(Valid user names.)
 
(34 intermediate revisions by 3 users not shown)
Line 1: Line 1:
This article is part of the [[Advanced User's Guide]].
+
This article is part of the [[Advanced User's Guide]]. The user management defines which permissions are required by a user to perform a database command or XQuery expression.
The user management defines which permissions are required
+
 
by a user to perform a specific [[Commands|database command]].
+
Permissions are mostly relevant in the client/server architecture, as the [[GUI]] and the [[Command-Line Client]] is run with admin permissions. There are a few exceptions such as the {{Function|XQuery|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 bash history, avoid sending passwords via ordinary REST requests, etc.
 +
 
 +
==Rules==
  
 
In the permission hierarchy below, the existing permissions are illustrated.
 
In the permission hierarchy below, the existing permissions are illustrated.
 
A higher permission includes all lower permissions.
 
A higher permission includes all lower permissions.
For example, all users who have the <code>WRITE</code> permission assigned
+
For example, all users who have the <code>write</code> permission assigned
will also be able to execute commands requiring <code>READ</code> permission.
+
will also be able to execute commands requiring <code>read</code> permission.
Next, local permissions can be assigned to databases, which override global
+
 
user settings.
+
Local permissions are applied to databases. They have a higher precedence
 +
and override global permissions.
  
[[File:perms.png|none|thumb|200px|Permissions hierarchy]]
+
[[File:perms.png|Permissions hierarchy]]
  
Valid user names may contain letters, numbers,
+
User names must follow the [[Valid Names|valid names constraints]], and the database patterns must follow the [[Commands#Glob_Syntax|Glob Syntax]].
underslashes and dashes (defined by the regular expression <code>[_-a-zA-Z0-9]+</code>).
 
  
==Commands==
+
==Operations==
  
Admin permissions are needed to execute all of the following commands:
+
For all operations, admin permissions are required:
+
 
'''Creating user 'test' (password will be entered on command line):
+
=Commands=
 +
 
 +
'''Create user 'test' (password will be entered on command line). By default, the user will have no permissions ('none'):
  
 
<code>&gt; CREATE USER test</code>  
 
<code>&gt; CREATE USER test</code>  
  
'''Change user 'test' password (password will be entered on command line):
+
'''Change password of user 'test' to '71x343sd#':
  
<code>&gt; ALTER USER test</code>  
+
<code>&gt; ALTER PASSWORD test 71x343sd#</code>  
 
   
 
   
As global permissions, you can set 'none', 'read', 'write', 'create' and 'admin':
+
'''Grant local write permissions to user 'test': '''
 
'''Grant all permissions to user 'test': '''
 
  
<code>&gt; GRANT admin TO test</code>
+
<code>&gt; GRANT write ON unit* TO test</code>  
 
Valid local permissions are 'none', 'read' and 'write':
 
 
'''Granting write permission on database 'factbook' to user 'test': '''
 
 
 
<code>&gt; GRANT write ON factbook TO test</code>  
 
  
 
Note: Local permissions overwrite global permissions.
 
Note: Local permissions overwrite global permissions.
As a consequence, the 'test' user will only be allowed to
+
As a consequence, the 'test' user will only be allowed to access (i.e., read and write)
access (i.e., read and write) the 'factbook' database.
+
database starting with the letters 'unit'. If no local permissions are set,
If no local permissions are set, the global rights are
+
the global rights are inherited.
inherited.
 
 
   
 
   
'''Showing global permissions:'''
+
'''Show global permissions:'''
  
 
<code>&gt; SHOW USERS</code>  
 
<code>&gt; SHOW USERS</code>  
 
'''Showing local permissions on database 'factbook':'''
 
  
<code>&gt; SHOW USERS ON factbook</code>
+
==XQuery==
 +
 
 +
The available user functions are listed in the [[User Module]]:
 +
 
 +
'''Create user 'test' with no permissions:'''
 +
 
 +
<code>user:create('test', 'top-secret')</code>
 +
 
 +
'''Show detailed information about user 'test':'''
 +
 
 +
<code>user:list-details()[@name = 'test']</code>
 +
 
 +
'''Drop user 'test':'''
 +
 
 +
<code>user:drop('test')</code>
 +
 
 +
=Storage=
 +
 
 +
The permission file {{Code|users.xml}} is stored in the database directory. This file can be manually edited; it will be parsed once when BaseX is started.
  
'''Dropping of user 'test':'''
+
Salted SHA256 hashes are used for authentication (the current timestamp will be used as salt). Additionally, digest hashes are used in the client/server architecture and the [[Clients|Language Bindings]], and in the [[Web Application|HTTP Context]] if {{Option|AUTHMETHOD}} is set to {{Code|Digest}}.
  
<code>&gt; DROP USER test</code>
+
=Changelog=
  
[[Category:Server]]
+
Revised in Version 8.0.

Latest revision as of 19:39, 18 July 2022

This article is part of the Advanced User's Guide. The user management defines which permissions are required by a user to perform a database command or XQuery expression.

Permissions are mostly relevant in the client/server architecture, as the GUI and the Command-Line Client is 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 bash history, avoid sending passwords via ordinary REST requests, etc.

Rules[edit]

In the permission hierarchy below, the existing permissions are illustrated. A higher permission includes all lower permissions. For example, all users who have the write permission assigned will also be able to execute commands requiring read permission.

Local permissions are applied to databases. They have a higher precedence and override global permissions.

Permissions hierarchy

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

Operations[edit]

For all operations, admin permissions are required:

Commands[edit]

Create user 'test' (password will be entered on command line). By default, the user will have no permissions ('none'):

> CREATE USER test

Change password of user 'test' to '71x343sd#':

> ALTER PASSWORD test 71x343sd#

Grant local write permissions to user 'test':

> GRANT write ON unit* TO test

Note: Local permissions overwrite global permissions. As a consequence, the 'test' user will only be allowed to access (i.e., read and write) database starting with the letters 'unit'. If no local permissions are set, the global rights are inherited.

Show global permissions:

> SHOW USERS

XQuery[edit]

The available user functions are listed in the User Module:

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

Storage[edit]

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.

Salted SHA256 hashes are used for authentication (the current timestamp will be used as salt). Additionally, digest hashes are used in the client/server architecture and the Language Bindings, and in the HTTP Context if AUTHMETHOD is set to Digest.

Changelog[edit]

Revised in Version 8.0.