Difference between revisions of "User Management"

From BaseX Documentation
Jump to navigation Jump to search
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
 
The user management defines which permissions are required
by a user to perform a specific [[Commands|database command]].
+
by a user to perform a database command or XQuery expression.
  
Permissions are only relevant in the client/server architecture: the [[Standalone Mode]] and the [[GUI]] is run with admin permissions.
+
Permissions are mostly relevant in the client/server architecture, as the
 +
[[Standalone Mode]] and the [[GUI]] is run with admin permissions.
 +
There are a few exceptions such as the [[XQuery Module#xquery:eval|xquery:eval]] function:
 +
its execution scope can also be limited by specifying a permission.
 +
 
 +
With {{Version|8.0}}, the user management has been reworked:
 +
 
 +
* Permissions can be manually edited, as they are now stored as XML.
 +
* The permission file has been moved from the home directory to the database directory. It was renamed from {{Code|.basexperm}} to {{Code|users.xml}}.
 +
* Local permissions are now defined for database glob patterns. Both local and global permissions are stored in the same file.
 +
* A new [[User Module]] was introduced to allow user management via XQuery.
 +
 
 +
==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 exist, which can be assigned to single databases.
 
Local permission have a higher priority and override global permissions.
 
  
All global permissions are stored in the file [[Configuration#Configuration Files|.basexperm]],
+
Local permissions are applied to databases. They have a higher precedence
and local permissions are encoded in the database meta data ([[Storage Layout|inf.basex]]).
+
and override global permissions.
  
 
[[File:perms.png|none|thumb|403px|Permissions hierarchy]]
 
[[File:perms.png|none|thumb|403px|Permissions hierarchy]]
  
User names must follow the [[Valid Names|valid names constraints]].
+
User names must follow the [[Valid Names|valid names constraints]], and the database patterns must follow the [[Commands#Glob_Syntax|Glob Syntax]].
  
 
==Commands==
 
==Commands==
  
Admin permissions are needed to execute all of the following commands:
+
Admin permissions are required to execute all of the following commands:
+
 
'''Creating user 'test' (password will be entered on command line):
+
'''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':'''
+
'''Show detailed information about user 'test' via XQuery:'''
  
<code>&gt; SHOW USERS ON factbook</code>
+
<code>&gt; XQUERY user:list-details()[@name = 'test']</code>
  
'''Dropping of user 'test':'''
+
'''Drop of user 'test' via XQuery:'''
  
<code>&gt; DROP USER test</code>  
+
<code>&gt; XQUERY user:drop('test')</code>  
  
 
[[Category:Server]]
 
[[Category:Server]]
 
[[Category:Internals]]
 
[[Category:Internals]]
 +
 +
=Changelog=
 +
 +
Revised in Version 8.0.

Revision as of 00:08, 11 December 2014

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 Standalone Mode and the GUI 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.

With Version 8.0, the user management has been reworked:

  • Permissions can be manually edited, as they are now stored as XML.
  • The permission file has been moved from the home directory to the database directory. It was renamed from .basexperm to users.xml.
  • Local permissions are now defined for database glob patterns. Both local and global permissions are stored in the same file.
  • A new User Module was introduced to allow user management via XQuery.

Rules

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.

Commands

Admin permissions are required to execute all of the following commands:

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

Show detailed information about user 'test' via XQuery:

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

Drop of user 'test' via XQuery:

> XQUERY user:drop('test')

Changelog

Revised in Version 8.0.