Difference between revisions of "User Module"

From BaseX Documentation
Jump to navigation Jump to search
(7 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
=Conventions=
 
=Conventions=
  
All functions in this module and errors are assigned to the <code><nowiki>http://basex.org/modules/user</nowiki></code> namespace, which is statically bound to the {{Code|user}} prefix.<br/>
+
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/user</nowiki></code> namespace, which is statically bound to the {{Code|user}} prefix.<br/>
  
 
=Read Operations=
 
=Read Operations=
Line 23: Line 23:
  
 
==user:list==
 
==user:list==
 
{{Mark|Updated with Version 8.5}}: If called by non-admins, will only return the current user.
 
  
 
{| width='100%'
 
{| width='100%'
Line 40: Line 38:
  
 
==user:list-details==
 
==user:list-details==
 
{{Mark|Updated with Version 8.5}}: If called by non-admins, will only return the current user.
 
  
 
{| width='100%'
 
{| width='100%'
Line 89: Line 85:
  
 
==user:check==
 
==user:check==
 
{{Mark|Introduced with Version 8.6}}:
 
  
 
{| width='100%'
 
{| width='100%'
Line 109: Line 103:
  
 
==user:info==
 
==user:info==
 
{{Mark|Introduced with Version 8.6}}:
 
  
 
{| width='100%'
 
{| width='100%'
Line 118: Line 110:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Returns an <code>info</code> element, which contains user-defined information. By default, this element has no contents. It can be modified via [[#user:update-info|user:update-info]].
+
|Returns an <code>info</code> element, which can be used to organize application-specific data. By default, the element has no contents. It can be modified via [[#user:update-info|user:update-info]].
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 223: Line 215:
  
 
==user:update-info==
 
==user:update-info==
 
{{Mark|Introduced with Version 8.6}}:
 
  
 
{| width='100%'
 
{| width='100%'
Line 232: Line 222:
 
|-
 
|-
 
| '''Summary'''
 
| '''Summary'''
|Updates the <code>info</code> element with {{Code|$info}}. This node can be used to organize groups and other enhanced user info.
+
|Updates the <code>info</code> element with {{Code|$info}}. This node can be used to organize application-specific data (groups, enhanced user info, etc.).
 
|-
 
|-
 
| '''Examples'''
 
| '''Examples'''
Line 247: Line 237:
 
let $user := 'john', $pw := '8hKJ@%.c/!0O', $group := 'editor'
 
let $user := 'john', $pw := '8hKJ@%.c/!0O', $group := 'editor'
 
return (
 
return (
   db:create($user, $pw),
+
   user:create($user, $pw),
 
   user:update-info(user:info() update
 
   user:update-info(user:info() update
 
     insert node <user name='{ $user }' group='{ $group }'/> into .
 
     insert node <user name='{ $user }' group='{ $group }'/> into .
Line 260: Line 250:
 
! width="110"|Code
 
! width="110"|Code
 
|Description
 
|Description
 +
|-
 +
|{{Code|admin}}
 +
|The "admin" user cannot be modified.
 +
|-
 +
|{{Code|conflict}}
 +
|A user cannot be both altered and dropped.
 +
|-
 +
|{{Code|equal}}
 +
|Name of old and new user is equal.
 +
|-
 +
|{{Code|local}}
 +
|A local permission can only be 'none', 'read' or 'write'.
 +
|-
 +
|{{Code|logged-in}}
 +
|The specified user is currently logged in.
 
|-
 
|-
 
|{{Code|name}}
 
|{{Code|name}}
 
|The specified user name is invalid.
 
|The specified user name is invalid.
 +
|-
 +
|{{Code|password}}
 +
|The specified password is wrong.
 
|-
 
|-
 
|{{Code|pattern}}
 
|{{Code|pattern}}
Line 272: Line 280:
 
|{{Code|unknown}}
 
|{{Code|unknown}}
 
|The specified user does not exist.
 
|The specified user does not exist.
|-
 
|{{Code|password}}
 
|The specified password is wrong.
 
|-
 
|{{Code|admin}}
 
|The "admin" user cannot be modified.
 
|-
 
|{{Code|equal}}
 
|Name of old and new user is equal.
 
|-
 
|{{Code|local}}
 
|A local permission can only be 'none', 'read' or 'write'.
 
|-
 
|{{Code|logged-in}}
 
|The specified user is currently logged in.
 
 
|-
 
|-
 
|{{Code|update}}
 
|{{Code|update}}
 
|The operation can only be performed once per user or database pattern.
 
|The operation can only be performed once per user or database pattern.
|-
 
|{{Code|conflict}}
 
|A user cannot be both altered and dropped.
 
 
|}
 
|}
  

Revision as of 16:53, 21 November 2017

This XQuery Module contains functions for creating and administering database users. The User Management article gives more information on database users and permissions.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/user namespace, which is statically bound to the user prefix.

Read Operations

user:current

Signatures user:current() as xs:string
Summary Returns the name of the currently logged in user.
Examples
  • If the GUI or the standalone mode is used, user:current() always returns admin.

user:list

Signatures user:list() as xs:string*
Summary Returns the names of all registered users that are visible to the current user.
Examples
  • After a fresh installation, user:list() will only return admin.

user:list-details

Signatures user:list-details() as element(user)*
user:list-details($name as xs:string) as element(user)*
Summary Returns an element sequence, containing all registered users that are visible to the current user.
In addition to the SHOW USERS command, encoded password strings and database permissions will be output. A user $name can be specified to filter the results in advance.
Examples
  • After a fresh installation, user:list-details() returns output similar to the following one:
<user name="admin" permission="admin">
  <password algorithm="digest">
    <hash>304bdfb0383c16f070a897fc1eb25cb4</hash>
  </password>
  <password algorithm="salted-sha256">
    <salt>871602799292195</salt>
    <hash>a065ca66fa3d6da5762c227587f1c8258c6dc08ee867e44a605a72da115dcb41</hash>
  </password>
</user>
Errors unknown: The specified user name is unknown.

user:exists

Signatures user:exists($name as xs:string) as xs:boolean
Summary Checks if a user with the specified $name exists.
Examples
  • user:exists('admin') will always yield true.
Errors name: The specified user name is invalid.

user:check

Signatures user:check($name as xs:string, $password as xs:string) as xs:empty-sequence()
Summary Checks if the specified user and password is correct. Raises errors otherwise.
Examples
  • user:check('admin', 'admin') will raise an error if the admin password was changed.
Errors name: The specified user name is invalid.
unknown: The specified user does not exist.
password: The specified password is wrong.

user:info

Signatures user:info() as element(info)
Summary Returns an info element, which can be used to organize application-specific data. By default, the element has no contents. It can be modified via user:update-info.
Examples
  • After a fresh installation, user:info() returns <info/>.

Updates

Important note: All functions in this section are updating functions: they will not be immediately executed, but queued on the Pending Update List, which will be processed after the actual query has been evaluated. This means that the order in which the functions are specified in the query does usually not reflect the order in which the code will be evaluated.

user:create

Signatures user:create($name as xs:string, $password as xs:string) as empty-sequence()
user:create($name as xs:string, $password as xs:string, $permissions as xs:string*) as empty-sequence()
user:create($name as xs:string, $password as xs:string, $permissions as xs:string*, $patterns as xs:string*) as empty-sequence()
Summary Creates a new user with the specified $name, $password, and $permissions. Local permissions are granted with non-empty glob $patterns. The default global permission (none) can be overwritten with an empty pattern or by omitting the last argument. Existing users will be overwritten.
Examples
  • user:create('John', '7e$j#!1', 'admin') creates a new user 'John' with admin permissions.
  • user:create('Jack', 'top!secret', 'read', 'index*') creates a new user 'Jack' with no permissions, but write permissions for databases starting with the letters 'index'.
Errors name: The specified user name is invalid.
permission: The specified permission is invalid.
admin: The "admin" user cannot be modified.
logged-in: The specified user is currently logged in.
update: The operation can only be performed once per user or database pattern.

user:grant

Signatures user:grant($name as xs:string, $permissions as xs:string*) as empty-sequence()
user:grant($name as xs:string, $permissions as xs:string*, $patterns as xs:string*) as empty-sequence()
Summary Grants global or local $permissions to a user with the specified $name. Local permissions are granted with non-empty glob $patterns.
Examples
  • user:grant('John', 'create') grants create permissions to the user 'John'.
  • user:grant('John', ('read','write'), ('index*','unit*')) allows John to read all databases starting with the letters 'index', and to write to all databases starting with 'unit'.
Errors unknown: The specified user name is unknown.
name: The specified user name is invalid.
pattern: The specified database pattern is invalid.
permission: The specified permission is invalid.
admin: The "admin" user cannot be modified.
local: A local permission can only be 'none', 'read' or 'write'.
logged-in: The specified user is currently logged in.
update: The operation can only be performed once per user or database pattern.

user:drop

Signatures user:drop($name as xs:string) as empty-sequence()
user:drop($name as xs:string, $patterns as xs:string*) as empty-sequence()
Summary Drops a user with the specified $name. If non-empty glob $patterns are specified, only the database patterns will be dropped.
Examples
  • user:drop('John') drops the user 'John'.
  • user:grant('John', 'unit*') removes the 'unit*' database pattern. If John accesses any of these database, his global permission will be checked again.
Errors unknown: The specified user name is unknown.
name: The specified user name is invalid.
pattern: The specified database pattern is invalid.
admin: The "admin" user cannot be modified.
logged-in: The specified user is currently logged in.
update: The operation can only be performed once per user or database pattern.
conflict: A user cannot be both altered and dropped.

user:alter

Signatures user:alter($name as xs:string, $newname as xs:string) as empty-sequence()
Summary Renames a user with the specified $name to $newname.
Examples
  • user:rename('John', 'Jack') renames the user 'John' to 'Jack'.
Errors unknown: The specified user name is unknown.
name: The specified user name is invalid.
admin: The "admin" user cannot be modified.
logged-in: The specified user is currently logged in.
update: The operation can only be performed once per user or database pattern.
conflict: A user cannot be both altered and dropped.

user:password

Signatures user:password($name as xs:string, $password as xs:string) as empty-sequence()
Summary Changes the password of a user with the specified $name.
Examples
  • user:password('John', ) assigns user 'John' an empty password string.
Errors unknown: The specified user name is unknown.
name: The specified user name is invalid.
update: The operation can only be performed once per user or database pattern.

user:update-info

Signatures user:update-info($info as element(info)) as empty-sequence()
Summary Updates the info element with $info. This node can be used to organize application-specific data (groups, enhanced user info, etc.).
Examples
  • Store initial groups information:
user:update-info(element info {
  for $group in ('editor', 'author', 'writer')
  return element group { $group }
})
  • Assign a group to a new user:
let $user := 'john', $pw := '8hKJ@%.c/!0O', $group := 'editor'
return (
  user:create($user, $pw),
  user:update-info(user:info() update
    insert node <user name='{ $user }' group='{ $group }'/> into .
  )
)

Errors

Code Description
admin The "admin" user cannot be modified.
conflict A user cannot be both altered and dropped.
equal Name of old and new user is equal.
local A local permission can only be 'none', 'read' or 'write'.
logged-in The specified user is currently logged in.
name The specified user name is invalid.
password The specified password is wrong.
pattern The specified database name is invalid.
permission The specified permission is invalid.
unknown The specified user does not exist.
update The operation can only be performed once per user or database pattern.

Changelog

Version 8.6
Version 8.4
Version 8.1

The Module was introduced with Version 8.0.