Difference between revisions of "User Module"
Jump to navigation
Jump to search
m (remove xs: from empty-sequence() on user-check signature) |
|||
(25 intermediate revisions by one other user not shown) | |||
Line 3: | Line 3: | ||
=Conventions= | =Conventions= | ||
− | All functions in this module | + | 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 18: | Line 18: | ||
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
− | |If the GUI or the standalone mode is used, {{Code|user:current()}} always returns {{Code|admin}}. | + | | |
+ | * If the GUI or the standalone mode is used, {{Code|user:current()}} always returns {{Code|admin}}. | ||
|} | |} | ||
Line 29: | Line 30: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns the names of all registered users. | + | |Returns the names of all registered users that are visible to the current user. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * {{Code|user:list()}} | + | * After a fresh installation, {{Code|user:list()}} will only return {{Code|admin}}. |
|} | |} | ||
Line 44: | Line 45: | ||
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Returns an element sequence, containing all registered users | + | |Returns an element sequence, containing all registered users that are visible to the current user.<br/>In addition to the [[Commands#SHOW_USERS|SHOW USERS]] command, encoded password strings and database permissions will be output. A user {{Code|$name}} can be specified to filter the results in advance. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
− | * | + | * After a fresh installation, {{Code|user:list-details()}} returns output similar to the following one: |
<pre class="brush:xml"> | <pre class="brush:xml"> | ||
<user name="admin" permission="admin"> | <user name="admin" permission="admin"> | ||
Line 81: | Line 82: | ||
| '''Errors''' | | '''Errors''' | ||
|{{Error|name|#Errors}} The specified user name is invalid. | |{{Error|name|#Errors}} The specified user name is invalid. | ||
+ | |} | ||
+ | |||
+ | ==user:check== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|user:check|$name as xs:string, $password as xs:string|empty-sequence()}}<br/> | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |Checks if the specified user and password is correct. Raises errors otherwise. | ||
+ | |- | ||
+ | | '''Examples''' | ||
+ | | | ||
+ | * {{Code|user:check('admin', 'admin')}} will raise an error if the admin password was changed. | ||
+ | |- | ||
+ | | '''Errors''' | ||
+ | |{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|unknown|#Errors}} The specified user does not exist.<br/>{{Error|password|#Errors}} The specified password is wrong.<br/> | ||
+ | |} | ||
+ | |||
+ | ==user:info== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|user:info||element(info)}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |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''' | ||
+ | | | ||
+ | * After a fresh installation, {{Code|user:info()}} returns <code><info/></code>. | ||
|} | |} | ||
Line 88: | Line 122: | ||
==user:create== | ==user:create== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|user:create|$name as xs:string, $password as xs:string|empty-sequence()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $ | + | |{{Func|user:create|$name as xs:string, $password as xs:string|empty-sequence()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $permissions as xs:string*|empty-sequence()}}<br/>{{Func|user:create|$name as xs:string, $password as xs:string, $permissions as xs:string*, $patterns as xs:string*|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Creates a new user with the specified {{Code|$name}} | + | |Creates a new user with the specified {{Code|$name}}, {{Code|$password}}, and {{Code|$permissions}}. Local permissions are granted with non-empty glob {{Code|$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''' | | '''Examples''' | ||
| | | | ||
* {{Code|user:create('John', '7e$j#!1', 'admin')}} creates a new user 'John' with admin permissions. | * {{Code|user:create('John', '7e$j#!1', 'admin')}} creates a new user 'John' with admin permissions. | ||
+ | * {{Code|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''' | | '''Errors''' | ||
Line 108: | Line 141: | ||
==user:grant== | ==user:grant== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
|- | |- | ||
| width='120' | '''Signatures''' | | width='120' | '''Signatures''' | ||
− | |{{Func|user:grant|$name as xs:string, $ | + | |{{Func|user:grant|$name as xs:string, $permissions as xs:string*|empty-sequence()}}<br/>{{Func|user:grant|$name as xs:string, $permissions as xs:string*, $patterns as xs:string*|empty-sequence()}} |
|- | |- | ||
| '''Summary''' | | '''Summary''' | ||
− | |Grants | + | |Grants global or local {{Code|$permissions}} to a user with the specified {{Code|$name}}. Local permissions are granted with non-empty glob {{Code|$patterns}}. |
|- | |- | ||
| '''Examples''' | | '''Examples''' | ||
| | | | ||
* {{Code|user:grant('John', 'create')}} grants create permissions to the user 'John'. | * {{Code|user:grant('John', 'create')}} grants create permissions to the user 'John'. | ||
− | * {{Code|user:grant('John', 'write', 'unit*')}} allows John to write to all databases starting with | + | * {{Code|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''' | | '''Errors''' | ||
Line 129: | Line 160: | ||
==user:drop== | ==user:drop== | ||
− | |||
− | |||
{| width='100%' | {| width='100%' | ||
Line 183: | Line 212: | ||
| '''Errors''' | | '''Errors''' | ||
|{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern. | |{{Error|unknown|#Errors}} The specified user name is unknown.<br/>{{Error|name|#Errors}} The specified user name is invalid.<br/>{{Error|update|#Errors}} The operation can only be performed once per user or database pattern. | ||
+ | |} | ||
+ | |||
+ | ==user:update-info== | ||
+ | |||
+ | {| width='100%' | ||
+ | |- | ||
+ | | width='120' | '''Signatures''' | ||
+ | |{{Func|user:update-info|$info as element(info)|empty-sequence()}} | ||
+ | |- | ||
+ | | '''Summary''' | ||
+ | |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''' | ||
+ | | | ||
+ | * Store initial groups information: | ||
+ | <pre class="brush:xquery"> | ||
+ | user:update-info(element info { | ||
+ | for $group in ('editor', 'author', 'writer') | ||
+ | return element group { $group } | ||
+ | }) | ||
+ | </pre> | ||
+ | * Assign a group to a new user: | ||
+ | <pre class="brush:xquery"> | ||
+ | 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 . | ||
+ | ) | ||
+ | ) | ||
+ | </pre> | ||
|} | |} | ||
Line 190: | 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 202: | Line 280: | ||
|{{Code|unknown}} | |{{Code|unknown}} | ||
|The specified user does not exist. | |The specified user does not exist. | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
|- | |- | ||
|{{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. | ||
− | |||
− | |||
− | |||
|} | |} | ||
=Changelog= | =Changelog= | ||
+ | |||
+ | ;Version 8.6 | ||
+ | * Added: [[#user:check|user:check]], [[#user:info|user:info]], [[#user:update-info|user:update-info]]. | ||
+ | * Updated: [[#user:list|user:list]], [[#user:list-details|user:list-details]]: If called by non-admins, will only return the current user. | ||
;Version 8.4 | ;Version 8.4 | ||
− | * Updated: [[#user:create|user:create]], [[#user:grant|user:grant]], [[#user:drop|user:drop]]: support for | + | * Updated: [[#user:create|user:create]], [[#user:grant|user:grant]], [[#user:drop|user:drop]]: extended support for database patterns. |
;Version 8.1 | ;Version 8.1 |
Revision as of 03:07, 11 October 2018
This XQuery Module contains functions for creating and administering database users. The User Management article gives more information on database users and permissions.
Contents
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 |
|
user:list
Signatures | user:list() as xs:string* |
Summary | Returns the names of all registered users that are visible to the current user. |
Examples |
|
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 |
<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 |
|
Errors | name : The specified user name is invalid.
|
user:check
Signatures | user:check($name as xs:string, $password as xs:string) as empty-sequence() |
Summary | Checks if the specified user and password is correct. Raises errors otherwise. |
Examples |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
|
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 |
user:update-info(element info { for $group in ('editor', 'author', 'writer') return element group { $group } })
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
- Added: user:check, user:info, user:update-info.
- Updated: user:list, user:list-details: If called by non-admins, will only return the current user.
- Version 8.4
- Updated: user:create, user:grant, user:drop: extended support for database patterns.
- Version 8.1
- Added: user:current.
The Module was introduced with Version 8.0.