Authentication and Authorization

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

arangosh> db._users.toArray()

[ 
  { 
    "user" : "root", 
    "userData" : { 
    }, 
    "authData" : { 
      "active" : true, 
      "changePassword" : false, 
      "simple" : { 
        "method" : "sha256", 
        "hash" : "c37b53b70549bb396b2c87cff45771702e977cdc901c83e4b784d1c926baed26", 
        "salt" : "SalL1I4QVCMQozze" 
      } 
    }, 
    "_id" : "_users/1722497", 
    "_rev" : "1722497", 
    "_key" : "1722497" 
  } 
]

Command-Line Options for the Authentication and Authorization

--server.disable-authentication
Setting value to true will turn off authentication on the server side so all clients can execute any action without authorization and privilege checks.
The default value is false.

--server.authenticate-system-only boolean
Controls whether incoming requests need authentication only if they are directed to the ArangoDB’s internal APIs and features, located at /_api/, /_admin/ etc.
IF the flag is set to true, then HTTP authentication is only required for requests going to URLs starting with /_, but not for other URLs. The flag can thus be used to expose a user-made API without HTTP authentication to the outside world, but to prevent the outside world from using the ArangoDB API and the admin interface without authentication. Note that checking the URL is performed after any database name prefix has been removed. That means when the actual URL called is /_db/_system/myapp/myaction, the URL /myapp/myaction will be used for authenticate-system-only check.
The default is false.
Note that authentication still needs to be enabled for the server regularly in order for HTTP authentication to be forced for the ArangoDB API and the web interface. Setting only this flag is not enough.
You can control ArangoDB’s general authentication feature with the --server.disable-authentication flag.

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.

Note: This functionality is not available from within the web interface.

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.

Note: this function will not work from within the web interface

Examples

arangosh> require("org/arangodb/users").save("my-user", "my-secret-password");

{ 
  "user" : "my-user", 
  "active" : true, 
  "extra" : { 
  }, 
  "changePassword" : false, 
  "code" : 201 
}

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

arangosh> require("org/arangodb/users").reload();

Note: this function will not work from within the web interface

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

arangosh> require("org/arangodb/users").document("my-user");

{ 
  "user" : "my-user", 
  "active" : true, 
  "extra" : { 
  }, 
  "changePassword" : false, 
  "code" : 200 
}

Note: this function will not work from within the web interface

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

arangosh> require("org/arangodb/users").replace("my-user", "my-changed-password");

{ 
  "user" : "my-user", 
  "active" : true, 
  "extra" : { 
  }, 
  "changePassword" : false, 
  "code" : 200 
}

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

arangosh> require("org/arangodb/users").update("my-user", "my-secret-password");

{ 
  "user" : "my-user", 
  "active" : true, 
  "extra" : { 
  }, 
  "changePassword" : false, 
  "code" : 200 
}

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

arangosh> require("org/arangodb/users").isValid("my-user", "my-secret-password");

true

Note: this function will not work from within the web interface

all()

users.all()

Fetches all existing ArangoDB users from the database.

Examples

arangosh> require("org/arangodb/users").all();

[ 
  { 
    "user" : "my-user", 
    "active" : true, 
    "extra" : { 
    }, 
    "changePassword" : false 
  }, 
  { 
    "user" : "root", 
    "active" : true, 
    "extra" : { 
    }, 
    "changePassword" : false 
  } 
]

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

arangosh> require("org/arangodb/users").remove("my-user");