diff --git a/Documentation/Books/Manual/Administration/Configuration/Authentication.mdpp b/Documentation/Books/Manual/Administration/Configuration/Authentication.mdpp deleted file mode 100644 index 5845102295..0000000000 --- a/Documentation/Books/Manual/Administration/Configuration/Authentication.mdpp +++ /dev/null @@ -1,232 +0,0 @@ -!CHAPTER Authentication and Authorization - -!SUBSECTION Authentication and Authorization - -ArangoDB only provides a very simple authentication interface and no -authorization. We plan to add authorization features in later releases, which -will allow the administrator to restrict access to collections and queries to -certain users, given them either read or write access. - -Currently, you can only secure the access to ArangoDB in an all-or-nothing -fashion. The collection *_users* contains all users and a salted SHA256 hash -of their passwords. A user can be active or inactive. A typical document of this -collection is - - @startDocuBlockInline USER_01_authFetch - @EXAMPLE_ARANGOSH_OUTPUT{USER_01_authFetch} - db._users.toArray() - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_01_authFetch - -!SUBSECTION Command-Line Options for the Authentication and Authorization - - -@startDocuBlock server_authentication - - -@startDocuBlock serverAuthenticateSystemOnly - -!SECTION Introduction to User Management - -ArangoDB provides basic functionality to add, modify and remove database users -programmatically. The following functionality is provided by the *users* module -and can be used from inside arangosh and arangod. - -Users can also be managed from within the web interface while logged in to the -*_system* database. - -!SUBSECTION Save - -`users.save(user, passwd, active, extra, changePassword)` - -This will create a new ArangoDB user. The username must be specified in -*user* and must not be empty. - -The password must be given as a string, too, but can be left empty if required. -If you pass the special value *ARANGODB_DEFAULT_ROOT_PASSWORD*, the password -will be set the value stored in the environment variable -`ARANGODB_DEFAULT_ROOT_PASSWORD`. This can be used to pass an instance variable -into ArangoDB. For example, the instance identifier from Amazon. - -If the *active* attribute is not specified, it defaults to *true*. The -*extra* attribute can be used to save custom data with the user. - -If the *changePassword* attribute is not specified, it defaults to *false*. -The *changePassword* attribute can be used to indicate that the user must -change has password before logging in. - -This method will fail if either the username or the passwords are not specified -or given in a wrong format, or there already exists a user with the specified -name. - -The new user account can only be used after the server is either restarted or -the server authentication cache is [reloaded](#reload). - -**Note**: this function will not work from within the web interface - -*Examples* - - @startDocuBlockInline USER_02_saveUser - @EXAMPLE_ARANGOSH_OUTPUT{USER_02_saveUser} - require("@arangodb/users").save("my-user", "my-secret-password"); - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_02_saveUser - -!SUBSECTION Reload - -`users.reload()` - -Reloads the user authentication data on the server - -All user authentication data is loaded by the server once on startup only and is -cached after that. When users get added or deleted, a cache flush is required, -and this can be performed by called this method. - -*Examples* - - @startDocuBlockInline USER_03_reloadUser - @EXAMPLE_ARANGOSH_OUTPUT{USER_03_reloadUser} - require("@arangodb/users").reload(); - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_03_reloadUser - -**Note**: this function will not work from within the web interface - - -!SUBSECTION Document - -`users.document(user)` - -Fetches an existing ArangoDB user from the database. - -The username must be specified in *user*. - -This method will fail if the user cannot be found in the database. - -*Examples* - - @startDocuBlockInline USER_04_documentUser - @EXAMPLE_ARANGOSH_OUTPUT{USER_04_documentUser} - require("@arangodb/users").document("my-user"); - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_04_documentUser - -**Note**: this function will not work from within the web interface - -!SUBSECTION Replace - -`users.replace(user, passwd, active, extra, changePassword)` - -This will look up an existing ArangoDB user and replace its user data. - -The username must be specified in *user*, and a user with the specified name -must already exist in the database. - -The password must be given as a string, too, but can be left empty if required. - -If the *active* attribute is not specified, it defaults to *true*. The -*extra* attribute can be used to save custom data with the user. - -If the *changePassword* attribute is not specified, it defaults to *false*. -The *changePassword* attribute can be used to indicate that the user must -change has password before logging in. - -This method will fail if either the username or the passwords are not specified -or given in a wrong format, or if the specified user cannot be found in the -database. - -**Note**: this function will not work from within the web interface - -*Examples* - - @startDocuBlockInline USER_03_replaceUser - @EXAMPLE_ARANGOSH_OUTPUT{USER_03_replaceUser} - require("@arangodb/users").replace("my-user", "my-changed-password"); - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_03_replaceUser - -!SUBSECTION Update - -`users.update(user, passwd, active, extra, changePassword)` - -This will update an existing ArangoDB user with a new password and other data. - -The username must be specified in *user* and the user must already exist in -the database. - -The password must be given as a string, too, but can be left empty if required. - -If the *active* attribute is not specified, the current value saved for the -user will not be changed. The same is true for the *extra* and the -*changePassword* attribute. - -This method will fail if either the username or the passwords are not specified -or given in a wrong format, or if the specified user cannot be found in the -database. - -**Note**: this function will not work from within the web interface - -*Examples* - - @startDocuBlockInline USER_04_updateUser - @EXAMPLE_ARANGOSH_OUTPUT{USER_04_updateUser} - require("@arangodb/users").update("my-user", "my-secret-password"); - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_04_updateUser - -!SUBSECTION isValid - -`users.isValid(user, password)` - -Checks whether the given combination of username and password is valid. The -function will return a boolean value if the combination of username and password -is valid. - -Each call to this function is penalized by the server sleeping a random -amount of time. - -*Examples* - - @startDocuBlockInline USER_05_isValidUser - @EXAMPLE_ARANGOSH_OUTPUT{USER_05_isValidUser} - require("@arangodb/users").isValid("my-user", "my-secret-password"); - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_05_isValidUser - -**Note**: this function will not work from within the web interface - -!SUBSECTION all() - -`users.all()` - -Fetches all existing ArangoDB users from the database. - -*Examples* - - @startDocuBlockInline USER_06_AllUsers - @EXAMPLE_ARANGOSH_OUTPUT{USER_06_AllUsers} - require("@arangodb/users").all(); - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_06_AllUsers - -!SUBSECTION Remove - -`users.remove(user)` - -Removes an existing ArangoDB user from the database. - -The username must be specified in *User* and the specified user must exist in -the database. - -This method will fail if the user cannot be found in the database. - -**Note**: this function will not work from within the web interface - -*Examples* - - @startDocuBlockInline USER_07_removeUser - @EXAMPLE_ARANGOSH_OUTPUT{USER_07_removeUser} - require("@arangodb/users").remove("my-user"); - @END_EXAMPLE_ARANGOSH_OUTPUT - @endDocuBlock USER_07_removeUser - diff --git a/Documentation/Books/Manual/Administration/ManagingUsers.mdpp b/Documentation/Books/Manual/Administration/ManagingUsers.mdpp index f554ff896a..33815aecc0 100644 --- a/Documentation/Books/Manual/Administration/ManagingUsers.mdpp +++ b/Documentation/Books/Manual/Administration/ManagingUsers.mdpp @@ -29,9 +29,205 @@ arangosh> users.grantDatabase("admin@testapp", "testdb"); This grants the user access to the database *testdb*. `revokeDatabase` will revoke the right. +!SUBSECTION Save + +`users.save(user, passwd, active, extra)` + +This will create a new ArangoDB user. The username must be specified in +*user* and must not be empty. + +The password must be given as a string, too, but can be left empty if required. +If you pass the special value *ARANGODB_DEFAULT_ROOT_PASSWORD*, the password +will be set the value stored in the environment variable +`ARANGODB_DEFAULT_ROOT_PASSWORD`. This can be used to pass an instance variable +into ArangoDB. For example, the instance identifier from Amazon. + +If the *active* attribute is not specified, it defaults to *true*. The +*extra* attribute can be used to save custom data with the user. + +This method will fail if either the username or the passwords are not specified +or given in a wrong format, or there already exists a user with the specified +name. + +**Note**: the user will not have permission to access any database. You need to +grant the access rights for one or more databases using +[grantDatabase](#grant-database). + +*Examples* + + @startDocuBlockInline USER_02_saveUser + @EXAMPLE_ARANGOSH_OUTPUT{USER_02_saveUser} + require("@arangodb/users").save("my-user", "my-secret-password"); + @END_EXAMPLE_ARANGOSH_OUTPUT + @endDocuBlock USER_02_saveUser + +!SUBSECTION Grant Database + +`users.grantDatabase(user, database)` + +This grants read/write access to the *database* for the *user*. + +If a user has access rights to the *_system* database, he is considered superuser. + +!SUBSECTION Revoke Database + +`users.revokeDatabase(user, database)` + +This revokes read/write access to the *database* for the *user*. + +!SUBSECTION Replace + +`users.replace(user, passwd, active, extra)` + +This will look up an existing ArangoDB user and replace its user data. + +The username must be specified in *user*, and a user with the specified name +must already exist in the database. + +The password must be given as a string, too, but can be left empty if required. + +If the *active* attribute is not specified, it defaults to *true*. The +*extra* attribute can be used to save custom data with the user. + +This method will fail if either the username or the passwords are not specified +or given in a wrong format, or if the specified user cannot be found in the +database. + +**Note**: this function will not work from within the web interface + +*Examples* + + @startDocuBlockInline USER_03_replaceUser + @EXAMPLE_ARANGOSH_OUTPUT{USER_03_replaceUser} + require("@arangodb/users").replace("my-user", "my-changed-password"); + @END_EXAMPLE_ARANGOSH_OUTPUT + @endDocuBlock USER_03_replaceUser + +!SUBSECTION Update + +`users.update(user, passwd, active, extra)` + +This will update an existing ArangoDB user with a new password and other data. + +The username must be specified in *user* and the user must already exist in +the database. + +The password must be given as a string, too, but can be left empty if required. + +If the *active* attribute is not specified, the current value saved for the +user will not be changed. The same is true for the *extra* attribute. + +This method will fail if either the username or the passwords are not specified +or given in a wrong format, or if the specified user cannot be found in the +database. + +*Examples* + + @startDocuBlockInline USER_04_updateUser + @EXAMPLE_ARANGOSH_OUTPUT{USER_04_updateUser} + require("@arangodb/users").update("my-user", "my-secret-password"); + @END_EXAMPLE_ARANGOSH_OUTPUT + @endDocuBlock USER_04_updateUser + +!SUBSECTION isValid + +`users.isValid(user, password)` + +Checks whether the given combination of username and password is valid. The +function will return a boolean value if the combination of username and password +is valid. + +Each call to this function is penalized by the server sleeping a random +amount of time. + +*Examples* + + @startDocuBlockInline USER_05_isValidUser + @EXAMPLE_ARANGOSH_OUTPUT{USER_05_isValidUser} + require("@arangodb/users").isValid("my-user", "my-secret-password"); + @END_EXAMPLE_ARANGOSH_OUTPUT + @endDocuBlock USER_05_isValidUser + +!SUBSECTION Remove + +`users.remove(user)` + +Removes an existing ArangoDB user from the database. + +The username must be specified in *User* and the specified user must exist in +the database. + +This method will fail if the user cannot be found in the database. + +*Examples* + + @startDocuBlockInline USER_07_removeUser + @EXAMPLE_ARANGOSH_OUTPUT{USER_07_removeUser} + require("@arangodb/users").remove("my-user"); + @END_EXAMPLE_ARANGOSH_OUTPUT + @endDocuBlock USER_07_removeUser + +!SUBSECTION Document + +`users.document(user)` + +Fetches an existing ArangoDB user from the database. + +The username must be specified in *user*. + +This method will fail if the user cannot be found in the database. + +*Examples* + + @startDocuBlockInline USER_04_documentUser + @EXAMPLE_ARANGOSH_OUTPUT{USER_04_documentUser} + require("@arangodb/users").document("my-user"); + @END_EXAMPLE_ARANGOSH_OUTPUT + @endDocuBlock USER_04_documentUser + +!SUBSECTION all() + +`users.all()` + +Fetches all existing ArangoDB users from the database. + +*Examples* + + @startDocuBlockInline USER_06_AllUsers + @EXAMPLE_ARANGOSH_OUTPUT{USER_06_AllUsers} + require("@arangodb/users").all(); + @END_EXAMPLE_ARANGOSH_OUTPUT + @endDocuBlock USER_06_AllUsers + +!SUBSECTION Reload + +`users.reload()` + +Reloads the user authentication data on the server + +All user authentication data is loaded by the server once on startup only and is +cached after that. When users get added or deleted, a cache flush is done +automatically, and this can be performed by called this method. + +*Examples* + + @startDocuBlockInline USER_03_reloadUser + @EXAMPLE_ARANGOSH_OUTPUT{USER_03_reloadUser} + require("@arangodb/users").reload(); + @END_EXAMPLE_ARANGOSH_OUTPUT + @endDocuBlock USER_03_reloadUser + !SECTION Comparison to ArangoDB 2 ArangoDB 2 contained separate users per database. It was not possible to give an user access to two or more databases. This proved impractical. Therefore we switch to a more common user model in ArangoDB 3. + +!SUBSECTION Command-Line Options for the Authentication and Authorization + + +@startDocuBlock server_authentication + + +@startDocuBlock serverAuthenticateSystemOnly diff --git a/Documentation/Books/Manual/SUMMARY.md b/Documentation/Books/Manual/SUMMARY.md index 0894408787..14c5e21acd 100644 --- a/Documentation/Books/Manual/SUMMARY.md +++ b/Documentation/Books/Manual/SUMMARY.md @@ -120,6 +120,7 @@ * [Arangoimp](Administration/Arangoimp.md) * [Arangodump](Administration/Arangodump.md) * [Arangorestore](Administration/Arangorestore.md) + * [Managing Users](Administration/ManagingUsers.md) * [Server Configuration](Administration/Configuration/README.md) * [Arangod options](Administration/Configuration/Arangod.md) * [Write-ahead log options](Administration/Configuration/Wal.md) @@ -127,8 +128,6 @@ * [Cluster options](Administration/Configuration/Cluster.md) * [Logging options](Administration/Configuration/Logging.md) * [Communication options](Administration/Configuration/Communication.md) - * [Authentication](Administration/Configuration/Authentication.md) - * [Managing Users](Administration/ManagingUsers.md) * [Durability](Administration/Durability.md) * [Replication](Administration/Replication/README.md) * [Asynchronous Replication](Administration/Replication/Asynchronous/README.md) diff --git a/Documentation/DocuBlocks/serverAuthenticateSystemOnly.md b/Documentation/DocuBlocks/serverAuthenticateSystemOnly.md index be40e203d1..64ee5c8b13 100644 --- a/Documentation/DocuBlocks/serverAuthenticateSystemOnly.md +++ b/Documentation/DocuBlocks/serverAuthenticateSystemOnly.md @@ -1,6 +1,4 @@ - @startDocuBlock serverAuthenticateSystemOnly -@brief whether or not only requests to internal URLs need authentication `--server.authentication-system-only boolean` Controls whether incoming requests need authentication only if they are diff --git a/Documentation/DocuBlocks/server_authentication.md b/Documentation/DocuBlocks/server_authentication.md index 310618f6b6..e0b155c995 100644 --- a/Documentation/DocuBlocks/server_authentication.md +++ b/Documentation/DocuBlocks/server_authentication.md @@ -1,6 +1,4 @@ - @startDocuBlock server_authentication -@brief disable authentication for ALL client requests `--server.authentication` Setting this option to *false* will turn off authentication on the server side